idnits 2.17.1 draft-ietf-storm-iscsi-cons-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. == There are 1 instance of lines with non-RFC3849-compliant IPv6 addresses in the document. If these are example addresses, they should be changed. -- The document has examples using IPv4 documentation addresses according to RFC6890, but does not use any IPv6 documentation addresses. Maybe there should be IPv6 examples, too? -- The abstract seems to indicate that this document obsoletes RFC3720, but the header doesn't have an 'Obsoletes:' line to match this. -- The abstract seems to indicate that this document obsoletes RFC3980, but the header doesn't have an 'Obsoletes:' line to match this. -- The abstract seems to indicate that this document obsoletes RFC5048, but the header doesn't have an 'Obsoletes:' line to match this. -- The abstract seems to indicate that this document obsoletes RFC4850, but the header doesn't have an 'Obsoletes:' line to match this. -- The abstract seems to indicate that this document updates RFC3721, but the header doesn't have an 'Updates:' line to match this. -- The abstract seems to indicate that this document updates RFC3723, but the header doesn't have an 'Updates:' line to match this. -- The abstract seems to indicate that this document updates RFC5048, but the header doesn't have an 'Updates:' line to match this. -- The abstract seems to indicate that this document updates RFC4850, but the header doesn't have an 'Updates:' line to match this. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- 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) -- Looks like a reference, but probably isn't: '1' on line 2908 -- Looks like a reference, but probably isn't: '0' on line 6819 -- Looks like a reference, but probably isn't: '7' on line 6819 == Missing Reference: 'RFC 4850' is mentioned on line 10880, but not defined ** Obsolete undefined reference: RFC 4850 (Obsoleted by RFC 7143) == Missing Reference: 'RFCyyyy' is mentioned on line 10975, but not defined == Missing Reference: 'MaxMissingDPDU' is mentioned on line 12032, but not defined == Missing Reference: 'MaxOutStandingR2T' is mentioned on line 12040, but not defined == Missing Reference: 'MaxMissingSPDU' is mentioned on line 12053, but not defined == Missing Reference: 'MaxSupportedConns' is mentioned on line 12063, but not defined == Unused Reference: 'RFC4850' is defined on line 11166, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'EUI' -- Possible downref: Non-RFC (?) normative reference: ref. 'FC-FS3' -- Possible downref: Non-RFC (?) normative reference: ref. 'OUI' ** Obsolete normative reference: RFC 3454 (Obsoleted by RFC 7564) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5996 (Obsoleted by RFC 7296) -- Possible downref: Non-RFC (?) normative reference: ref. 'SAM2' -- Possible downref: Non-RFC (?) normative reference: ref. 'SAM4' -- Possible downref: Non-RFC (?) normative reference: ref. 'SPC2' -- Possible downref: Non-RFC (?) normative reference: ref. 'SPC3' -- Possible downref: Non-RFC (?) normative reference: ref. 'UML' -- Possible downref: Non-RFC (?) normative reference: ref. 'UNICODE' -- Obsolete informational reference (is this intentional?): RFC 2401 (Obsoleted by RFC 4301) -- Obsolete informational reference (is this intentional?): RFC 2406 (Obsoleted by RFC 4303, RFC 4305) -- Obsolete informational reference (is this intentional?): RFC 2407 (Obsoleted by RFC 4306) -- Obsolete informational reference (is this intentional?): RFC 2409 (Obsoleted by RFC 4306) -- Obsolete informational reference (is this intentional?): RFC 3720 (Obsoleted by RFC 7143) -- Obsolete informational reference (is this intentional?): RFC 4850 (Obsoleted by RFC 7143) -- Obsolete informational reference (is this intentional?): RFC 5046 (Obsoleted by RFC 7145) -- Obsolete informational reference (is this intentional?): RFC 5048 (Obsoleted by RFC 7143) Summary: 4 errors (**), 0 flaws (~~), 10 warnings (==), 31 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Storage Maintenance (storm) WG Mallikarjun Chadalapaka 2 Internet Draft Microsoft 3 draft-ietf-storm-iscsi-cons-08.txt 4 Intended status: Proposed Standard Julian Satran 5 Expires: July 2013 Infinidat Ltd. 6 Obsoletes: RFC3720, RFC3980, RFC4850, RFC5048 7 Updates: RFC3721, RFC3723 Kalman Meth 8 IBM 10 David Black 11 EMC 13 iSCSI Protocol (Consolidated) 15 Status of this Memo 17 This Internet-Draft is submitted to IETF in full conformance with 18 the provisions of BCP 78 and BCP 79. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF), its areas, and its working groups. Note that 22 other groups may also distribute working documents as Internet- 23 Drafts. 25 Internet-Drafts are draft documents valid for a maximum of six 26 months and may be updated, replaced, or obsoleted by other 27 documents at any time. It is inappropriate to use Internet-Drafts 28 as reference material or to cite them other than as "work in 29 progress." 31 The list of current Internet-Drafts can be accessed at 32 http://www.ietf.org/ietf/1id-abstracts.txt 33 The list of Internet-Draft Shadow Directories can be accessed at 34 http://www.ietf.org/shadow.html 36 This Internet-Draft will expire on July 15, 2013. 38 Copyright Notice 40 Copyright (c) 2013 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with 48 respect to this document. Code Components extracted from this 49 document must include Simplified BSD License text as described in 50 Section 4.e of the Trust Legal Provisions and are provided without 51 warranty as described in the Simplified BSD License. 53 Abstract 55 This document describes a transport protocol for SCSI that works 56 on top of TCP. The iSCSI protocol aims to be fully compliant with 57 the standardized SCSI Architecture Model (SAM-2). RFC 3720 58 defined the original iSCSI protocol. RFC 3721 discusses iSCSI 59 Naming examples and discovery techniques. Subsequently, RFC 3980 60 added an additional naming format to iSCSI protocol. RFC 4850 61 followed up by adding a new public extension key to iSCSI. RFC 62 5048 offered a number of clarifications and a few improvements and 63 corrections to the original iSCSI protocol. 65 This document obsoletes RFCs 3720, 3980, 4850 and 5048 by 66 consolidating them into a single document and making additional 67 updates to the consolidated specification. This document also 68 updates RFC 3721 and RFC 3723. The text in this document thus 69 supersedes the text in all the noted RFCs wherever there is a 70 difference in semantics. 72 Note: This version of the draft does not yet incorporate planned 73 resolutions to some Last Call comments regarding Kerberos and 74 IPsec-related security considerations. 76 1. Introduction.................................................... 15 78 2. Acronyms, Definitions and Document Summary...................... 16 79 2.1. Acronyms ...................................................16 80 2.2. Definitions ................................................18 81 2.3. Summary of Changes .........................................25 82 2.4. Conventions ................................................26 83 3. UML Conventions................................................. 27 84 3.1. UML Conventions Overview ...................................27 85 3.2. Multiplicity Notion ........................................27 86 3.3. Class Diagram Conventions ..................................28 87 3.4. Class Diagram Notation for Associations ....................29 88 3.5. Class Diagram Notation for Aggregations ....................30 89 3.6. Class Diagram Notation for Generalizations .................30 90 4. Overview........................................................ 32 91 4.1. SCSI Concepts ............................................... 32 92 4.2. iSCSI Concepts and Functional Overview ...................... 33 93 4.2.1. Layers and Sessions ..................................... 34 94 4.2.2. Ordering and iSCSI Numbering ............................ 35 95 4.2.2.1. Command Numbering and Acknowledging ................. 35 96 4.2.2.2. Response/Status Numbering and Acknowledging ......... 39 97 4.2.2.3. Response Ordering ................................... 40 98 4.2.2.3.1. Need for Response Ordering ...................... 40 99 4.2.2.3.2. Response Ordering Model Description ............. 40 100 4.2.2.3.3. iSCSI Semantics with the Interface Model ........ 41 101 4.2.2.3.4. Current List of Fenced Response Use Cases ....... 42 102 4.2.2.4. Data Sequencing ..................................... 43 103 4.2.3. iSCSI Task Management ................................... 44 104 4.2.3.1. Task Management Overview ............................ 44 105 4.2.3.2. Notion of Affected Tasks ............................ 44 106 4.2.3.3. Standard Multi-task Abort Semantics ................. 45 107 4.2.3.4. FastAbort Multi-task Abort Semantics ................ 46 108 4.2.3.5. Affected Tasks Shared across Standard and FastAbort 109 Sessions ..................................................... 48 110 4.2.3.6. Rationale behind the FastAbort Semantics ............49 111 4.2.4. iSCSI Login .............................................51 112 4.2.5. iSCSI Full Feature Phase ................................52 113 4.2.5.1. Command Connection Allegiance .......................53 114 4.2.5.2. Data Transfer Overview ..............................54 115 4.2.5.3. Tags and Integrity Checks ...........................55 116 4.2.5.4. Task Management .....................................56 117 4.2.6. iSCSI Connection Termination ............................56 118 4.2.7. iSCSI Names .............................................57 119 4.2.7.1. iSCSI Name Properties ...............................58 120 4.2.7.2. iSCSI Name Encoding .................................60 121 4.2.7.3. iSCSI Name Structure ................................61 122 4.2.7.4. Type "iqn." (iSCSI Qualified Name) ..................62 123 4.2.7.5. Type "eui." (IEEE EUI-64 format) ....................64 124 4.2.7.6. Type "naa." - Network Address Authority .............64 125 4.2.8. Persistent State ........................................65 126 4.2.9. Message Synchronization and Steering ....................66 127 4.2.9.1. Sync/Steering and iSCSI PDU Length ..................67 128 4.3. iSCSI Session Types .........................................67 129 4.4. SCSI to iSCSI Concepts Mapping Model ........................68 130 4.4.1. iSCSI Architecture Model ................................69 131 4.4.2. SCSI Architecture Model .................................72 132 4.4.3. Consequences of the Model ...............................74 133 4.4.3.1. I_T Nexus State .....................................75 134 4.4.3.2. Reservations ........................................75 135 4.5. iSCSI UML Model .............................................76 136 4.6. Request/Response Summary ....................................79 137 4.6.1. Request/Response Types Carrying SCSI Payload ............79 138 4.6.1.1. SCSI-Command ........................................79 139 4.6.1.2. SCSI-Response .......................................80 140 4.6.1.3. Task Management Function Request ....................80 141 4.6.1.4. Task Management Function Response ...................81 142 4.6.1.5. SCSI Data-out and SCSI Data-in ......................81 143 4.6.1.6. Ready To Transfer (R2T) .............................82 144 4.6.2. Requests/Responses carrying SCSI and iSCSI Payload ......83 145 4.6.2.1. Asynchronous Message ................................83 147 4.6.3. Requests/Responses Carrying iSCSI Only Payload ..........83 148 4.6.3.1. Text Request and Text Response ......................83 149 4.6.3.2. Login Request and Login Response ....................84 150 4.6.3.3. Logout Request and Response .........................85 151 4.6.3.4. SNACK Request .......................................85 152 4.6.3.5. Reject ..............................................85 153 4.6.3.6. NOP-Out Request and NOP-In Response .................86 154 5. SCSI Mode Parameters for iSCSI.................................. 87 156 6. Login and Full Feature Phase Negotiation........................ 88 157 6.1. Text Format ................................................. 89 158 6.2. Text Mode Negotiation ....................................... 93 159 6.2.1. List negotiations ....................................... 97 160 6.2.2. Simple-value Negotiations ............................... 98 161 6.3. Login Phase ................................................. 99 162 6.3.1. Login Phase Start ...................................... 102 163 6.3.2. iSCSI Security Negotiation ............................. 105 164 6.3.3. Operational Parameter Negotiation During the Login Phase 106 165 6.3.4. Connection Reinstatement ............................... 107 166 6.3.5. Session Reinstatement, Closure, and Timeout ............ 108 167 6.3.5.1. Loss of Nexus Notification .......................... 108 168 6.3.6. Session Continuation and Failure ....................... 109 169 6.4. Operational Parameter Negotiation Outside the Login Phase .. 109 170 7. iSCSI Error Handling and Recovery.............................. 111 171 7.1. Overview .................................................. 111 172 7.1.1. Background ............................................ 111 173 7.1.2. Goals ................................................. 111 174 7.1.3. Protocol Features and State Expectations .............. 112 175 7.1.4. Recovery Classes ...................................... 113 176 7.1.4.1. Recovery Within-command ........................... 114 177 7.1.4.2. Recovery Within-connection ........................ 115 178 7.1.4.3. Connection Recovery ............................... 116 179 7.1.4.4. Session Recovery .................................. 117 180 7.1.5. Error Recovery Hierarchy .............................. 117 181 7.2. Retry and Reassign in Recovery ............................ 119 182 7.2.1. Usage of Retry ........................................ 119 183 7.2.2. Allegiance Reassignment ............................... 120 184 7.3. Usage Of Reject PDU in Recovery ........................... 121 185 7.4. Error Recovery Considerations for Discovery Sessions ...... 122 186 7.4.1. ErrorRecoveryLevel for Discovery Sessions ............. 122 187 7.4.2. Reinstatement Semantics for Discovery Sessions ........ 122 188 7.4.2.1. Unnamed Discovery Sessions ........................ 123 189 7.4.2.2. Named Discovery Session ........................... 124 190 7.4.3. Target PDUs During Discovery .......................... 124 191 7.5. Connection Timeout Management ............................. 124 192 7.5.1. Timeouts on Transport Exception Events ................ 125 193 7.5.2. Timeouts on Planned Decommissioning ................... 125 194 7.6. Implicit Termination of Tasks ............................. 125 195 7.7. Format Errors ............................................. 126 196 7.8. Digest Errors ............................................. 127 197 7.9. Sequence Errors ........................................... 129 198 7.10. Message Error Checking ................................... 129 199 7.11. SCSI Timeouts ............................................ 130 200 7.12. Negotiation Failures ..................................... 131 201 7.13. Protocol Errors .......................................... 131 202 7.14. Connection Failures ...................................... 132 203 7.15. Session Errors ........................................... 133 204 8. State Transitions.............................................. 134 205 8.1. Standard Connection State Diagrams ........................ 134 206 8.1.1. State Descriptions for Initiators and Targets ......... 134 207 8.1.2. State Transition Descriptions for Initiators and Targets 135 208 8.1.3. Standard Connection State Diagram for an Initiator ..... 139 209 8.1.4. Standard Connection State Diagram for a Target ......... 141 210 8.2. Connection Cleanup State Diagram for Initiators and Targets 143 211 8.2.1. State Descriptions for Initiators and Targets .......... 145 212 8.2.2. State Transition Descriptions for Initiators and Targets 146 213 8.3. Session State Diagrams ..................................... 148 214 8.3.1. Session State Diagram for an Initiator ................. 148 215 8.3.2. Session State Diagram for a Target ..................... 149 216 8.3.3. State Descriptions for Initiators and Targets .......... 150 217 8.3.4. State Transition Descriptions for Initiators and Targets 151 218 9. Security Considerations........................................ 153 219 9.1. iSCSI Security Mechanisms .................................. 153 220 9.2. In-band Initiator-Target Authentication .................... 154 221 9.2.1. CHAP Considerations .................................... 155 222 9.2.2. SRP Considerations ..................................... 158 223 9.3. IPsec ...................................................... 158 224 9.3.1. Data Integrity and Authentication ...................... 159 225 9.3.2. Confidentiality ........................................ 160 226 9.3.3. Policy, Security Associations, and Cryptographic Key 227 Management .................................................... 161 228 9.4. Security Considerations for the X#NodeArchitecture Key ..... 162 229 9.5. SCSI Access Control Considerations ......................... 164 230 10. Notes to Implementers......................................... 165 231 10.1. Multiple Network Adapters ................................. 165 232 10.1.1. Conservative Reuse of ISIDs ........................... 165 233 10.1.2. iSCSI Name, ISID, and TPGT Use ........................ 166 234 10.2. Autosense and Auto Contingent Allegiance (ACA) ............ 168 235 10.3. iSCSI Timeouts ............................................ 168 236 10.4. Command Retry and Cleaning Old Command Instances .......... 169 237 10.5. Synch and Steering Layer and Performance .................. 170 238 10.6. Considerations for State-dependent Devices and Long-lasting 239 SCSI Operations ................................................. 170 240 10.6.1. Determining the Proper ErrorRecoveryLevel ............. 171 241 10.7. Multi-task Abort Implementation Considerations ............ 172 242 11. iSCSI PDU Formats............................................. 173 243 11.1. iSCSI PDU Length and Padding .............................. 173 244 11.2. PDU Template, Header, and Opcodes ......................... 173 245 11.2.1. Basic Header Segment (BHS) ............................ 174 246 11.2.1.1. I ................................................. 175 247 11.2.1.2. Opcode ............................................ 175 248 11.2.1.3. Final (F) bit ..................................... 177 249 11.2.1.4. Opcode-specific Fields ............................ 177 250 11.2.1.5. TotalAHSLength .................................... 177 251 11.2.1.6. DataSegmentLength ................................. 177 252 11.2.1.7. LUN ............................................... 177 253 11.2.1.8. Initiator Task Tag ................................ 178 254 11.2.2. Additional Header Segment (AHS) ....................... 178 255 11.2.2.1. AHSType ........................................... 178 256 11.2.2.2. AHSLength ......................................... 179 257 11.2.2.3. Extended CDB AHS .................................. 179 258 11.2.2.4. Bidirectional Expected Read-Data Length AHS ....... 179 259 11.2.3. Header Digest and Data Digest ......................... 180 260 11.2.4. Data Segment .......................................... 180 261 11.3. SCSI Command .............................................. 180 262 11.3.1. Flags and Task Attributes (byte 1) .................... 181 263 11.3.2. CmdSN - Command Sequence Number ....................... 182 264 11.3.3. ExpStatSN ............................................. 183 265 11.3.4. Expected Data Transfer Length ......................... 183 266 11.3.5. CDB - SCSI Command Descriptor Block ................... 184 267 11.3.6. Data Segment - Command Data ........................... 184 268 11.4. SCSI Response ............................................. 184 269 11.4.1. Flags (byte 1) ........................................ 185 270 11.4.2. Status ................................................ 186 271 11.4.3. Response .............................................. 187 272 11.4.4. SNACK Tag ............................................. 188 273 11.4.5. Residual Count ........................................ 188 274 11.4.5.1. Field Semantics ................................... 188 275 11.4.5.2. Residuals Concepts Overview ....................... 189 276 11.4.5.3. SCSI REPORT LUNS and Residual Overflow ............ 189 277 11.4.6. Bidirectional Read Residual Count ..................... 191 278 11.4.7. Data Segment - Sense and Response Data Segment ........ 191 279 11.4.7.1. SenseLength ....................................... 192 280 11.4.7.2. Sense Data ........................................ 192 281 11.4.8. ExpDataSN ............................................. 193 282 11.4.9. StatSN - Status Sequence Number ....................... 193 283 11.4.10. ExpCmdSN - Next Expected CmdSN from this Initiator ... 194 284 11.4.11. MaxCmdSN - Maximum CmdSN from this Initiator ......... 194 285 11.5. Task Management Function Request .......................... 195 286 11.5.1. Function .............................................. 195 287 11.5.2. TotalAHSLength and DataSegmentLength .................. 199 288 11.5.3. LUN ................................................... 199 289 11.5.4. Referenced Task Tag ................................... 199 290 11.5.5. RefCmdSN .............................................. 199 291 11.5.6. ExpDataSN ............................................. 200 292 11.6. Task Management Function Response ......................... 200 293 11.6.1. Response .............................................. 201 294 11.6.2. TotalAHSLength and DataSegmentLength .................. 203 295 11.7. SCSI Data-out & SCSI Data-in .............................. 203 296 11.7.1. F (Final) Bit ......................................... 206 297 11.7.2. A (Acknowledge) bit ................................... 206 298 11.7.3. Flags (byte 1) ........................................ 207 299 11.7.4. Target Transfer Tag and LUN ........................... 208 300 11.7.5. DataSN ................................................ 208 301 11.7.6. Buffer Offset ......................................... 208 302 11.7.7. DataSegmentLength ..................................... 209 303 11.8. Ready To Transfer (R2T) ................................... 210 304 11.8.1. TotalAHSLength and DataSegmentLength .................. 212 305 11.8.2. R2TSN ................................................. 212 306 11.8.3. StatSN ................................................ 212 307 11.8.4. Desired Data Transfer Length and Buffer Offset ........ 212 308 11.8.5. Target Transfer Tag ................................... 212 309 11.9. Asynchronous Message ...................................... 213 310 11.9.1. AsyncEvent ............................................ 214 311 11.9.2. AsyncVCode ............................................ 217 312 11.9.3. LUN ................................................... 217 313 11.9.4. Sense Data and iSCSI Event Data ....................... 217 314 11.9.4.1. SenseLength ....................................... 218 315 11.10. Text Request ............................................. 218 316 11.10.1. F (Final) Bit ........................................ 220 317 11.10.2. C (Continue) Bit ..................................... 220 318 11.10.3. Initiator Task Tag ................................... 220 319 11.10.4. Target Transfer Tag .................................. 220 320 11.10.5. Text ................................................. 221 321 11.11. Text Response ............................................ 222 322 11.11.1. F (Final) Bit ........................................ 223 323 11.11.2. C (Continue) Bit ..................................... 224 324 11.11.3. Initiator Task Tag ................................... 224 325 11.11.4. Target Transfer Tag .................................. 224 326 11.11.5. StatSN ............................................... 225 327 11.11.6. Text Response Data ................................... 225 328 11.12. Login Request ............................................ 225 329 11.12.1. T (Transit) Bit ...................................... 226 330 11.12.2. C (Continue) Bit ..................................... 227 331 11.12.3. CSG and NSG .......................................... 227 332 11.12.4. Version .............................................. 227 333 11.12.4.1. Version-max ...................................... 227 334 11.12.4.2. Version-min ...................................... 228 335 11.12.5. ISID ................................................. 228 336 11.12.6. TSIH ................................................. 230 337 11.12.7. Connection ID - CID .................................. 230 338 11.12.8. CmdSN ................................................ 230 339 11.12.9. ExpStatSN ............................................ 231 340 11.12.10. Login Parameters .................................... 231 341 11.13. Login Response ........................................... 231 342 11.13.1. Version-max .......................................... 232 343 11.13.2. Version-active ....................................... 233 344 11.13.3. TSIH ................................................. 233 345 11.13.4. StatSN ............................................... 233 346 11.13.5. Status-Class and Status-Detail ....................... 233 347 11.13.6. T (Transit) bit ...................................... 237 348 11.13.7. C (Continue) Bit ..................................... 238 349 11.13.8. Login Parameters ..................................... 238 350 11.14. Logout Request ........................................... 238 351 11.14.1. Reason Code .......................................... 241 352 11.14.2. TotalAHSLength and DataSegmentLength ................. 242 353 11.14.3. CID .................................................. 242 354 11.14.4. ExpStatSN ............................................ 242 355 11.14.5. Implicit termination of tasks ........................ 242 356 11.15. Logout Response .......................................... 243 357 11.15.1. Response ............................................. 244 358 11.15.2. TotalAHSLength and DataSegmentLength ................. 245 359 11.15.3. Time2Wait ............................................ 245 360 11.15.4. Time2Retain .......................................... 245 361 11.16. SNACK Request ............................................ 246 362 11.16.1. Type ................................................. 247 363 11.16.2. Data Acknowledgement ................................. 248 364 11.16.3. Resegmentation ....................................... 248 365 11.16.4. Initiator Task Tag ................................... 249 366 11.16.5. Target Transfer Tag or SNACK Tag ..................... 249 367 11.16.6. BegRun ............................................... 250 368 11.16.7. RunLength ............................................ 250 369 11.17. Reject ................................................... 251 370 11.17.1. Reason ............................................... 252 371 11.17.2. DataSN/R2TSN ......................................... 253 372 11.17.3. StatSN, ExpCmdSN and MaxCmdSN ........................ 253 373 11.17.4. Complete Header of Bad PDU ........................... 254 374 11.18. NOP-Out .................................................. 254 375 11.18.1. Initiator Task Tag ................................... 255 376 11.18.2. Target Transfer Tag .................................. 255 377 11.18.3. Ping Data ............................................ 256 378 11.19. NOP-In ................................................... 257 379 11.19.1. Target Transfer Tag .................................. 258 380 11.19.2. StatSN ............................................... 258 381 11.19.3. LUN .................................................. 258 382 12. iSCSI Security Text Keys and Authentication Methods........... 259 383 12.1. AuthMethod ................................................ 259 384 12.1.1. Kerberos .............................................. 261 385 12.1.2. Secure Remote Password (SRP) .......................... 262 386 12.1.3. Challenge Handshake Authentication Protocol (CHAP) .... 263 387 13. Login/Text Operational Text Keys.............................. 266 388 13.1. HeaderDigest and DataDigest .............................. 266 389 13.2. MaxConnections ........................................... 269 390 13.3. SendTargets .............................................. 269 391 13.4. TargetName ............................................... 269 392 13.5. InitiatorName ............................................ 270 393 13.6. TargetAlias .............................................. 271 394 13.7. InitiatorAlias ............................................ 271 395 13.8. TargetAddress ............................................. 272 396 13.9. TargetPortalGroupTag ...................................... 273 397 13.10. InitialR2T ............................................... 273 398 13.11. ImmediateData ............................................ 274 399 13.12. MaxRecvDataSegmentLength ................................. 275 400 13.13. MaxBurstLength ........................................... 276 401 13.14. FirstBurstLength ......................................... 276 402 13.15. DefaultTime2Wait ......................................... 277 403 13.16. DefaultTime2Retain ....................................... 277 404 13.17. MaxOutstandingR2T ........................................ 278 405 13.18. DataPDUInOrder ........................................... 278 406 13.19. DataSequenceInOrder ...................................... 279 407 13.20. ErrorRecoveryLevel ....................................... 279 408 13.21. SessionType .............................................. 280 409 13.22. The Private Extension Key Format ......................... 281 410 13.23. TaskReporting ............................................ 281 411 13.24. iSCSIProtocolLevel Negotiation ........................... 282 412 13.25. Obsoleted Keys ........................................... 282 413 13.26. X#NodeArchitecture ....................................... 283 414 13.26.1. Definition ........................................... 283 415 13.26.2. Implementation Requirements .......................... 284 416 14. Rationale for revised IANA Considerations..................... 285 418 15. IANA Considerations........................................... 287 420 Appendix A. Examples ............................................. 294 421 Read Operation Example .......................................... 294 422 Write Operation Example ......................................... 295 423 R2TSN/DataSN Use Examples ....................................... 295 424 CRC Examples .................................................... 299 425 Appendix B. Login Phase Examples ................................. 301 427 Appendix C. SendTargets Operation ................................ 311 429 Appendix D. Algorithmic Presentation of Error Recovery Classes ... 316 430 D.2.1. Procedure Descriptions ................................. 318 431 Appendix E. Clearing Effects of Various Events on Targets ........ 335 432 1. Introduction 434 The Small Computer Systems Interface (SCSI) is a popular family of 435 protocols for communicating with I/O devices, especially storage 436 devices. SCSI is a client-server architecture. Clients of a SCSI 437 interface are called "initiators". Initiators issue SCSI 438 "commands" to request services from components, logical units of a 439 server known as a "target". A "SCSI transport" maps the client- 440 server SCSI protocol to a specific interconnect. An Initiator is 441 one endpoint of a SCSI transport and a target is the other 442 endpoint. 444 The SCSI protocol has been mapped over various transports, 445 including Parallel SCSI, IPI, IEEE-1394 (firewire) and Fibre 446 Channel. These transports are I/O specific and have limited 447 distance capabilities. 449 The iSCSI protocol defined in this document describes a means of 450 transporting of the SCSI packets over TCP/IP, providing for an 451 interoperable solution which can take advantage of existing 452 Internet infrastructure, Internet management facilities and 453 address distance limitations. 455 2. Acronyms, Definitions and Document Summary 457 2.1. Acronyms 459 Acronym Definition 460 -------------------------------------------------------------- 461 3DES Triple Data Encryption Standard 462 ACA Auto Contingent Allegiance 463 AEN Asynchronous Event Notification 464 AES Advanced Encryption Standard 465 AH Additional Header (not the IPsec AH!) 466 AHS Additional Header Segment 467 API Application Programming Interface 468 ASC Additional Sense Code 469 ASCII American Standard Code for Information Interchange 470 ASCQ Additional Sense Code Qualifier 471 BHS Basic Header Segment 472 CBC Cipher Block Chaining 473 CD Compact Disk 474 CDB Command Descriptor Block 475 CHAP Challenge Handshake Authentication Protocol 476 CID Connection ID 477 CO Connection Only 478 CRC Cyclic Redundancy Check 479 CRL Certificate Revocation List 480 CSG Current Stage 481 CSM Connection State Machine 482 DES Data Encryption Standard 483 DNS Domain Name Server 484 DOI Domain of Interpretation 485 DVD Digital Versatile Disk 486 EDTL Expected Data Transfer Length 487 ESP Encapsulating Security Payload 488 EUI Extended Unique Identifier 489 FFP Full Feature Phase 490 FFPO Full Feature Phase Only 491 Gbps Gigabits per Second 492 HBA Host Bus Adapter 493 HMAC Hashed Message Authentication Code 494 I_T Initiator_Target 496 I_T_L Initiator_Target_LUN 497 IANA Internet Assigned Numbers Authority 498 IB InfiniBand 499 ID Identifier 500 IDN Internationalized Domain Name 501 IEEE Institute of Electrical & Electronics Engineers 502 IETF Internet Engineering Task Force 503 IKE Internet Key Exchange 504 I/O Input-Output 505 IO Initialize Only 506 IP Internet Protocol 507 IPsec Internet Protocol Security 508 IPv4 Internet Protocol Version 4 509 IPv6 Internet Protocol Version 6 510 IQN iSCSI Qualified Name 511 iSCSI Internet SCSI 512 iSER iSCSI Extensions for RDMA 513 ISID Initiator Session ID 514 iSNS Internet Storage Name Service (see [RFC4171]) 515 ITN iSCSI Target Name 516 ITT Initiator Task Tag 517 KRB5 Kerberos V5 518 LFL Lower Functional Layer 519 LTDS Logical-Text-Data-Segment 520 LO Leading Only 521 LU Logical Unit 522 LUN Logical Unit Number 523 MAC Message Authentication Codes 524 NA Not Applicable 525 NAA Network Address Authority 526 NIC Network Interface Card 527 NOP No Operation 528 NSG Next Stage 529 OS Operating System 530 PDU Protocol Data Unit 531 PKI Public Key Infrastructure 532 R2T Ready To Transfer 533 R2TSN Ready To Transfer Sequence Number 534 RDMA Remote Direct Memory Access 535 RFC Request For Comments 536 SAM SCSI Architecture Model 537 SAM2 SCSI Architecture Model - 2 538 SAN Storage Area Network 539 SAS Serial Attached SCSI 540 SCSI Small Computer Systems Interface 541 SLP Service Location Protocol 542 SN Sequence Number 543 SNACK Selective Negative Acknowledgment - also 544 Sequence Number Acknowledgement for data 545 SPDTL SCSI-Presented Data Transfer Length 546 SPKM Simple Public-Key Mechanism 547 SRP Secure Remote Password 548 SSID Session ID 549 SW Session-Wide 550 TCB Task Control Block 551 TCP Transmission Control Protocol 552 TMF Task Management Function 553 TPGT Target Portal Group Tag 554 TSIH Target Session Identifying Handle 555 TTT Target Transfer Tag 556 UA Unit Attention 557 UFL Upper Functional Layer 558 ULP Upper Level Protocol 559 URN Uniform Resource Names 560 UTF Universal Transformation Format 561 WG Working Group 563 2.2. Definitions 565 - Alias: An alias string can also be associated with an iSCSI 566 Node. The alias allows an organization to associate a user- 567 friendly string with the iSCSI Name. However, the alias string is 568 not a substitute for the iSCSI Name. 570 - CID (Connection ID): Connections within a session are identified 571 by a connection ID. It is a unique ID for this connection within 572 the session for the initiator. It is generated by the initiator 573 and presented to the target during login requests and during 574 logouts that close connections. 576 - Connection: A connection is a TCP connection. Communication 577 between the initiator and target occurs over one or more TCP 579 connections. The TCP connections carry control messages, SCSI 580 commands, parameters, and data within iSCSI Protocol Data Units 581 (iSCSI PDUs). 583 - I/O Buffer:A buffer that is used in a SCSI Read or Write 584 operation so SCSI data may be sent from or received into that 585 buffer. For a read or write data transfer to take place for a 586 task, an I/O Buffer is required on the initiator and at least one 587 is required on the 588 target. 590 - INCITS: INCITS stands for InterNational Committee of Information 591 Technology Standards. The INCITS has a broad standardization scope 592 within the field of Information and Communications Technologies 593 (ICT), encompassing storage, processing, transfer, display, 594 management, organization, and retrieval of information. INCITS 595 serves as ANSI's Technical Advisory Group for the ISO/IEC Joint 596 Technical Committee 1 (JTC 1). See http://www.incits.org. 598 - InfiniBand: An I/O architecture originally intended to replace 599 PCI and to address high performance server interconnectivity [IB]. 601 - iSCSI Device: A SCSI Device using an iSCSI service delivery 602 subsystem. Service Delivery Subsystem is defined by [SAM2] as a 603 transport mechanism for SCSI commands and responses. 605 - iSCSI Initiator Name: The iSCSI Initiator Name specifies the 606 worldwide unique name of the initiator. 608 - iSCSI Initiator Node: The "initiator" device. The word 609 "initiator" has been appropriately qualified as either a port or a 610 device in the rest of the document when the context is ambiguous. 611 All unqualified usages of "initiator" refer to an initiator port 612 (or device) depending on the context. 614 - iSCSI Layer: This layer builds/receives iSCSI PDUs and 615 relays/receives them to/from one or more TCP connections that form 616 an initiator-target "session". 618 - iSCSI Name: The name of an iSCSI initiator or iSCSI target. 620 - iSCSI Node: The iSCSI Node represents a single iSCSI initiator 621 or iSCSI target or a single instance of each. There are one or 622 more iSCSI Nodes within a Network Entity. The iSCSI Node is 623 accessible via one or more Network Portals. An iSCSI Node is 624 identified by its iSCSI Name. The separation of the iSCSI Name 625 from the addresses used by and for the iSCSI Node allows multiple 626 iSCSI nodes to use the same address, and the same iSCSI node to 627 use multiple addresses. 629 - iSCSI Target Name: The iSCSI Target Name specifies the worldwide 630 unique name of the target. 632 - iSCSI Target Node: The "target" device. The word "target" has 633 been appropriately qualified as either a port or a device in the 634 rest of the document when the context is ambiguous. All 635 unqualified usages of "target" refer to a target port (or device) 636 depending on the context. 638 - iSCSI Task: An iSCSI task is an iSCSI request for which a 639 response is expected. 641 - iSCSI Transfer Direction: The iSCSI transfer direction is 642 defined with regard to the initiator. Outbound or outgoing 643 transfers are transfers from the initiator to the target, while 644 inbound or incoming transfers are from the target to the 645 initiator. 647 - ISID: The initiator part of the Session Identifier. It is 648 explicitly specified by the initiator during Login. 650 - I_T nexus: According to [SAM2], the I_T nexus is a relationship 651 between a SCSI Initiator Port and a SCSI Target Port. For iSCSI, 652 this relationship is a session, defined as a relationship between 653 an iSCSI Initiator's end of the session (SCSI Initiator Port) and 654 the iSCSI Target's Portal Group. The I_T nexus can be identified 655 by the conjunction of the SCSI port names; that is, the I_T nexus 656 identifier is the tuple (iSCSI Initiator Name + ',i,'+ ISID, iSCSI 657 Target Name + ',t,'+ Portal Group Tag). 659 - I_T_L nexus: An I_T_L nexus is a SCSI concept, and is defined as 660 the relationship between a SCSI Initiator Port, a SCSI Target 661 Port, and a Logical Unit (LU). 663 - NAA: Network Address Authority, a naming format defined by the 664 INCITS T11 Fibre Channel protocols [FC-FS3]. 666 - Network Entity: The Network Entity represents a device or 667 gateway that is accessible from the IP network. A Network Entity 668 must have one or more Network Portals, each of which can be used 669 to gain access to the IP network by some iSCSI Nodes contained in 670 that Network Entity. 672 - Network Portal: The Network Portal is a component of a Network 673 Entity that has a TCP/IP network address and that may be used by 674 an iSCSI Node within that Network Entity for the connection(s) 675 within one of its iSCSI sessions. A Network Portal in an initiator 676 is identified by its IP address. A Network Portal in a target is 677 identified by its IP address and its listening TCP port. 679 - Originator: In a negotiation or exchange, the party that 680 initiates the negotiation or exchange. 682 - PDU (Protocol Data Unit): The initiator and target divide their 683 communications into messages. The term "iSCSI protocol data unit" 684 (iSCSI PDU) is used for these messages. 686 - Portal Groups: iSCSI supports multiple connections within the 687 same session; some implementations will have the ability to 688 combine connections in a session across multiple Network Portals. 689 A Portal Group defines a set of Network Portals within an iSCSI 690 Network Entity that collectively supports the capability of 691 coordinating a session with connections spanning these portals. 692 Not all Network Portals within a Portal Group need participate in 693 every session connected through that Portal Group. One or more 694 Portal Groups may provide access to an iSCSI Node. Each Network 695 Portal, as utilized by a given iSCSI Node, belongs to exactly one 696 portal group within that node. 698 - Portal Group Tag: This 16-bit quantity identifies a Portal Group 699 within an iSCSI Node. All Network Portals with the same portal 700 group tag in the context of a given iSCSI Node are in the same 701 Portal Group. 703 - Recovery R2T: An R2T generated by a target upon detecting the 704 loss of one or more Data-Out PDUs through one of the following 705 means: a digest error, a sequence error, or a sequence reception 706 timeout. A recovery R2T carries the next unused R2TSN, but 707 requests all or part of the data burst that an earlier R2T (with a 708 lower R2TSN) had already requested. 710 - Responder: In a negotiation or exchange, the party that responds 711 to the originator of the negotiation or exchange. 713 - SAS: Serial Attached SCSI. The Serial Attached SCSI (SAS) 714 standard contains both a physical layer compatible with Serial 715 ATA, and protocols for transporting SCSI commands to SAS devices 716 and ATA commands to SATA devices [SAS]. 718 - SCSI Device: This is the SAM2 term for an entity that contains 719 one or more SCSI ports that are connected to a service delivery 720 subsystem and supports a SCSI application protocol. For example, a 721 SCSI Initiator Device contains one or more SCSI Initiator Ports 722 and zero or more application clients. A Target Device contains one 723 or more SCSI Target Ports and one or more device servers and 724 associated logical units. For iSCSI, the SCSI Device is the 725 component within an iSCSI Node that provides the SCSI 726 functionality. As such, there can be, at most, one SCSI Device 727 within a given iSCSI Node. Access to the SCSI Device can only be 728 achieved in an iSCSI normal operational session. The SCSI Device 729 Name is defined to be the iSCSI Name of the node. 731 - SCSI Layer: This builds/receives SCSI CDBs (Command Descriptor 732 Blocks) and relays/receives them with the remaining command 733 execute [SAM2] parameters to/from the iSCSI Layer. 735 - Session: The group of TCP connections that link an initiator 736 with a target form a session (loosely equivalent to a SCSI I-T 737 nexus). TCP connections can be added and removed from a session. 739 Across all connections within a session, an initiator sees one and 740 the same target. 742 - SCSI Port: This is the SAM2 term for an entity in a SCSI Device 743 that provides the SCSI functionality to interface with a service 744 delivery subsystem. For iSCSI, the definition of the SCSI 745 Initiator Port and the SCSI Target Port are different. 747 - SCSI Initiator Port: This maps to the endpoint of an iSCSI 748 normal operational session. An iSCSI normal operational session is 749 negotiated through the login process between an iSCSI initiator 750 node and an iSCSI target node. At successful completion of this 751 process, a SCSI Initiator Port is created within the SCSI 752 Initiator Device. The SCSI Initiator Port Name and SCSI Initiator 753 Port Identifier are both defined to be the iSCSI Initiator Name 754 together with (a) a label that identifies it as an initiator port 755 name/identifier and (b) the ISID portion of the session 756 identifier. 758 - SCSI Port Name: A name consisting of UTF-8 [RFC3629] encoding of 759 Unicode [UNICODE] characters and includes the iSCSI Name + 'i' or 760 't' + ISID or Portal Group Tag. 762 - SCSI-Presented Data Transfer Length (SPDTL): SPDTL is the 763 aggregate data length of the data that the SCSI layer logically 764 "presents" to the iSCSI layer for a Data-In or Data-Out transfer 765 in the context of a SCSI task. For a bidirectional task, there are 766 two SPDTL values -- one for Data-In and one for Data-Out. Note 767 that the notion of "presenting" includes immediate data per the 768 data transfer model in [SAM2], and excludes overlapping data 769 transfers, if any, requested by the SCSI layer. 771 - SCSI Target Port: This maps to an iSCSI Target Portal Group. 773 - SCSI Target Port Name and SCSI Target Port Identifier: These are 774 both defined to be the iSCSI Target Name together with (a) a label 775 that identifies it as a target port name/identifier and (b) the 776 portal group tag. 778 - SSID (Session ID): A session between an iSCSI initiator and an 779 iSCSI target is defined by a session ID that is a tuple composed 780 of an initiator part (ISID) and a target part (Target Portal Group 781 Tag). The ISID is explicitly specified by the initiator at session 782 establishment. The Target Portal Group Tag is implied by the 783 initiator through the selection of the TCP endpoint at connection 784 establishment. The TargetPortalGroupTag key must also be returned 785 by the target as a confimation during connection establishment. 787 - T10: A technical committee within INCITS that develops standards 788 and technical reports on I/O interfaces, particularly the series 789 of SCSI (Small Computer Systems Interface) standards. See 790 http://www.t10.org. 792 - T11: A technical committee within INCITS responsible for 793 standards development in the areas of Intelligent Peripheral 794 Interface (IPI), High-Performance Parallel Interface (HIPPI) and 795 Fibre Channel (FC). See http://www.t11.org. 797 - Target Portal Group Tag: A numerical identifier (16-bit) for an 798 iSCSI Target Portal Group. 800 -Target Transfer Tag (TTT): An iSCSI protocol field used in a few 801 iSCSI PDUs (e.g. R2T, NOP-In) which is always sent from the target 802 to the initiator first and then quoted as a reference in 803 initiator-sent PDUs back to the target relating to the same 804 task/exchange. So effectively, TTT acts as an opaque handle to an 805 existing task/exchange to help target associate the incoming PDUs 806 from the initiator to the proper execution context. 808 - Third-party: A term used in this document as a qualifier to 809 nexus objects (I_T or I_T_L) and iSCSI sessions, to indicate that 810 these objects and sessions reap the side effects of actions that 811 take place in the context of a separate iSCSI session. One 812 example of a third-party session is an iSCSI session discovering 813 that its I_T_L nexus to an LU got reset due to an LU Reset 814 operation orchestrated via a separate I_T nexus. 816 - TSIH (Target Session Identifying Handle): A target assigned tag 817 for a session with a specific named initiator. The target 818 generates it during session establishment. Other than defining it 819 as a 16 bit binary string, its internal format and content are not 820 defined by this protocol but for the all 0 value that is reserved 821 and used by the initiator to indicate a new session. It is given 822 to the target during additional connection establishment for the 823 same session. 825 2.3. Summary of Changes 827 1) Consolidated RFCs 3720, 3980, 4850 and 5048, and made the 828 necessary editorial changes 829 2) iSCSIProtocolLevel is specified as "1" in Section 13.24, and 830 added a related normative reference to [iSCSI-SAM] draft 831 3) Markers and related keys were removed 832 4) SPKM authentication and related keys were removed 833 5) Added a new Section 13.25 on responding to obsoleted keys 834 6) Have explicitly allowed initiator+target implementations 835 throughout the text 836 7) Clarified in Section 4.2.7 that implementations SHOULD NOT 837 rely on SLP-based discovery 838 8) Added UML diagrams and related conventions in Section 3 839 9) FastAbort implementation is made a "SHOULD" requirement in 840 Section 4.2.3.4 from the previous "MUST" requirement. 841 10) Clarified in Section 6.2 that validity of NotUnderstood 842 response depends on iSCSIProtocolLevel 843 11) Required in Section 4.2.7.1 that iSCSI Target Name must be 844 the same as iSCSI Initiator Name for SCSI (composite) devices 845 with both roles 846 12) Changed the "MUST NOT" to "should avoid" in Section 4.2.7.2 847 regarding usage of characters such as punctuation marks in 848 iSCSI Names. 849 13) Updated Section 9.3 to require the following: MUST implement 850 IPsec, 2400-series RFCs (IPsec v2, IKEv1) and SHOULD implement 851 IPsec, 4300-series RFCs (IPsec v3, IKEv2). 852 14) Clarified in Section 10.2 that ACA is a SHOULD requirement 853 only for iSCSI targets 854 15) Prohibited usage of X# name prefix for new public keys in 855 Section 6.2 856 16) Prohibited usage of Y# name prefix for new digest extensions 857 in Section 13.1, and Z# name prefix for new authentication 858 method extensions in Section 12.1 859 17) Added a SHOULD requirement in Section 6.2 that initiators and 860 targets support at least six (6) exchanges during text 861 negotiation. 863 18) Added a clarification that Appendix.C is normative. 865 2.4. Conventions 867 In examples, "I->" and "T->" show iSCSI PDUs sent by the initiator 868 and target respectively. 870 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL 871 NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" 872 in this document are to be interpreted as described in RFC 2119 873 [RFC2119]. 875 3. UML Conventions 877 3.1. UML Conventions Overview 879 The SCSI Architecture Model (SAM) uses class diagrams and object 880 diagrams with notation that is based on the Unified Modeling 881 Language [UML]. Therefore, this document also uses UML to model 882 the relationships for SCSI and iSCSI objects. 884 A treatise on the graphical notation used in UML is beyond the 885 scope of this document. However, given the use of ASCII drawing 886 for UML static class diagrams, a description of the notational 887 conventions used in this document is included in the remainder of 888 this Section. 890 3.2. Multiplicity Notion 892 Not specified The number of instances of an attribute is not 893 specified. 895 1 One instance of the class or attribute exists. 897 0..* Zero or more instances of the class or attribute exist. 899 1..* One or more instances of the class or attribute exist. 901 0..1 Zero or one instance of the class or attribute exists. 903 n..m n to m instances of the class or attribute exist 904 (e.g., 2..8). 906 x, n..m Multiple disjoint instances of the class or 907 attribute exist (e.g., 2, 8..15). 909 3.3. Class Diagram Conventions 911 +--------------+ +--------------+ +--------------+ 912 | Class Name | | Class Name | | Class Name | 913 +--------------+ +--------------+ +--------------+ 914 | | | | 915 +--------------+ +--------------+ 916 | | 917 +--------------+ 918 The previous three diagrams are examples of a class with no 919 attributes and with no operations. 921 +-------------------+ +-------------------+ 922 | Class Name | | Class Name | 923 +-------------------+ +-------------------+ 924 | attribute 01[1] | | attribute 01[1] | 925 | attribute 02[1] | | attribute 02[1] | 926 +-------------------+ +-------------------+ 927 | | 928 +-------------------+ 929 The preceding two diagrams are examples of a class with attributes 930 and with no operations. 932 +------------------------+ 933 | Class Name | 934 +------------------------+ 935 | attribute 01[1..*] | 936 | attribute 02[1] | 937 +------------------------+ 938 | operation 01() | 939 | operation 02() | 940 +------------------------+ 941 The preceding diagram is an example of a class with attributes 942 that have a specified multiplicity and operations. 944 3.4. Class Diagram Notation for Associations 946 +-----------------+ 947 | Class A | 948 +-----------------+ association_name +-----------------+ 949 | attribute 01[1] |<------------------>| Class B | 950 | attribute 02[1] | 1..* 0..1 +-----------------+ 951 +-----------------+ | attribute 03[1] | 952 | operation 1() | +-----------------+ 953 +-----------------+ 954 The preceding diagram is an example where Class A knows about 955 Class B (i.e., read as "Class A association_name ClassB") and 956 Class B knows about Class A (i.e., read as "Class B 957 association_name Class A"). The use of association_name is 958 optional. The multiplicity notation (1..* and 0..1) indicates the 959 number of instances of the object. 961 +--------------------+ 962 | Class A | 963 +--------------------+ +--------------------+ 964 | attribute 01[1] |<-------------| Class B | 965 | attribute 02[1] | 1 0..1 +--------------------+ 966 +--------------------+ | attribute 03[1] | 967 | operation 1() | +--------------------+ 968 +--------------------+ 969 The preceding diagram is an example where Class B knows about 970 Class A (i.e., read as "Class B knows about Class A") but Class A 971 does not know about Class B. 973 +----------------------+ 974 | Class A | 975 +----------------------+ +--------------------+ 976 | attribute 01[1] |----------->| Class B | 977 | attribute 02[1] | 0..* 1 +--------------------+ 978 +----------------------+ | attribute 03[1] | 979 | operation 1() | +--------------------+ 980 +----------------------+ 981 The preceding diagram is an example where Class A knows about 982 Class B (i.e., read as "Class A knows about Class B") but Class B 983 does not know about Class A. 985 3.5. Class Diagram Notation for Aggregations 987 +---------------+ +--------------+ 988 | Class whole |o------------| Class part | 989 +---------------+ +--------------+ 990 The preceding diagram is an example where Class whole is an 991 aggregate that contains Class part and where Class part may 992 continue to exist even if Class whole is removed (i.e., read as 993 "the whole contains the part"). 995 +---------------+ +--------------+ 996 | Class whole |@------------| Class part | 997 +---------------+ +--------------+ 998 The preceding diagram is an example where Class whole is an 999 aggregate that contains Class part where Class part only belongs 1000 to one Class whole, and the Class part does not continue to exist 1001 if the Class whole is removed (i.e., read as "the whole contains 1002 the part"). 1004 +-------------+ 1005 | | 1006 +-------------+ 1007 | | 1008 + =(a)= + 1009 | | 1010 The preceding diagram is an example where there is a constraint 1011 between the associations where the (a) footnote describes the 1012 constraint. 1014 3.6. Class Diagram Notation for Generalizations 1016 +---------------+ 1017 | Superclass | 1018 +-------^-------+ 1019 /_\ 1020 | 1021 +---------------+ 1022 | Subclass | 1023 +---------------+ 1024 The preceding diagram is an example where the subclass is a kind 1025 of superclass. A subclass shares all the attributes and 1026 operations of the superclass (i.e., the subclass inherits from the 1027 superclass). 1029 4. Overview 1031 4.1. SCSI Concepts 1033 The SCSI Architecture Model-2 [SAM2] describes in detail the 1034 architecture of the SCSI family of I/O protocols. This Section 1035 provides a brief background of the SCSI architecture and is 1036 intended to familiarize readers with its terminology. 1038 At the highest level, SCSI is a family of interfaces for 1039 requesting services from I/O devices, including hard drives, tape 1040 drives, CD and DVD drives, printers, and scanners. In SCSI 1041 terminology, an individual I/O device is called a "logical unit" 1042 (LU). 1044 SCSI is a client-server architecture. Clients of a SCSI interface 1045 are called "initiators". Initiators issue SCSI "commands" to 1046 request services from components, logical units, of a server known 1047 as a "target". The "device server" on the logical unit accepts 1048 SCSI commands and processes them. 1050 A "SCSI transport" maps the client-server SCSI protocol to a 1051 specific interconnect. Initiator is one endpoint of a SCSI 1052 transport. The "target" is the other endpoint. A target can 1053 contain multiple Logical Units (LUs). Each Logical Unit has an 1054 address within a target called a Logical Unit Number (LUN). 1056 A SCSI task is a SCSI command or possibly a linked set of SCSI 1057 commands. Some LUs support multiple pending (queued) tasks, but 1058 the queue of tasks is managed by the logical unit. The target uses 1059 an initiator provided "task tag" to distinguish between tasks. 1060 Only one command in a task can be outstanding at any given time. 1062 Each SCSI command results in an optional data phase and a required 1063 response phase. In the data phase, information can travel from the 1064 initiator to target (e.g., WRITE), target to initiator (e.g., 1065 READ), or in both directions. In the response phase, the target 1066 returns the final status of the operation, including any errors. 1068 Command Descriptor Blocks (CDB) are the data structures used to 1069 contain the command parameters that an initiator sends to a 1071 target. The CDB content and structure is defined by [SAM2] and 1072 device-type specific SCSI standards. 1074 4.2. iSCSI Concepts and Functional Overview 1076 The iSCSI protocol is a mapping of the SCSI command, event and 1077 task management model (see [SAM2]) over the TCP protocol. SCSI 1078 commands are carried by iSCSI requests and SCSI responses and 1079 status are carried by iSCSI responses. iSCSI also uses the request 1080 response mechanism for iSCSI protocol mechanisms. 1082 For the remainder of this document, the terms "initiator" and 1083 "target" refer to "iSCSI initiator node" and "iSCSI target node", 1084 respectively (see iSCSI) unless otherwise qualified. 1086 As its title suggests, Section 4 presents an overview of the iSCSI 1087 concepts, and later Sections in the rest of the specification 1088 contain the normative requirements - in many cases covering the 1089 same concepts discussed in Section 4. Such normative requirements 1090 text overrides the overview text in Section 4 if there is a 1091 disagreement between the two. 1093 In keeping with similar protocols, the initiator and target divide 1094 their communications into messages. This document uses the term 1095 "iSCSI protocol data unit" (iSCSI PDU) for these messages. 1097 For performance reasons, iSCSI allows a "phase-collapse". A 1098 command and its associated data may be shipped together from 1099 initiator to target, and data and responses may be shipped 1100 together from targets. 1102 The iSCSI transfer direction is defined with respect to the 1103 initiator. Outbound or outgoing transfers are transfers from an 1104 initiator to a target, while inbound or incoming transfers are 1105 from a target to an initiator. 1107 An iSCSI task is an iSCSI request for which a response is 1108 expected. 1110 In this document "iSCSI request", "iSCSI command", request, or 1111 (unqualified) command have the same meaning. Also, unless 1112 otherwise specified, status, response, or numbered response have 1113 the same meaning. 1115 4.2.1. Layers and Sessions 1117 The following conceptual layering model is used to specify 1118 initiator and target actions and the way in which they relate to 1119 transmitted and received Protocol Data Units: 1121 - The SCSI layer builds/receives SCSI CDBs (Command Descriptor 1122 Blocks) and passes/receives them with the remaining command 1123 execute parameters ([SAM2]) to/from 1125 - the iSCSI layer that builds/receives iSCSI PDUs and 1126 relays/receives them to/from one or more TCP connections; 1127 the group of connections form an initiator-target "session". 1129 Communication between the initiator and target occurs over one or 1130 more TCP connections. The TCP connections carry control messages, 1131 SCSI commands, parameters, and data within iSCSI Protocol Data 1132 Units (iSCSI PDUs). The group of TCP connections that link an 1133 initiator with a target form a session (equivalent to a SCSI I_T 1134 nexus, see Section 4.4.2). A session is defined by a session ID 1135 that is composed of an initiator part and a target part. TCP 1136 connections can be added and removed from a session. Each 1137 connection within a session is identified by a connection ID 1138 (CID). 1140 Across all connections within a session, an initiator sees one 1141 "target image". All target identifying elements, such as LUN, are 1142 the same. A target also sees one "initiator image" across all 1143 connections within a session. Initiator-identifying elements, such 1144 as the Initiator Task Tag, are global across the session 1145 regardless of the connection on which they are sent or received. 1147 iSCSI targets and initiators MUST support at least one TCP 1148 connection and MAY support several connections in a session. For 1149 error recovery purposes, targets and initiators that support a 1150 single active connection in a session SHOULD support two 1151 connections during recovery. 1153 4.2.2. Ordering and iSCSI Numbering 1155 iSCSI uses Command and Status numbering schemes and a Data 1156 sequencing scheme. 1158 Command numbering is session-wide and is used for ordered command 1159 delivery over multiple connections. It can also be used as a 1160 mechanism for command flow control over a session. 1162 Status numbering is per connection and is used to enable missing 1163 status detection and recovery in the presence of transient or 1164 permanent communication errors. 1166 Data sequencing is per command or part of a command (R2T-triggered 1167 sequence) and is used to detect missing data and/or R2T PDUs due 1168 to header digest errors. 1170 Typically, fields in the iSCSI PDUs communicate the Sequence 1171 Numbers between the initiator and target. During periods when 1172 traffic on a connection is unidirectional, iSCSI NOP-Out/In PDUs 1173 may be utilized to synchronize the command and status ordering 1174 counters of the target and initiator. 1176 The iSCSI session abstraction is equivalent to the SCSI I_T nexus, 1177 and the iSCSI session provides an ordered command delivery from 1178 the SCSI initiator to the SCSI target. For detailed design 1179 considerations that led to the iSCSI session model as it is 1180 defined here and how it relates the SCSI command ordering features 1181 defined in SCSI specifications to the iSCSI concepts see 1182 [RFC3783]. 1184 4.2.2.1. Command Numbering and Acknowledging 1186 iSCSI performs ordered command delivery within a session. All 1187 commands (initiator-to-target PDUs) in transit from the initiator 1188 to the target are numbered. 1190 iSCSI considers a task to be instantiated on the target in 1191 response to every request issued by the initiator. A set of task 1192 management operations including abort and reassign (see Section 1193 11.5) may be performed on an iSCSI task - however an abort 1194 operation cannot be performed on a task management operation, and 1195 usage of reassign operation has certain constraints. See Section 1196 11.5.1 for the details. 1198 Some iSCSI tasks are SCSI tasks, and many SCSI activities are 1199 related to a SCSI task ([SAM2]). In all cases, the task is 1200 identified by the Initiator Task Tag for the life of the task. 1202 The command number is carried by the iSCSI PDU as CmdSN (Command- 1203 Sequence-Number). The numbering is session-wide. Outgoing iSCSI 1204 PDUs carry this number. The iSCSI initiator allocates CmdSNs with 1205 a 32-bit unsigned counter (modulo 2**32). Comparisons and 1206 arithmetic on CmdSN use Serial Number Arithmetic as defined in 1207 [RFC1982] where SERIAL_BITS = 32. 1209 Commands meant for immediate delivery are marked with an immediate 1210 delivery flag; they MUST also carry the current CmdSN. CmdSN MUST 1211 NOT advance after a command marked for immediate delivery is sent. 1213 Command numbering starts with the first login request on the first 1214 connection of a session (the leading login on the leading 1215 connection) and CmdSN MUST be incremented by 1, in a Serial Number 1216 Arithmetic sense as defined in [RFC1982], for every non-immediate 1217 command issued afterwards. 1219 If immediate delivery is used with task management commands, these 1220 commands may reach the target before the tasks on which they are 1221 supposed to act. However their CmdSN serves as a marker of their 1222 position in the stream of commands. The initiator and target MUST 1223 ensure that the SCSI task management functions specified in [SAM2] 1224 act in accordance with the [SAM2] specification. For example, both 1225 commands and responses appear as if delivered in order. Whenever 1226 CmdSN for an outgoing PDU is not specified by an explicit rule, 1227 CmdSN will carry the current value of the local CmdSN variable 1228 (see later in this Section). 1230 The means by which an implementation decides to mark a PDU for 1231 immediate delivery or by which iSCSI decides by itself to mark a 1232 PDU for immediate delivery are beyond the scope of this document. 1234 The number of commands used for immediate delivery is not limited 1235 and their delivery to execution is not acknowledged through the 1236 numbering scheme. An iSCSI target MAY reject immediate commands, 1237 e.g., due to lack of resources to accommodate additional commands. 1238 An iSCSI target MUST be able to handle at least one immediate task 1239 management command and one immediate non-task-management iSCSI 1240 command per connection at any time. 1242 In this document, delivery for execution means delivery to the 1243 SCSI execution engine or an iSCSI protocol specific execution 1244 engine (e.g., for text requests with public or private extension 1245 keys involving an execution component). With the exception of the 1246 commands marked for immediate delivery, the iSCSI target layer 1247 MUST deliver the commands for execution in the order specified by 1248 CmdSN. Commands marked for immediate delivery may be delivered by 1249 the iSCSI target layer for execution as soon as detected. iSCSI 1250 may avoid delivering some commands to the SCSI target layer if 1251 required by a prior SCSI or iSCSI action (e.g., CLEAR TASK SET 1252 Task Management request received before all the commands on which 1253 it was supposed to act). 1255 On any connection, the iSCSI initiator MUST send the commands in 1256 increasing order of CmdSN, except for commands that are 1257 retransmitted due to digest error recovery and connection 1258 recovery. 1260 For the numbering mechanism, the initiator and target maintain the 1261 following three variables for each session: 1263 - CmdSN - the current command Sequence Number, advanced by 1 1264 on each command shipped except for commands marked for 1265 immediate delivery (see Section 4.2.2.1). CmdSN always 1266 contains the number to be assigned to the next Command PDU. 1268 - ExpCmdSN - the next expected command by the target. The 1269 target acknowledges all commands up to, but not including, 1270 this number. The initiator treats all commands with CmdSN 1271 less than ExpCmdSN as acknowledged. The target iSCSI layer 1272 sets the ExpCmdSN to the largest non-immediate CmdSN that it 1273 can deliver for execution "plus 1" per [RFC1982]. There 1274 MUST NOT be any holes in the acknowledged CmdSN sequence. 1276 - MaxCmdSN - the maximum number to be shipped. The queuing 1277 capacity of the receiving iSCSI layer is MaxCmdSN - ExpCmdSN 1278 + 1. 1280 The initiator's ExpCmdSN and MaxCmdSN are derived from target-to- 1281 initiator PDU fields. Comparisons and arithmetic on ExpCmdSN and 1282 MaxCmdSN MUST use Serial Number Arithmetic as defined in [RFC1982] 1283 where SERIAL_BITS = 32. 1285 The target MUST NOT transmit a MaxCmdSN that is less than 1286 ExpCmdSN-1. For non-immediate commands, the CmdSN field can take 1287 any value from ExpCmdSN to MaxCmdSN inclusive. The target MUST 1288 silently ignore any non-immediate command outside of this range or 1289 non-immediate duplicates within the range. The CmdSN carried by 1290 immediate commands may lie outside the ExpCmdSN to MaxCmdSN range. 1291 For example, if the initiator has previously sent a non-immediate 1292 command carrying the CmdSN equal to MaxCmdSN, the target window is 1293 closed. For group task management commands issued as immediate 1294 commands, CmdSN indicates the scope of the group action (e.g., on 1295 ABORT TASK SET indicates which commands are to be aborted). 1297 MaxCmdSN and ExpCmdSN fields are processed by the initiator as 1298 follows: 1300 -If the PDU MaxCmdSN is less than the PDU ExpCmdSN-1 (in 1301 Serial Arithmetic Sense), they are both ignored. 1303 -If the PDU MaxCmdSN is greater than the local MaxCmdSN (in 1304 Serial Arithmetic Sense), it updates the local MaxCmdSN; 1305 otherwise, it is ignored. 1307 -If the PDU ExpCmdSN is greater than the local ExpCmdSN (in 1308 Serial Arithmetic Sense), it updates the local ExpCmdSN; 1309 otherwise, it is ignored. 1311 This sequence is required because updates may arrive out of order 1312 (e.g., the updates are sent on different TCP connections). 1314 iSCSI initiators and targets MUST support the command numbering 1315 scheme. 1317 A numbered iSCSI request will not change its allocated CmdSN, 1318 regardless of the number of times and circumstances in which it is 1319 reissued (see Section 7.2.1). At the target, CmdSN is only 1320 relevant while the command has not created any state related to 1321 its execution (execution state); afterwards, CmdSN becomes 1322 irrelevant. Testing for the execution state (represented by 1323 identifying the Initiator Task Tag) MUST precede any other action 1324 at the target. If no execution state is found, it is followed by 1325 ordering and delivery. If an execution state is found, it is 1326 followed by delivery if it has not already been delivered. 1328 If an initiator issues a command retry for a command with CmdSN R 1329 on a connection when the session CmdSN value is Q, it MUST NOT 1330 advance the CmdSN past R + 2**31 -1 unless the connection is no 1331 longer operational (i.e., it has returned to the FREE state, see 1332 Section 8.1.3), the connection has been reinstated (see Section 1333 6.3.4), or a non-immediate command with CmdSN equal or greater 1334 than Q was issued subsequent to the command retry on the same 1335 connection and the reception of that command is acknowledged by 1336 the target (see Section 10.4). 1338 A target command response or Data-in PDU with status MUST NOT 1339 precede the command acknowledgement. However, the acknowledgement 1340 MAY be included in the response or the Data-in PDU. 1342 4.2.2.2. Response/Status Numbering and Acknowledging 1344 Responses in transit from the target to the initiator are 1345 numbered. The StatSN (Status Sequence Number) is used for this 1346 purpose. StatSN is a counter maintained per connection. ExpStatSN 1347 is used by the initiator to acknowledge status. The status 1348 sequence number space is 32-bit unsigned-integers and the 1349 arithmetic operations are the regular mod(2**32) arithmetic. 1351 Status numbering starts with the Login response to the first Login 1352 request of the connection. The Login response includes an initial 1353 value for status numbering (any initial value is valid). 1355 To enable command recovery, the target MAY maintain enough state 1356 information for data and status recovery after a connection 1357 failure. A target doing so can safely discard all of the state 1358 information maintained for recovery of a command after the 1359 delivery of the status for the command (numbered StatSN) is 1360 acknowledged through ExpStatSN. 1362 A large absolute difference between StatSN and ExpStatSN may 1363 indicate a failed connection. Initiators MUST undertake recovery 1364 actions if the difference is greater than an implementation 1365 defined constant that MUST NOT exceed 2**31-1. 1367 Initiators and Targets MUST support the response-numbering scheme. 1369 4.2.2.3. Response Ordering 1371 4.2.2.3.1. Need for Response Ordering 1373 Whenever an iSCSI session is composed of multiple connections, the 1374 Response PDUs (task responses or TMF responses) originating in 1375 the target SCSI layer are distributed onto the multiple 1376 connections by the target iSCSI layer according to iSCSI 1377 connection allegiance rules. This process generally may not 1378 preserve the ordering of the responses by the time they are 1379 delivered to the initiator SCSI layer. 1381 Since ordering is not expected across SCSI responses anyway, this 1382 approach works fine in the general case. However, to address the 1383 special cases where some ordering is desired by the SCSI layer, we 1384 introduce the notion of a "Response Fence": Response Fence is 1385 logically the attribute/property of a SCSI response message handed 1386 off to a target iSCSI layer which indicates that there are special 1387 SCSI-level ordering considerations associated with this particular 1388 response message - whenever Response Fence is set or required on a 1389 SCSI response message, we define the semantics in 4.2.2.3.2 with 1390 respect to target iSCSI layer's handling of such SCSI response 1391 messages. 1393 4.2.2.3.2. Response Ordering Model Description 1395 The target SCSI protocol layer hands off the SCSI response 1396 messages to the target iSCSI layer by invoking the "Send Command 1397 Complete" protocol data service ([SAM2], clause 5.4.2) and "Task 1398 Management Function Executed" ([SAM2], clause 6.9) service. On 1399 receiving the SCSI response message, the iSCSI layer exhibits the 1400 Response Fence behavior for certain SCSI response messages 1401 (Section 4.2.2.3.4 describes the specific instances where the 1402 semantics must be realized). 1404 Whenever the Response Fence behavior is required for a SCSI 1405 response message, the target iSCSI layer MUST ensure that the 1406 following conditions are met in delivering the response message to 1407 the initiator iSCSI layer: 1409 - Response with Response Fence MUST be delivered 1410 chronologically after all the "preceding" responses on the 1411 I_T_L nexus, if the preceding responses are delivered at 1412 all, to the initiator iSCSI layer. 1414 - Response with Response Fence MUST be delivered 1415 chronologically prior to all the "following" responses on 1416 the I_T_L nexus. 1418 The "preceding" and "following" notions refer to the order of 1419 handoff of a response message from the target SCSI protocol layer 1420 to the target iSCSI layer. 1422 4.2.2.3.3. iSCSI Semantics with the Interface Model 1424 Whenever the TaskReporting key (Section 13.23) is negotiated to 1425 ResponseFence or FastAbort for an iSCSI session and the Response 1426 Fence behavior is required for a SCSI response message, the target 1427 iSCSI layer MUST perform the actions described in this Section for 1428 that session. 1430 a) If it is a single-connection session, no special 1431 processing is required. The standard SCSI Response PDU 1432 build and dispatch process happens. 1433 b) If it is a multi-connection session, the target iSCSI 1434 layer takes note of the last-sent and unacknowledged 1435 StatSN on each of the connections in the iSCSI session, 1436 and waits for an acknowledgement (NOP-In PDUs MAY be used 1437 to solicit acknowledgements as needed in order to 1438 accelerate this process) of each such StatSN to clear the 1439 fence. The SCSI response requiring Response Fence 1440 behavior MUST NOT be sent to the initiator before 1441 acknowledgements are received for each of the 1442 unacknowledged StatSNs. 1443 c) The target iSCSI layer must wait for an acknowledgement 1444 of the SCSI Response PDU that carried the SCSI response 1445 requiring the Response Fence behavior. The fence MUST be 1446 considered cleared only after receiving the 1447 acknowledgement. 1448 d) All further status processing for the LU is resumed only 1449 after clearing the fence. If any new responses for the 1450 I_T_L nexus are received from the SCSI layer before the 1451 fence is cleared, those Response PDUs MUST be held and 1452 queued at the iSCSI layer until the fence is cleared. 1454 4.2.2.3.4. Current List of Fenced Response Use Cases 1456 This Section lists the situations in which fenced response 1457 behavior is REQUIRED in iSCSI target implementations. Note that 1458 the following list is an exhaustive enumeration as currently 1459 identified - it is expected that as SCSI protocol specifications 1460 evolve, the specifications will specify when response fencing is 1461 required on a case-by-case basis. 1463 Whenever the TaskReporting key (Section 13.23) is negotiated to 1464 ResponseFence or FastAbort for an iSCSI session, the target iSCSI 1465 layer MUST assume that the Response Fence is required for the 1466 following SCSI completion messages: 1468 1. The first completion message carrying the UA after the 1469 multi-task abort on issuing and third-party sessions. See 1470 Section 4.2.3.2 for related TMF discussion. 1472 2. The TMF Response carrying the multi-task TMF Response on 1473 the issuing session. 1475 3. The completion message indicating ACA establishment on the 1476 issuing session. 1478 4. The first completion message carrying the ACA ACTIVE status 1479 after ACA establishment on issuing and third-party 1480 sessions. 1482 5. The TMF Response carrying the Clear ACA response on the 1483 issuing session. 1485 6. The response to a PERSISTENT RESERVE OUT/PREEMPT AND ABORT 1486 command. 1488 Note: 1489 - Due to the absence of ACA-related fencing requirements in 1490 [RFC3720], initiator implementations SHOULD NOT use ACA on 1491 multi-connection iSCSI sessions with targets complying only 1492 with [RFC3720]. This can be determined via TaskReporting key 1493 (Section 13.23) negotiation - when the negotiation results 1494 in either "RFC3720" or "NotUnderstood". 1496 - Initiators that want to employ ACA on multi-connection iSCSI 1497 sessions SHOULD first assess response-fencing behavior via 1498 negotiating for "ResponseFence" or "FastAbort" value for the 1499 TaskReporting (Section 13.23) key. 1501 4.2.2.4. Data Sequencing 1503 Data and R2T PDUs transferred as part of some command execution 1504 MUST be sequenced. The DataSN field is used for data sequencing. 1505 For input (read) data PDUs, DataSN starts with 0 for the first 1506 data PDU of an input command and advances by 1 for each subsequent 1507 data PDU. For output data PDUs, DataSN starts with 0 for the first 1508 data PDU of a sequence (the initial unsolicited sequence or any 1509 data PDU sequence issued to satisfy an R2T) and advances by 1 for 1510 each subsequent data PDU. R2Ts are also sequenced per command. For 1511 example, the first R2T has an R2TSN of 0 and advances by 1 for 1512 each subsequent R2T. For bidirectional commands, the target uses 1513 the DataSN/R2TSN to sequence Data-In and R2T PDUs in one 1514 continuous sequence (undifferentiated). Unlike command and status, 1515 data PDUs and R2Ts are not acknowledged by a field in regular 1516 outgoing PDUs. Data-In PDUs can be acknowledged on demand by a 1517 special form of the SNACK PDU. Data and R2T PDUs are implicitly 1518 acknowledged by status for the command. The DataSN/R2TSN field 1519 enables the initiator to detect missing data or R2T PDUs. 1521 For any read or bidirectional command, a target MUST issue less 1522 than 2**32 combined R2T and Data-In PDUs. Any output data sequence 1523 MUST contain less than 2**32 Data-Out PDUs. 1525 4.2.3. iSCSI Task Management 1527 4.2.3.1. Task Management Overview 1529 iSCSI task management features allow an initiator to control the 1530 active iSCSI tasks on an operational iSCSI session that it has 1531 with an iSCSI target. Section 11.5 defines the task management 1532 function types that this specification defines - ABORT TASK, ABORT 1533 TASK SET, CLEAR ACA, CLEAR TASK SET, LOGICAL UNIT RESET, TARGET 1534 WARM RESET, TARGET COLD RESET, and TASK REASSIGN. 1536 Out of these function types, ABORT TASK and TASK REASSIGN 1537 functions manage a single active task, whereas ABORT TASK SET, 1538 CLEAR TASK SET, LOGICAL UNIT RESET, TARGET WARM RESET and TARGET 1539 COLD RESET functions can each potentially affect multiple active 1540 tasks. 1542 4.2.3.2. Notion of Affected Tasks 1544 This Section defines the notion of "affected tasks" in multi-task 1545 abort scenarios. Scope definitions in this Section apply to both 1546 the Standard Multi-task Abort semantics (Section 4.2.3.3) and the 1547 FastAbort Multi-task Abort semantics behavior (Section 4.2.3.4). 1549 ABORT TASK SET: All outstanding tasks for the I_T_L nexus 1550 identified by the LUN field in the ABORT TASK SET TMF Request PDU 1551 (Section 11.5). 1553 CLEAR TASK SET: All outstanding tasks in the task set for the LU 1554 identified by the LUN field in the CLEAR TASK SET TMF Request PDU. 1555 See [SPC3] for the definition of a "task set". 1557 LOGICAL UNIT RESET: All outstanding tasks from all initiators for 1558 the LU identified by the LUN field in the LOGICAL UNIT RESET 1559 Request PDU. 1561 TARGET WARM RESET/TARGET COLD RESET: All outstanding tasks from 1562 all initiators across all LUs to which the TMF-issuing session has 1563 access on the SCSI target device hosting the iSCSI session. 1565 Usage: An "ABORT TASK SET TMF Request PDU" in the preceding text 1566 is an iSCSI TMF Request PDU with the "Function" field set to 1567 "ABORT TASK SET" as defined in Section 11.5. Similar usage is 1568 employed for other scope descriptions. 1570 4.2.3.3. Standard Multi-task Abort Semantics 1572 All iSCSI implementations MUST support the protocol behavior 1573 defined in this Section as the default behavior. The execution of 1574 ABORT TASK SET, CLEAR TASK SET, LOGICAL UNIT RESET, TARGET WARM 1575 RESET, and TARGET COLD RESET TMF Requests consists of the 1576 following sequence of actions in the specified order on the 1577 specified party. 1579 The initiator iSCSI layer: 1580 a. MUST continue to respond to each TTT received for the 1581 affected tasks. 1582 b. SHOULD process any responses received for affected tasks in 1583 the normal fashion. This is acceptable because the 1584 responses are guaranteed to have been sent prior to the TMF 1585 response. 1586 c. SHOULD receive the TMF Response concluding all the tasks in 1587 the set of affected tasks unless the initiator has done 1588 something (e.g., LU reset, connection drop) that may 1589 prevent the TMF Response from being sent or received. The 1590 initiator MUST thus conclude all affected tasks as part of 1591 this step in either case, and MUST discard any TMF Response 1592 received after the affected tasks are concluded. 1594 The target iSCSI layer: 1595 a. MUST wait for responses on currently valid target-transfer 1596 tags of the affected tasks from the issuing initiator. MAY 1597 wait for responses on currently valid target-transfer tags 1598 of the affected tasks from third-party initiators. 1599 b. MUST wait (concurrent with the wait in Step a) for all 1600 commands of the affected tasks to be received based on the 1601 CmdSN ordering. SHOULD NOT wait for new commands on third- 1602 party affected sessions -- only the instantiated tasks have 1603 to be considered for the purpose of determining the 1604 affected tasks. In the case of target-scoped requests 1605 (i.e., TARGET WARM RESET and TARGET COLD RESET), all of the 1606 commands that are not yet received on the issuing session 1607 in the command stream however can be considered to have 1608 been received with no command waiting period -- i.e., the 1609 entire CmdSN space up to the CmdSN of the task management 1610 function can be "plugged". 1611 c. MUST propagate the TMF request to and receive the response 1612 from the target SCSI layer. 1613 d. MUST provide the Response Fence behavior for the TMF 1614 Response on the issuing session as specified in Section 1615 4.2.2.3.2. 1616 e. MUST provide the Response Fence behavior on the first post- 1617 TMF Response on third-party sessions as specified in 1618 Section 4.2.2.3.3. If some tasks originate from non-iSCSI 1619 I_T_L nexuses, then the means by which the target ensures 1620 that all affected tasks have returned their status to the 1621 initiator are defined by the specific non-iSCSI transport 1622 protocol(s). 1624 Technically, the TMF servicing is complete in Step d. Data 1625 transfers corresponding to terminated tasks may however still be 1626 in progress on third-party iSCSI sessions even at the end of Step 1627 e. The TMF Response MUST NOT be sent by the target iSCSI layer 1628 before the end of Step d, and MAY be sent at the end of Step d 1629 despite these outstanding data transfers until after Step e. 1631 4.2.3.4. FastAbort Multi-task Abort Semantics 1633 Protocol behavior defined in this Section SHOULD be implemented by 1634 all iSCSI implementations complying with this document, noting 1635 that some steps below may not be compatible with [RFC3720] 1636 semantics. However, protocol behavior defined in this Section MUST 1637 be exhibited by iSCSI implementations on an iSCSI session when 1638 they negotiate the TaskReporting (Section 13.23) key to 1639 "FastAbort" on that session. The execution of ABORT TASK SET, 1640 CLEAR TASK SET, LOGICAL UNIT RESET, TARGET WARM RESET, and TARGET 1641 COLD RESET TMF Requests consists of the following sequence of 1642 actions in the specified order on the specified party. 1644 The initiator iSCSI layer: 1646 a. MUST NOT send any more Data-Out PDUs for affected tasks on 1647 the issuing connection of the issuing iSCSI session once 1648 the TMF is sent to the target. 1649 b. SHOULD process any responses received for affected tasks in 1650 the normal fashion. This is acceptable because the 1651 responses are guaranteed to have been sent prior to the TMF 1652 response. 1653 c. MUST respond to each Async Message PDU with FAST_ABORT 1654 AsyncEvent as defined in Section 11.9. 1655 d. MUST treat the TMF response as terminating all affected 1656 tasks for which responses have not been received, and MUST 1657 discard any responses for affected tasks received after the 1658 TMF response is passed to the SCSI layer (although the 1659 semantics defined in this Section ensure that such an out- 1660 of-order scenario will never happen with a compliant target 1661 implementation). 1663 The target iSCSI layer: 1664 a. MUST wait for all commands of the affected tasks to be 1665 received based on the CmdSN ordering on the issuing 1666 session. SHOULD NOT wait for new commands on third-party 1667 affected sessions - only the instantiated tasks have to be 1668 considered for the purpose of determining the affected 1669 tasks. In the case of target-scoped requests (i.e., TARGET 1670 WARM RESET and TARGET COLD RESET), all the commands that 1671 are not yet received on the issuing session in the command 1672 stream can be considered to have been received with no 1673 command waiting period -- i.e., the entire CmdSN space up 1674 to the CmdSN of the task management function can be 1675 "plugged". 1676 b. MUST propagate the TMF request to and receive the response 1677 from the target SCSI layer. 1678 c. MUST leave all active "affected TTTs" (i.e., active TTTs 1679 associated with affected tasks) valid. 1680 d. MUST send an Asynchronous Message PDU with AsyncEvent=5 1681 (Section 11.9) on: 1682 i) each connection of each third-party session to 1683 which at least one affected task is allegiant if 1684 TaskReporting=FastAbort is operational on that third- 1685 party session, and, 1687 ii) each connection except the issuing connection of 1688 the issuing session that has at least one allegiant 1689 affected task. 1690 If there are multiple affected LUs (say, due to a target 1691 reset), then one Async Message PDU MUST be sent for each 1692 such LU on each connection that has at least one allegiant 1693 affected task. The LUN field in the Asynchronous Message PDU 1694 MUST be set to match the LUN for each such LU. 1695 e. MUST address the Response Fence flag on the TMF Response on 1696 the issuing session as defined in Section 4.2.2.3.3. 1697 f. MUST address the Response Fence flag on the first post-TMF 1698 Response on third-party sessions as defined in Section 1699 4.2.2.3.3. If some tasks originate from non-iSCSI I_T_L 1700 nexuses, then the means by which the target ensures that 1701 all affected tasks have returned their status to the 1702 initiator are defined by the specific non-iSCSI transport 1703 protocol(s). 1704 g. MUST free up the affected TTTs (and STags, if applicable) 1705 and the corresponding buffers, if any, once it receives 1706 each associated NOP-Out acknowledgement that the initiator 1707 generated in response to each Async Message. 1709 Technically, the TMF servicing is complete in Step e. Data 1710 transfers corresponding to terminated tasks may however still be 1711 in progress even at the end of Step f. A TMF Response MUST NOT be 1712 sent by the target iSCSI layer before the end of Step e, and MAY 1713 be sent at the end of Step e despite these outstanding Data 1714 transfers until Step g. Step g specifies an event to free up any 1715 such resources that may have been reserved to support outstanding 1716 data transfers. 1718 4.2.3.5. Affected Tasks Shared across Standard and FastAbort Sessions 1720 If an iSCSI target implementation is capable of supporting 1721 TaskReporting=FastAbort functionality (Section 13.23), it may end 1722 up in a situation where some sessions have TaskReporting=RFC3720 1723 operational (RFC 3720 sessions) while some other sessions have 1724 TaskReporting=FastAbort operational (FastAbort sessions) even 1725 while accessing a shared set of affected tasks (Section 4.2.3.2). 1726 If the issuing session is an RFC 3720 session, the iSCSI target 1727 implementation is FastAbort-capable, and the third-party affected 1728 session is a FastAbort session, the following behavior SHOULD be 1729 exhibited by the iSCSI target layer: 1730 a. Between Steps c and d of the target behavior in Section 1731 4.2.3.3, send an Asynchronous Message PDU with AsyncEvent=5 1732 (Section 11.9) on each connection of each third-party 1733 session to which at least one affected task is allegiant. 1734 If there are multiple affected LUs, then send one Async 1735 Message PDU for each such LU on each connection that has at 1736 least one allegiant affected task. When sent, the LUN field 1737 in the Asynchronous Message PDU MUST be set to match the 1738 LUN for each such LU. 1739 b. After Step e of the target behavior in Section 4.2.3.3, 1740 free up the affected TTTs (and STags, if applicable) and 1741 the corresponding buffers, if any, once each associated 1742 NOP-Out acknowledgement is received that the third-party 1743 initiator generated in response to each Async Message sent 1744 in Step a. 1746 If the issuing session is a FastAbort session, the iSCSI target 1747 implementation is FastAbort-capable, and the third-party affected 1748 session is an RFC 3720 session, iSCSI target layer MUST NOT send 1749 Asynchronous Message PDUs on the third-party session to prompt the 1750 FastAbort behavior. 1752 If the third-party affected session is a FastAbort session and the 1753 issuing session is a FastAbort session, the initiator in the 1754 third-party role MUST respond to each Async Message PDU with 1755 AsyncEvent=5 as defined in Section 11.9. Note that an initiator 1756 MAY thus receive these Async Messages on a third-party affected 1757 session even if the session is a single-connection session. 1759 4.2.3.6. Rationale behind the FastAbort Semantics 1761 There are fundamentally three basic objectives behind the 1762 semantics 1763 specified in Sections 4.2.3.3 and 4.2.3.4. 1764 1. Maintaining an ordered command flow I_T nexus abstraction 1765 to the target SCSI layer even with multi-connection 1766 sessions. 1767 - Target iSCSI processing of a TMF request must 1768 maintain the single flow illusion. Target behavior in 1769 Step b of Section 4.2.3.3 and Step a of Section 4.2.3.4 1770 correspond to this objective. 1771 2. Maintaining a single ordered response flow I_T nexus 1772 abstraction to the initiator SCSI layer even with multi- 1773 connection sessions when one response (i.e., TMF response) 1774 could imply the status of other unfinished tasks from the 1775 initiator's perspective. 1776 - The target must ensure that the initiator does not 1777 see "old" task responses (that were placed on the wire 1778 chronologically earlier than the TMF Response) after 1779 seeing the TMF response. The target behavior in Step d 1780 of Section 4.2.3.3 and Step e of Section 4.2.3.4 1781 correspond to this objective. 1782 - Whenever the result of a TMF action is visible across 1783 multiple I_T_L nexuses, [SAM2] requires the SCSI device 1784 server to trigger a UA on each of the other I_T_L 1785 nexuses. Once an initiator is notified of such an UA, 1786 the application client on the receiving initiator is 1787 required to clear its task state (clause 5.5 in [SAM2]) 1788 for the affected tasks. It would thus be inappropriate 1789 to deliver a SCSI Response for a task after the task 1790 state is cleared on the initiator, i.e., after the UA 1791 is notified. The UA notification contained in the first 1792 SCSI Response PDU on each affected Third-party I_T_L 1793 nexus after the TMF action thus MUST NOT pass the 1794 affected task responses on any of the iSCSI sessions 1795 accessing the LU. The target behavior in Step e of 1796 Section 4.2.3.3 and Step f of Section 4.2.3.4 1797 correspond to this objective. 1798 3. Draining all active TTTs corresponding to affected tasks in 1799 a deterministic fashion. 1800 - Data-Out PDUs with stale TTTs arriving after the 1801 tasks are terminated can create a buffer management 1802 problem even for traditional iSCSI implementations, and 1803 is fatal for the connection for iSCSI/iSER 1804 implementations. Either the termination of affected 1805 tasks should be postponed until the TTTs are retired 1806 (as in Step a of Section 4.2.3.3), or the TTTs and the 1807 buffers should stay allocated beyond task termination 1808 to be deterministically freed up later (as in Steps c 1809 and g of Section 4.2.3.4). 1811 The only other notable optimization is the plugging. If all tasks 1812 on an I_T nexus will be aborted anyway (as with a target reset), 1813 there is no need to wait to receive all commands to plug the CmdSN 1814 holes. The target iSCSI layer can simply plug all missing CmdSN 1815 slots and move on with TMF processing. The first objective 1816 (maintaining a single ordered command flow) is still met with this 1817 optimization because the target SCSI layer only sees ordered 1818 commands. 1820 4.2.4. iSCSI Login 1822 The purpose of the iSCSI login is to enable a TCP connection for 1823 iSCSI use, authentication of the parties, negotiation of the 1824 session's parameters and marking of the connection as belonging to 1825 an iSCSI session. 1827 A session is used to identify to a target all the connections with 1828 a given initiator that belong to the same I_T nexus. (For more 1829 details on how a session relates to an I_T nexus, see Section 1830 4.4.2). 1832 The targets listen on a well-known TCP port or other TCP port for 1833 incoming connections. The initiator begins the login process by 1834 connecting to one of these TCP ports. 1836 As part of the login process, the initiator and target SHOULD 1837 authenticate each other and MAY set a security association 1838 protocol for the session. This can occur in many different ways 1839 and is subject to negotiation - see Section 12. 1841 To protect the TCP connection, an IPsec security association MAY 1842 be established before the Login request. For information on using 1843 IPsec security for iSCSI see Section 9 and [RFC3723]. 1845 The iSCSI Login Phase is carried through Login requests and 1846 responses. Once suitable authentication has occurred and 1847 operational parameters have been set, the session transitions to 1848 Full Feature Phase and the initiator may start to send SCSI 1849 commands. The security policy for whether, and by what means, a 1851 target chooses to authorize an initiator is beyond the scope of 1852 this document. For a more detailed description of the Login Phase, 1853 see Section 6. 1855 The login PDU includes the ISID part of the session ID (SSID). The 1856 target portal group that services the login is implied by the 1857 selection of the connection endpoint. For a new session, the TSIH 1858 is zero. As part of the response, the target generates a TSIH. 1860 During session establishment, the target identifies the SCSI 1861 initiator port (the "I" in the "I_T nexus") through the value pair 1862 (InitiatorName, ISID). We describe InitiatorName later in this 1863 Section. Any persistent state (e.g., persistent reservations) on 1864 the target that is associated with a SCSI initiator port is 1865 identified based on this value pair. Any state associated with the 1866 SCSI target port (the "T" in the "I_T nexus") is identified 1867 externally by the TargetName and portal group tag (see Section 1868 4.4.1). ISID is subject to reuse restrictions because it is used 1869 to identify a persistent state (see Section 4.4.3). 1871 Before the Full Feature Phase is established, only Login Request 1872 and Login Response PDUs are allowed. Login requests and responses 1873 MUST be used exclusively during Login. On any connection, the 1874 login phase MUST immediately follow TCP connection establishment 1875 and a subsequent Login Phase MUST NOT occur before tearing down a 1876 connection. 1878 A target receiving any PDU except a Login request before the Login 1879 phase is started MUST immediately terminate the connection on 1880 which the PDU was received. Once the Login phase has started, if 1881 the target receives any PDU except a Login request, it MUST send a 1882 Login reject (with Status "invalid during login") and then 1883 disconnect. If the initiator receives any PDU except a Login 1884 response, it MUST immediately terminate the connection. 1886 4.2.5. iSCSI Full Feature Phase 1888 Once the two sides successfully conclude the Login on the first - 1889 also called the leading - connection in the session, the iSCSI 1890 session is in the iSCSI Full Feature Phase. A connection is in 1891 Full Feature Phase if the session is in Full Feature Phase and the 1892 connection login has completed successfully. An iSCSI connection 1893 is not in Full Feature Phase 1895 a) when it does not have an established transport 1896 connection, 1897 OR 1898 b) when it has a valid transport connection, but a 1899 successful login was not performed or the connection is 1900 currently logged out. 1902 In a normal Full Feature Phase, the initiator may send SCSI 1903 commands and data to the various LUs on the target by 1904 encapsulating them in iSCSI PDUs that go over the established 1905 iSCSI session. 1907 4.2.5.1. Command Connection Allegiance 1909 For any iSCSI request issued over a TCP connection, the 1910 corresponding response and/or other related PDU(s) MUST be sent 1911 over the same connection. We call this "connection allegiance". If 1912 the original connection fails before the command is completed, the 1913 connection allegiance of the command may be explicitly reassigned 1914 to a different transport connection as described in detail in 1915 Section 7.2. 1917 Thus, if an initiator issues a READ command, the target MUST send 1918 the requested data, if any, followed by the status to the 1919 initiator over the same TCP connection that was used to deliver 1920 the SCSI command. If an initiator issues a WRITE command, the 1921 initiator MUST send the data, if any, for that command over the 1922 same TCP connection that was used to deliver the SCSI command. The 1923 target MUST return Ready To Transfer (R2T), if any, and the status 1924 over the same TCP connection that was used to deliver the SCSI 1925 command. Retransmission requests (SNACK PDUs) and the data and 1926 status that they generate MUST also use the same connection. 1928 However, consecutive commands that are part of a SCSI linked 1929 command-chain task (see [SAM2]) MAY use different connections. 1930 Connection allegiance is strictly per-command and not per-task. 1931 During the iSCSI Full Feature Phase, the initiator and target MAY 1932 interleave unrelated SCSI commands, their SCSI Data, and responses 1933 over the session. 1935 4.2.5.2. Data Transfer Overview 1937 Outgoing SCSI data (initiator to target user data or command 1938 parameters) is sent as either solicited data or unsolicited data. 1939 Solicited data are sent in response to R2T PDUs. Unsolicited data 1940 can be sent as part of an iSCSI command PDU ("immediate data") or 1941 in separate iSCSI data PDUs. 1943 Immediate data are assumed to originate at offset 0 in the 1944 initiator SCSI write-buffer (outgoing data buffer). All other Data 1945 PDUs have the buffer offset set explicitly in the PDU header. 1947 An initiator may send unsolicited data up to FirstBurstLength 1948 (see Section 13.14) as immediate (up to the negotiated maximum PDU 1949 length), in a separate PDU sequence or both. All subsequent data 1950 MUST be solicited. The maximum length of an individual data PDU or 1951 the immediate-part of the first unsolicited burst MAY be 1952 negotiated at login. 1954 The maximum amount of unsolicited data that can be sent with a 1955 command is negotiated at login through the FirstBurstLength (see 1956 Section 13.14) key. A target MAY separately enable immediate data 1957 (through the ImmediateData key) without enabling the more general 1958 (separate data PDUs) form of unsolicited data (through the 1959 InitialR2T key). 1961 Unsolicited data on write are meant to reduce the effect of 1962 latency on throughput (no R2T is needed to start sending data). In 1963 addition, immediate data is meant to reduce the protocol overhead 1964 (both bandwidth and execution time). 1966 An iSCSI initiator MAY choose not to send unsolicited data, only 1967 immediate data or FirstBurstLength bytes of unsolicited data with 1968 a command. If any non-immediate unsolicited data is sent, the 1969 total unsolicited data MUST be either FirstBurstLength, or all of 1970 the data if the total amount is less than the FirstBurstLength. 1972 It is considered an error for an initiator to send unsolicited 1973 data PDUs to a target that operates in R2T mode (only solicited 1974 data are allowed). It is also an error for an initiator to send 1975 more unsolicited data, whether immediate or as separate PDUs, than 1976 FirstBurstLength. 1978 An initiator MUST honor an R2T data request for a valid 1979 outstanding command (i.e., carrying a valid Initiator Task Tag) 1980 and deliver all the requested data provided the command is 1981 supposed to deliver outgoing data and the R2T specifies data 1982 within the command bounds. The initiator action is unspecified for 1983 receiving an R2T request that specifies data, all or part, outside 1984 of the bounds of the command. 1986 A target SHOULD NOT silently discard data and then request 1987 retransmission through R2T. Initiators SHOULD NOT keep track of 1988 the data transferred to or from the target (scoreboarding). SCSI 1989 targets perform residual count calculation to check how much data 1990 was actually transferred to or from the device by a command. This 1991 may differ from the amount the initiator sent and/or received for 1992 reasons such as retransmissions and errors. Read or bidirectional 1993 commands implicitly solicit the transmission of the entire amount 1994 of data covered by the command. SCSI data packets are matched to 1995 their corresponding SCSI commands by using tags specified in the 1996 protocol. 1998 In addition, iSCSI initiators and targets MUST enforce some 1999 ordering rules. When unsolicited data is used, the order of the 2000 unsolicited data on each connection MUST match the order in which 2001 the commands on that connection are sent. Command and unsolicited 2002 data PDUs may be interleaved on a single connection as long as the 2003 ordering requirements of each are maintained (e.g., command N+1 2004 MAY be sent before the unsolicited Data-Out PDUs for command N, 2005 but the unsolicited Data-Out PDUs for command N MUST precede the 2006 unsolicited Data-Out PDUs of command N+1). A target that receives 2007 data out of order MAY terminate the session. 2009 4.2.5.3. Tags and Integrity Checks 2011 Initiator tags for pending commands are unique initiator-wide for 2012 a session. Target tags are not strictly specified by the protocol. 2013 It is assumed that target tags are used by the target to tag 2014 (alone or in combination with the LUN) the solicited data. Target 2015 tags are generated by the target and "echoed" by the initiator. 2017 These mechanisms are designed to accomplish efficient data 2018 delivery along with a large degree of control over the data flow. 2020 As the Initiator Task Tag is used to identify a task during its 2021 execution the iSCSI initiator and target MUST verify that all 2022 other fields used in task related PDUs have values that are 2023 consistent with the values used at the task instantiation based on 2024 Initiator Task Tag (e.g., the LUN used in an R2T PDU MUST be the 2025 same as the one used in the SCSI command PDU used to instantiate 2026 the task). Using inconsistent field values is considered a 2027 protocol error. 2029 4.2.5.4. Task Management 2031 SCSI task management assumes that individual tasks and task groups 2032 can be aborted solely based on the task tags (for individual 2033 tasks) or the timing of the task management command (for task 2034 groups) and that the task management action is executed 2035 synchronously - i.e, no message involving an aborted task will be 2036 seen by the SCSI initiator after receiving the task management 2037 response. In iSCSI initiators and targets interact asynchronously 2038 over several connections. iSCSI specifies the protocol mechanism 2039 and implementation requirements needed to present a synchronous 2040 view while using an asynchronous infrastructure. 2042 4.2.6. iSCSI Connection Termination 2044 An iSCSI connection may be terminated by use of a transport 2045 connection shutdown or a transport reset. Transport reset is 2046 assumed to be an exceptional event. 2048 Graceful TCP connection shutdowns are done by sending TCP FINs. A 2049 graceful transport connection shutdown SHOULD only be initiated by 2050 either party when the connection is not in iSCSI Full Feature 2051 Phase. A target MAY terminate a Full Feature Phase connection on 2052 internal exception events, but it SHOULD announce the fact through 2053 an Asynchronous Message PDU. Connection termination with 2054 outstanding commands may require recovery actions. 2056 If a connection is terminated while in Full Feature Phase, 2057 connection cleanup (see Section 7) is required prior to recovery. 2058 By doing connection cleanup before starting recovery, the 2059 initiator and target will avoid receiving stale PDUs after 2060 recovery. 2062 4.2.7. iSCSI Names 2064 Both targets and initiators require names for the purpose of 2065 identification. In addition, names enable iSCSI storage resources 2066 to be managed regardless of location (address). An iSCSI node name 2067 is also the SCSI device name contained in the iSCSI Node. The 2068 iSCSI name of a SCSI device is the principal object used in 2069 authentication of targets to initiators and initiators to targets. 2070 This name is also used to identify and manage iSCSI storage 2071 resources. 2073 iSCSI names must be unique within the operation domain of the end 2074 user. However, because the operation domain of an IP network is 2075 potentially worldwide, the iSCSI name formats are architected to 2076 be worldwide unique. To assist naming authorities in the 2077 construction of worldwide unique names, iSCSI provides three name 2078 formats for different types of naming authorities. 2080 iSCSI names are associated with iSCSI nodes, and not iSCSI network 2081 adapter cards, to ensure that the replacement of network adapter 2082 cards does not require reconfiguration of all SCSI and iSCSI 2083 resource allocation information. 2085 Some SCSI commands require that protocol-specific identifiers be 2086 communicated within SCSI CDBs. See SCSI for the definition of the 2087 SCSI port name/identifier for iSCSI ports. 2089 An initiator may discover the iSCSI Target Names to which it has 2090 access, along with their addresses, using the SendTargets text 2091 request, or other techniques discussed in [RFC3721]. 2093 iSCSI equipment that needs discovery functions beyond SendTargets 2094 SHOULD implement iSNS (see [RFC4171]) for extended discovery 2095 management capabilities and interoperability. Although [RFC3721] 2096 implies an SLP ([RFC2608]) implementation requirement, SLP has not 2097 been widely implemented or deployed for use with iSCSI in 2098 practice. iSCSI implementations therefore SHOULD NOT rely on SLP- 2099 based discovery interoperability. 2101 4.2.7.1. iSCSI Name Properties 2103 Each iSCSI node, whether it is an initiator or target or both, 2104 MUST have an iSCSI name. Whenever an iSCSI Node contains an iSCSI 2105 Initiator Node and an iSCSI Target Node, the iSCSI Initiator Name 2106 MUST be the same as the iSCSI Target Name for the contained Nodes 2107 such that there is only one iSCSI Node Name for the iSCSI Node 2108 overall. Note the related requirements in Section 9.2.1 on how to 2109 map CHAP names to iSCSI Names in such a scenario. 2111 Initiators and targets MUST support the receipt of iSCSI names of 2112 up to the maximum length of 223 bytes. 2114 The initiator MUST present both its iSCSI Initiator Name and the 2115 iSCSI Target Name to which it wishes to connect in the first login 2116 request of a new session or connection. The only exception is if a 2117 discovery session (see Section 4.3) is to be established. In this 2118 case, the iSCSI Initiator Name is still required, but the iSCSI 2119 Target Name MAY be omitted. 2121 iSCSI names have the following properties: 2123 - iSCSI names are globally unique. No two initiators or 2124 targets can have the same name. 2126 - iSCSI names are permanent. An iSCSI initiator node or target 2127 node has the same name for its lifetime. 2129 - iSCSI names do not imply a location or address. An iSCSI 2130 initiator or target can move, or have multiple addresses. A 2131 change of address does not imply a change of name. 2133 - iSCSI names do not rely on a central name broker; the naming 2134 authority is distributed. 2136 - iSCSI names support integration with existing unique naming 2137 schemes. 2139 - iSCSI names rely on existing naming authorities. iSCSI does 2140 not create any new naming authority. 2142 The encoding of an iSCSI name has the following properties: 2144 - iSCSI names have the same encoding method regardless of the 2145 underlying protocols. 2147 - iSCSI names are relatively simple to compare. The algorithm 2148 for comparing two iSCSI names for equivalence does not rely 2149 on an external server. 2151 - iSCSI names are composed only of printable ASCII and Unicode 2152 characters. iSCSI names allow the use of international 2153 character sets but uppercase characters are prohibited. The 2154 iSCSI stringprep profile [RFC3722] maps uppercase characters 2155 to lowercase and SHOULD be used to prepare iSCSI names from 2156 input that may include uppercase characters. No whitespace 2157 characters are used in iSCSI names, see [RFC3722] for 2158 details. 2160 - iSCSI names may be transported using both binary and ASCII- 2161 based protocols. 2163 An iSCSI name really names a logical software entity, and is not 2164 tied to a port or other hardware that can be changed. For 2165 instance, an initiator name should name the iSCSI initiator node, 2166 not a particular NIC or HBA. When multiple NICs are used, they 2167 should generally all present the same iSCSI initiator name to the 2168 targets, because they are simply paths to the same SCSI layer. In 2169 most operating systems, the named entity is the operating system 2170 image. 2172 Similarly, a target name should not be tied to hardware interfaces 2173 that can be changed. A target name should identify the logical 2174 target and must be the same for the target regardless of the 2175 physical portion being addressed. This assists iSCSI initiators in 2176 determining that the two targets it has discovered are really two 2177 paths to the same target. 2179 The iSCSI name is designed to fulfill the functional requirements 2180 for Uniform Resource Names (URN) [RFC1737]. For example, it is 2181 required that the name have a global scope, be independent of 2182 address or location, and be persistent and globally unique. Names 2183 must be extensible and scalable with the use of naming 2184 authorities. The name encoding should be both human and machine 2185 readable. See [RFC1737] for further requirements. 2187 4.2.7.2. iSCSI Name Encoding 2189 An iSCSI name MUST be a UTF-8 (see [RFC3629]) encoding of a string 2190 of Unicode characters with the following properties: 2192 - It is in Normalization Form C (see "Unicode Normalization 2193 Forms" [UNICODE]). 2195 - It only contains characters allowed by the output of the 2196 iSCSI stringprep template (described in [RFC3722]). 2198 - The following characters are used for formatting iSCSI 2199 names: 2201 - dash ('-'=U+002d) 2202 - dot ('.'=U+002e) 2203 - colon (':'=U+003a) 2205 - The UTF-8 encoding of the name is not larger than 223 bytes. 2207 The stringprep process is described in [RFC3454]; iSCSI's use of 2208 the stringprep process is described in [RFC3722]. Stringprep is a 2209 method designed by the Internationalized Domain Name (IDN) working 2210 group to translate human-typed strings into a format that can be 2211 compared as opaque strings. iSCSI names are expected to be used by 2212 administrators for purposes such as system configuration - for 2213 this reason, characters that may lead to human confusion among 2214 different iSCSI names (e.g., punctuation, spacing, diacritical 2215 marks) should be avoided, even when such characters are allowed as 2216 stringprep processing output by [RFC3722]. The stringprep process 2217 also converts strings into equivalent strings of lower-case 2218 characters. 2220 The stringprep process does not need to be implemented if the 2221 names are generated using only characters allowed as output by the 2222 stringprep processing specified in [RFC3722]. Those allowed 2223 characters include all ASCII lowercase and numeric characters, as 2224 well as lowercase Unicode characters as specified in [RFC3722]. 2225 Once iSCSI names encoded in UTF-8 are "normalized" as described in 2226 this Section, they may be safely compared byte-for-byte. 2228 4.2.7.3. iSCSI Name Structure 2230 An iSCSI name consists of two parts--a type designator followed by 2231 a unique name string. 2233 iSCSI uses three existing naming authorities in constructing 2234 globally unique iSCSI names. Type designator in an iSCSI name 2235 indicates the naming authority on which the name is based. The 2236 three iSCSI name formats are the following: 2238 a) iSCSI-Qualified Name: it is based on domain names to 2239 identify a naming authority, 2240 b) NAA format Name: it is based on a naming format defined 2241 by [FC-FS3] for constructing globally unique identifiers, 2242 referred to as the Network Address Authority (NAA), and, 2243 c) EUI format Name: it is based on EUI names where the IEEE 2244 Registration Authority assists in the formation of 2245 worldwide unique names (EUI-64 format). 2247 The corresponding type designator strings currently defined are: 2249 a) iqn. - iSCSI Qualified name 2251 b) naa. - Remainder of the string is an INCITS T11-defined 2252 Network Address Authority identifier, in ASCII-encoded 2253 hexadecimal. 2255 c) eui. - Remainder of the string is an IEEE EUI-64 2256 identifier, in ASCII-encoded hexadecimal. 2258 These three naming authority designators were considered 2259 sufficient at the time of writing this document. The creation of 2260 additional naming type designators for iSCSI may be considered by 2261 the IETF and detailed in separate RFCs. 2263 The following table summarizes the current SCSI transport 2264 protocols and their naming formats. 2266 SCSI Transport Protocol Naming Format 2267 +----------------------------+-------+-----+----+ 2268 | | EUI-64| NAA |IQN | 2269 |----------------------------|-------|-----|----| 2270 | iSCSI (Internet SCSI) | X | X | X | 2271 |----------------------------|-------|-----|----| 2272 | FCP (Fibre Channel) | | X | | 2273 |----------------------------|-------|-----|----| 2274 | SAS (Serial Attached SCSI) | | X | | 2275 +----------------------------+-------+-----+----+ 2277 4.2.7.4. Type "iqn." (iSCSI Qualified Name) 2279 This iSCSI name type can be used by any organization that owns a 2280 domain name. This naming format is useful when an end user or 2281 service provider wishes to assign iSCSI names for targets and/or 2282 initiators. 2284 To generate names of this type, the person or organization 2285 generating the name must own a registered domain name. This domain 2286 name does not have to resolve to an address; it just needs to be 2287 reserved to prevent others from generating iSCSI names using the 2288 same domain name. 2290 Since a domain name can expire, be acquired by another entity, or 2291 may be used to generate iSCSI names by both owners, the domain 2292 name must be additionally qualified by a date during which the 2293 naming authority owned the domain name. A date code is provided as 2294 part of the "iqn." format for this reason. 2296 The iSCSI qualified name string consists of: 2298 - The string "iqn.", used to distinguish these names from 2299 "eui." formatted names. 2301 - A date code, in yyyy-mm format. This date MUST be a date 2302 during which the naming authority owned the domain name used 2303 in this format, and SHOULD be the first month in which the 2304 domain name was owned by this naming authority at 00:01 GMT 2305 of the first day of the month. This date code uses the 2306 Gregorian calendar. All four digits in the year must be 2307 present. Both digits of the month must be present, with 2308 January == "01" and December == "12". The dash must be 2309 included. 2311 - A dot "." 2313 - The reversed domain name of the naming authority (person or 2314 organization) creating this iSCSI name. 2316 - An optional, colon (:) prefixed, string within the character 2317 set and length boundaries that the owner of the domain name 2318 deems appropriate. This may contain product types, serial 2319 numbers, host identifiers, or software keys (e.g, it may 2320 include colons to separate organization boundaries). With 2321 the exception of the colon prefix, the owner of the domain 2322 name can assign everything after the reversed domain name as 2323 desired. It is the responsibility of the entity that is the 2324 naming authority to ensure that the iSCSI names it assigns 2325 are worldwide unique. For example, "Example Storage Arrays, 2326 Inc.", might own the domain name "example.com". 2328 The following are examples of iSCSI qualified names that might be 2329 generated by "EXAMPLE Storage Arrays, Inc." 2331 Naming String defined by 2332 Type Date Auth "example.com" naming authority 2333 +--++-----+ +---------+ +--------------------------------+ 2334 | || | | | | | 2336 iqn.2001-04.com.example:storage:diskarrays-sn-a8675309 2337 iqn.2001-04.com.example 2338 iqn.2001-04.com.example:storage.tape1.sys1.xyz 2339 iqn.2001-04.com.example:storage.disk2.sys1.xyz 2341 4.2.7.5. Type "eui." (IEEE EUI-64 format) 2343 The IEEE Registration Authority provides a service for assigning 2344 globally unique identifiers [EUI]. The EUI-64 format is used to 2345 build a global identifier in other network protocols. For example, 2346 Fibre Channel defines a method of encoding it into a 2347 WorldWideName. For more information on registering for EUI 2348 identifiers, see [OUI]. 2350 The format is "eui." followed by an EUI-64 identifier (16 ASCII- 2351 encoded hexadecimal digits). 2353 Example iSCSI name: 2355 Type EUI-64 identifier (ASCII-encoded hexadecimal) 2357 +--++--------------+ 2359 | || | 2361 eui.02004567A425678D 2363 The IEEE EUI-64 iSCSI name format might be used when a 2364 manufacturer is already registered with the IEEE Registration 2365 Authority and uses EUI-64 formatted worldwide unique names for its 2366 products. 2368 More examples of name construction are discussed in [RFC3721]. 2370 4.2.7.6. Type "naa." - Network Address Authority 2372 The INCITS T11 Framing and Signaling Specification [FC-FS3] 2373 defines a format called the Network Address Authority (NAA) format 2374 for constructing worldwide unique identifiers that use various 2375 identifier registration authorities. This identifier format is 2376 used by the Fibre Channel and SAS SCSI transport protocols. As FC 2377 and SAS constitute a large fraction of networked SCSI ports, the 2378 NAA format is a widely used format for SCSI transports. The 2379 objective behind iSCSI supporting a direct representation of an 2380 NAA-format name is to facilitate construction of a target device 2381 name that translates easily across multiple namespaces for a SCSI 2382 storage device containing ports served by different transports. 2383 More specifically, this format allows implementations wherein one 2384 NAA identifier can be assigned as the basis for the SCSI device 2385 name for a SCSI target with both SAS ports and iSCSI ports. 2387 The iSCSI NAA naming format is "naa.", followed by an NAA 2388 identifier represented in ASCII-encoded hexadecimal digits. 2390 An example of an iSCSI name with a 64-bit NAA value follows: 2392 Type NAA identifier (ASCII-encoded hexadecimal) 2393 +--++--------------+ 2394 | || | 2395 naa.52004567BA64678D 2397 An example of an iSCSI name with a 128-bit NAA value follows: 2399 Type NAA identifier (ASCII-encoded hexadecimal) 2400 +--++------------------------------+ 2401 | || | 2402 naa.62004567BA64678D0123456789ABCDEF 2404 The iSCSI NAA naming format might be used in an implementation 2405 when the infrastructure for generating NAA worldwide unique names 2406 is already in place because the device contains both SAS and iSCSI 2407 SCSI ports. 2409 The NAA identifier formatted in an ASCII-hexadecimal 2410 representation has a maximum size of 32 characters (128 bit NAA 2411 format). As a result, there is no issue with this naming format 2412 exceeding the maximum size for iSCSI node names. 2414 4.2.8. Persistent State 2416 iSCSI does not require any persistent state maintenance across 2417 sessions. However, in some cases, SCSI requires persistent 2418 identification of the SCSI initiator port name (See Section 4.4.2 2419 and Section 4.4.3). 2421 iSCSI sessions do not persist through power cycles and boot 2422 operations. 2424 All iSCSI session and connection parameters are re-initialized on 2425 session and connection creation. 2427 Commands persist beyond connection termination if the session 2428 persists and command recovery within the session is supported. 2429 However, when a connection is dropped, command execution, as 2430 perceived by iSCSI (i.e., involving iSCSI protocol exchanges for 2431 the affected task), is suspended until a new allegiance is 2432 established by the 'task reassign' task management function. (See 2433 Section 11.5.) 2435 4.2.9. Message Synchronization and Steering 2437 iSCSI presents a mapping of the SCSI protocol onto TCP. This 2438 encapsulation is accomplished by sending iSCSI PDUs of varying 2439 lengths. Unfortunately, TCP does not have a built-in mechanism for 2440 signaling message boundaries at the TCP layer. iSCSI overcomes 2441 this obstacle by placing the message length in the iSCSI message 2442 header. This serves to delineate the end of the current message as 2443 well as the beginning of the next message. 2445 In situations where IP packets are delivered in order from the 2446 network, iSCSI message framing is not an issue and messages are 2447 processed one after the other. In the presence of IP packet 2448 reordering (i.e., frames being dropped), legacy TCP 2449 implementations store the "out of order" TCP segments in temporary 2450 buffers until the missing TCP segments arrive, upon which the data 2451 must be copied to the application buffers. In iSCSI, it is 2452 desirable to steer the SCSI data within these out of order TCP 2453 segments into the pre-allocated SCSI buffers rather than store 2454 them in temporary buffers. This decreases the need for dedicated 2455 reassembly buffers as well as the latency and bandwidth related to 2456 extra copies. 2458 Relying solely on the "message length" information from the iSCSI 2459 message header may make it impossible to find iSCSI message 2460 boundaries in subsequent TCP segments due to the loss of a TCP 2461 segment that contains the iSCSI message length. The missing TCP 2462 segment(s) must be received before any of the following segments 2463 can be steered to the correct SCSI buffers (due to the inability 2464 to determine the iSCSI message boundaries). Since these segments 2465 cannot be steered to the correct location, they must be saved in 2466 temporary buffers that must then be copied to the SCSI buffers. 2468 Different schemes can be used to recover synchronization. The 2469 details of any such schemes are beyond this protocol 2470 specification, but it suffices to note that [RFC4297] provides an 2471 overview of the direct data placement problem on IP networks, and 2472 [RFC5046] specifies a protocol extension for iSCSI that 2473 facilitates this direct data placement objective. Rest of this 2474 document refers to any such direct data placement protocol usage 2475 as an example of a "Synch and Steering layer". 2477 Under normal circumstances (no PDU loss or data reception out of 2478 order), iSCSI data steering can be accomplished by using the 2479 identifying tag and the data offset fields in the iSCSI header in 2480 addition to the TCP sequence number from the TCP header. The 2481 identifying tag helps associate the PDU with a SCSI buffer address 2482 while the data offset and TCP sequence number are used to 2483 determine the offset within the buffer. 2485 4.2.9.1. Sync/Steering and iSCSI PDU Length 2487 When a large iSCSI message is sent, the TCP segment(s) that 2488 contain the iSCSI header may be lost. The remaining TCP segment(s) 2489 up to the next iSCSI message must be buffered (in temporary 2490 buffers) because the iSCSI header that indicates to which SCSI 2491 buffers the data are to be steered was lost. To minimize the 2492 amount of buffering, it is recommended that the iSCSI PDU length 2493 be restricted to a small value (perhaps a few TCP segments in 2494 length). During login, each end of the iSCSI session specifies the 2495 maximum iSCSI PDU length it will accept. 2497 4.3. iSCSI Session Types 2499 iSCSI defines two types of sessions: 2501 a) Normal operational session - an unrestricted session. 2503 b) Discovery-session - a session only opened for target 2504 discovery. The target MUST ONLY accept text requests with 2505 the SendTargets key and a logout request with reason 2506 "close the session". All other requests MUST be rejected. 2508 The session type is defined during login with SessionType=value 2509 parameter in the login command. 2511 4.4. SCSI to iSCSI Concepts Mapping Model 2513 The following diagram shows an example of how multiple iSCSI Nodes 2514 (targets in this case) can coexist within the same Network Entity 2515 and can share Network Portals (IP addresses and TCP ports). Other 2516 more complex configurations are also possible. For detailed 2517 descriptions of the components of these diagrams, see Section 2518 4.4.1. 2520 +-----------------------------------+ 2521 | Network Entity (iSCSI Client) | 2522 | | 2523 | +-------------+ | 2524 | | iSCSI Node | | 2525 | | (Initiator) | | 2526 | +-------------+ | 2527 | | | | 2528 | +--------------+ +--------------+ | 2529 | |Network Portal| |Network Portal| | 2530 | | 192.0.2.4 | | 192.0.2.5 | | 2531 +-+--------------+-+--------------+-+ 2532 | | 2533 | IP Networks | 2534 | | 2535 +-+--------------+-+--------------+-+ 2536 | |Network Portal| |Network Portal| | 2537 | |198.51.100.21 | |198.51.100.3 | | 2538 | | TCP Port 3260| | TCP Port 3260| | 2539 | +--------------+ +--------------+ | 2540 | | | | 2541 | ----------------- | 2542 | | | | 2543 | +-------------+ +--------------+ | 2544 | | iSCSI Node | | iSCSI Node | | 2545 | | (Target) | | (Target) | | 2546 | +-------------+ +--------------+ | 2547 | | 2548 | Network Entity (iSCSI Server) | 2549 +-----------------------------------+ 2551 4.4.1. iSCSI Architecture Model 2553 This Section describes the part of the iSCSI architecture model 2554 that has the most bearing on the relationship between iSCSI and 2555 the SCSI Architecture Model. 2557 - Network Entity - represents a device or gateway that is 2558 accessible from the IP network. A Network Entity must have 2559 one or more Network Portals (see a following item), each of 2560 which can be used by some iSCSI Nodes (see the following 2561 item) contained in that Network Entity to gain access to the 2563 IP network. 2565 - iSCSI Node - represents a single iSCSI initiator or iSCSI 2566 target or an instance of each. There are one or more iSCSI 2567 Nodes within a Network Entity. The iSCSI Node is accessible 2568 via one or more Network Portals (see item d). An iSCSI Node 2569 is identified by its iSCSI Name (see Section 4.2.7 and 2570 Section 13). The separation of the iSCSI Name from the 2571 addresses used by and for the iSCSI node allows multiple 2572 iSCSI nodes to use the same addresses, and the same iSCSI 2573 node to use multiple addresses. 2575 - An alias string may also be associated with an iSCSI Node. 2576 The alias allows an organization to associate a user 2577 friendly string with the iSCSI Name. However, the alias 2578 string is not a substitute for the iSCSI Name. 2580 - Network Portal - a component of a Network Entity that has a 2581 TCP/IP network address and that may be used by an iSCSI Node 2582 within that Network Entity for the connection(s) within one 2583 of its iSCSI sessions. In an initiator, it is identified by 2584 its IP address. In a target, it is identified by its IP 2585 address and its listening TCP port. 2587 - Portal Groups - iSCSI supports multiple connections within 2588 the same session; some implementations will have the ability 2589 to combine connections in a session across multiple Network 2590 Portals. A Portal Group defines a set of Network Portals 2591 within an iSCSI Node that collectively supports the 2592 capability of coordinating a session with connections that 2593 span these portals. Not all Network Portals within a Portal 2594 Group need to participate in every session connected through 2595 that Portal Group. One or more Portal Groups may provide 2596 access to an iSCSI Node. Each Network Portal, as utilized by 2597 a given iSCSI Node, belongs to exactly one portal group 2598 within that node. Portal Groups are identified within an 2599 iSCSI Node by a portal group tag, a simple unsigned-integer 2600 between 0 and 65535 (see Section 13.3). All Network Portals 2602 with the same portal group tag in the context of a given 2603 iSCSI Node are in the same Portal Group. 2605 Both iSCSI Initiators and iSCSI Targets have portal groups, 2606 though only the iSCSI Target Portal Groups are used directly 2607 in the iSCSI protocol (e.g., in SendTargets). For references 2608 to the Initiator Portal Groups, see Section 10.1.1. 2610 - Portals within a Portal Group should support similar session 2611 parameters, because they may participate in a common 2612 session. 2614 The following diagram shows an example of one such configuration 2615 on a target and how a session that shares Network Portals within a 2616 Portal Group may be established. 2618 ----------------------------IP Network--------------------- 2619 | | | 2620 +----|----------------|----+ +----|---------+ 2621 | +---------+ +---------+ | | +---------+ | 2622 | | Network | | Network | | | | Network | | 2623 | | Portal | | Portal | | | | Portal | | 2624 | +--|------+ +---------+ | | +---------+ | 2625 | | | | | | | 2626 | | Portal | | | | Portal | 2627 | | Group 1 | | | | Group 2 | 2628 +--------------------------+ +--------------+ 2629 | | | 2630 +--------|----------------|------------------|------------------+ 2631 | | | | | 2632 | +----------------------------+ +----------------------------+ | 2633 | | iSCSI Session (Target side)| | iSCSI Session (Target side)| | 2634 | | | | | | 2635 | | (TSIH = 56) | | (TSIH = 48) | | 2636 | +----------------------------+ +----------------------------+ | 2637 | | 2638 | iSCSI Target Node | 2639 | (within Network Entity, not shown) | 2640 +---------------------------------------------------------------+ 2642 4.4.2. SCSI Architecture Model 2644 This Section describes the relationship between the SCSI 2645 Architecture Model [SAM2] and constructs of the SCSI device, SCSI 2646 port and I_T nexus, and the iSCSI constructs described in Section 2647 4.4.1. 2649 This relationship implies implementation requirements in order to 2650 conform to the SAM2 model and other SCSI operational functions. 2651 These requirements are detailed in Section 4.4.3. 2653 The following list outlines mappings of SCSI architectural 2654 elements to iSCSI. 2656 a) SCSI Device - the SAM2 term for an entity that contains 2657 one or more SCSI ports that are connected to a service 2658 delivery subsystem and supports a SCSI application 2659 protocol. For example, a SCSI Initiator Device contains 2660 one or more SCSI Initiator Ports and zero or more 2661 application clients. A SCSI Target Device contains one or 2662 more SCSI Target Ports and one or more logical units. For 2663 iSCSI, the SCSI Device is the component within an iSCSI 2664 Node that provides the SCSI functionality. As such, there 2665 can be one SCSI Device, at most, within an iSCSI Node. 2666 Access to the SCSI Device can only be achieved in an 2667 iSCSI normal operational session (see Section 4.3). The 2668 SCSI Device Name is defined to be the iSCSI Name of the 2669 node and MUST be used in the iSCSI protocol. 2671 b) SCSI Port - the SAM2 term for an entity in a SCSI Device 2672 that provides the SCSI functionality to interface with a 2673 service delivery subsystem or transport. For iSCSI, the 2674 definition of SCSI Initiator Port and SCSI Target Port 2675 are different. 2677 SCSI Initiator Port: This maps to one endpoint of an 2678 iSCSI normal operational session (see Section 4.3). An 2679 iSCSI normal operational session is negotiated through 2680 the login process between an iSCSI initiator node and an 2681 iSCSI target node. At successful completion of this 2682 process, a SCSI Initiator Port is created within the SCSI 2683 Initiator Device. The SCSI Initiator Port Name and SCSI 2684 Initiator Port Identifier are both defined to be the 2685 iSCSI Initiator Name together with (a) a label that 2686 identifies it as an initiator port name/identifier and 2687 (b) the ISID portion of the session identifier. 2689 SCSI Target Port: This maps to an iSCSI Target Portal 2690 Group. The SCSI Target Port Name and the SCSI Target Port 2691 Identifier are both defined to be the iSCSI Target Name 2692 together with (a) a label that identifies it as a target 2693 port name/identifier and (b) the portal group tag. 2695 The SCSI Port Name MUST be used in iSCSI. When used in 2696 SCSI parameter data, the SCSI port name MUST be encoded 2697 as: 2698 1. The iSCSI Name in UTF-8 format, followed by 2699 2. a comma separator (1 byte), followed by 2700 3. the ASCII character 'i' (for SCSI Initiator Port) 2701 or the ASCII character 't' (for SCSI Target Port) 2702 (1 byte), followed by 2703 4. a comma separator (1 byte), followed by 2704 5. a text encoding as a hex-constant (see Section 6.1) 2705 of the ISID (for SCSI initiator port) or the 2706 portal group tag (for SCSI target port) including 2707 the initial 0X or 0x and the terminating null (14 2708 bytes). 2710 The ASCII character 'i' or 't' is the label that 2711 identifies this port as either a SCSI Initiator 2712 Port or a SCSI Target Port. 2714 c) I_T nexus - a relationship between a SCSI Initiator Port 2715 and a SCSI Target Port, according to [SAM2]. For iSCSI, 2716 this relationship is a session, defined as a relationship 2717 between an iSCSI Initiator's end of the session (SCSI 2718 Initiator Port) and the iSCSI Target's Portal Group. The 2719 I_T nexus can be identified by the conjunction of the 2720 SCSI port names or by the iSCSI session identifier SSID. 2721 iSCSI defines the I_T nexus identifier to be the tuple 2722 (iSCSI Initiator Name + ",i,0x" + ISID in text format, 2723 iSCSI Target Name + ",t,0x" + Portal Group Tag in text 2724 format) - an upper case hex prefix "0X" may alternatively 2725 be used in place of "0x". 2727 NOTE: The I_T nexus identifier is not equal to the 2728 session identifier (SSID). 2730 4.4.3. Consequences of the Model 2732 This Section describes implementation and behavioral requirements 2733 that result from the mapping of SCSI constructs to the iSCSI 2734 constructs defined above. Between a given SCSI initiator port and 2735 a given SCSI target port, only one I_T nexus (session) can exist. 2736 No more than one nexus relationship (parallel nexus) is allowed by 2737 [SAM2]. Therefore, at any given time, only one session with the 2738 same session identifier (SSID) can exist between a given iSCSI 2739 initiator node and an iSCSI target node. 2741 These assumptions lead to the following conclusions and 2742 requirements: 2744 ISID RULE: Between a given iSCSI Initiator and iSCSI Target Portal 2745 Group (SCSI target port), there can only be one session with a 2746 given value for ISID that identifies the SCSI initiator port. See 2747 Section 11.12.5. 2749 The structure of the ISID that contains a naming authority 2750 component (see Section 11.12.5 and [RFC3721]) provides a mechanism 2751 to facilitate compliance with the ISID rule. (See Section 10.1.1) 2753 The iSCSI Initiator Node should manage the assignment of ISIDs 2754 prior to session initiation. The "ISID RULE" does not preclude the 2755 use of the same ISID from the same iSCSI Initiator with different 2756 Target Portal Groups on the same iSCSI target or on other iSCSI 2757 targets (see Section 10.1.1). Allowing this would be analogous to 2758 a single SCSI Initiator Port having relationships (nexus) with 2759 multiple SCSI target ports on the same SCSI target device or SCSI 2760 target ports on other SCSI target devices. It is also possible to 2761 have multiple sessions with different ISIDs to the same Target 2762 Portal Group. Each such session would be considered to be with a 2763 different initiator even when the sessions originate from the same 2764 initiator device. The same ISID may be used by a different iSCSI 2765 initiator because it is the iSCSI Name together with the ISID that 2766 identifies the SCSI Initiator Port. 2768 NOTE: A consequence of the ISID RULE and the specification for the 2769 I_T nexus identifier is that two nexus with the same identifier 2770 should never exist at the same time. 2772 TSIH RULE: The iSCSI Target selects a non-zero value for the TSIH 2773 at session creation (when an initiator presents a 0 value at 2774 Login). After being selected, the same TSIH value MUST be used 2775 whenever initiator or target refers to the session and a TSIH is 2776 required. 2778 4.4.3.1. I_T Nexus State 2780 Certain nexus relationships contain an explicit state (e.g., 2781 initiator-specific mode pages) that may need to be preserved by 2782 the device server [SAM2] in a logical unit through changes or 2783 failures in the iSCSI layer (e.g., session failures). In order for 2784 that state to be restored, the iSCSI initiator should reestablish 2785 its session (re-login) to the same Target Portal Group using the 2786 previous ISID. That is, it should reinstate the session via iSCSI 2787 session reinstatement (Section 6.3.5) or continue via session 2788 continuation (Section 6.3.6). This is because the SCSI initiator 2789 port identifier and the SCSI target port identifier (or relative 2790 target port) form the datum that the SCSI logical unit device 2791 server uses to identify the I_T nexus. 2793 4.4.3.2. Reservations 2795 There are two reservation management methods defined in the SCSI 2796 standards, reserve/release reservations, based on the RESERVE and 2797 RELEASE commands [SPC2], and persistent reservations, based on the 2798 PERSISTENT RESERVE IN and PERSISTENT RESERVE OUT commands [SPC3]. 2799 Reserve/release reservations are obsolete [SPC3] and should not be 2800 used; persistent reservations are suggested as an alternative, see 2801 Annex B of [SPC4]. 2803 State for persistent reservations is required to persist through 2804 changes and failures at the iSCSI layer that result in I_T nexus 2805 failures, see [SPC3] for details and specific requirements. 2807 In contrast, [SPC2] does not specify detailed persistence 2808 requirements for reserve/release reservation state after an I_T 2809 nexus failure. Nonetheless, when reserve/release reservations are 2810 supported by an iSCSI target, the preferred implementation 2811 approach is to preserve reserve/release reservation state for 2812 iSCSI session reinstatement (see Section 6.3.5) or session 2813 continuation (see Section 6.3.6). 2815 Two additional caveats apply to reserve/release reservations: 2817 - Retention of a failed session's reserve/release reservation 2818 state by an iSCSI target, even after that failed iSCSI 2819 session is not reinstated or continued, may require an 2820 initiator to issue a reset (e.g., LOGICAL UNIT RESET, see 2821 Section 11.5) in order to remove that reservation state. 2823 - Reserve/release reservations may not behave as expected when 2824 persistent reservations are also used on the same logical 2825 unit; see the discussion of "Exceptions to SPC-2 RESERVE and 2826 RELEASE behavior" in [SPC4]. 2828 4.5. iSCSI UML Model 2830 This Section presents the application of the UML modeling concepts 2831 discussed in Section 3 to the iSCSI and SCSI architecture model 2832 discussed in Section 4.4. 2834 +----------------+ 2835 | Network Entity | 2836 +----------------+ 2837 @ 1 @ 1 2838 | | 2839 +--------------------+ | 2840 | | 2841 | | 0..* 2842 | +------------------+ 2843 | | iSCSI Node | 2844 | +------------------+ 2845 | @ @ 2846 | | | 2847 | +-----------+ =(a)= +-----------+ 2848 | | | 2849 | | 0..1 | 0..1 2850 | +------------------------+ +----------------------+ 2851 | | iSCSI Target Node | | iSCSI Initiator Node | 2852 | +------------------------+ +----------------------+ 2853 | @ 1 @ 1 2854 | +--------------+ | 2855 | 1..* | | 1..* 2856 | +-----------------------------+ 2857 | | Portal Group | 2858 | +-----------------------------+ 2859 | O 1 2860 | | 2861 | | 1..* 2862 | 1..* +------------------------+ 2863 +--------------------| Network Portal | 2864 +------------------------+ 2866 (a) Each instance of an iSCSI Node class MUST contain one iSCSI 2867 Target Node instance or one iSCSI Initiator Node instance, or 2868 both. 2870 +----------------+ 2871 | Network Entity | 2872 +----------------+ 2873 @ 1 @ 1 2874 | | +-------------------+ 2875 +---------------------+ | | iSCSI Session | 2876 | | +-------------------+ 2877 | | 0..* | SSID[1] | 2878 | +--------------------+ | ISID[1] | 2879 | | iSCSI Node | +-------------------+ 2880 | +--------------------+ @ 1 2881 | | iSCSI Node Name[1] | | 2882 | | Alias [0..1] | | 0..* 2883 | +--------------------+ +------------------+ 2884 | | | | iSCSI Connection | 2885 | +--------------------+ +------------------+ 2886 | @ 1 @ 1 | CID[1] | 2887 | | | +------------------+ 2888 | +-------------+ ==(b)== +----------+ 0..* | 2889 | | 1 | 1 | 2890 | +------------------------+ +------------------------+ | 2891 | | iSCSI Target Node | | iSCSI Initiator Node | | 2892 | +------------------------+ +------------------------+ | 2893 | | iSCSI Target name [1] | |iSCSI Initiator Name [1]| | 2894 | +------------------------+ +------------------------+ | 2895 | @ 1 @ 1 | 2896 | | 1..* | 1..* | 2897 | +--------------------------+ +------------------------+ | 2898 | | Target Portal Group | | Initiator Portal Group | | 2899 | +--------------------------+ +------------------------+ | 2900 | |Target Portal Group Tag[1]| | Portal group tag[1] | | 2901 | +--------------------------+ +------------------------+ | 2902 | o 1 o 1 | 2903 | +------------+ +---------+ | 2904 | 1..* | | 1..* | 2905 | +-------------------------+ | 2906 | | Network Portal | | 2907 | +-------------------------+ | 2908 | 1..* | IP Address [1] | 1 | 2909 +----------------| TCP Port [0..1] |<----------------------+ 2910 +-------------------------+ 2912 (b) Each instance of an iSCSI Node class MUST contain one iSCSI 2913 Target Node instance or one iSCSI Initiator Node instance, or 2914 both. However, in all scenarios, note that an iSCSI Node MUST 2915 only have a single iSCSI Name. Note the related requirement in 2916 Section 4.2.7.1. 2918 4.6. Request/Response Summary 2920 This Section lists and briefly describes all the iSCSI PDU types 2921 (request and responses). 2923 All iSCSI PDUs are built as a set of one or more header segments 2924 (basic and auxiliary) and zero or one data segments. The header 2925 group and the data segment may each be followed by a CRC (digest) 2926 (see [CRC]). 2928 The basic header segment has a fixed length of 48 bytes. 2930 4.6.1. Request/Response Types Carrying SCSI Payload 2932 4.6.1.1. SCSI-Command 2934 This request carries the SCSI CDB and all the other SCSI execute 2935 command procedure call (see [SAM2]) IN arguments such as task 2936 attributes, Expected Data Transfer Length for one or both transfer 2937 directions (the latter for bidirectional commands), and Task Tag 2938 (as part of the I_T_L_x nexus). The I_T_L nexus is derived by the 2939 initiator and target from the LUN field in the request and the I_T 2940 nexus is implicit in the session identification. 2942 In addition, the SCSI-command PDU carries information required for 2943 the proper operation of the iSCSI protocol - the command sequence 2944 number (CmdSN) and the expected status number (ExpStatSN) on the 2945 connection it is issued. 2947 All or part of the SCSI output (write) data associated with the 2948 SCSI command may be sent as part of the SCSI-Command PDU as a data 2949 segment. 2951 4.6.1.2. SCSI-Response 2953 The SCSI-Response carries all the SCSI execute-command procedure 2954 call (see [SAM2]) OUT arguments and the SCSI execute-command 2955 procedure call return value. 2957 The SCSI-Response contains the residual counts from the operation, 2958 if any, an indication of whether the counts represent an overflow 2959 or an underflow, and the SCSI status if the status is valid or a 2960 response code (a non-zero return value for the execute-command 2961 procedure call) if the status is not valid. 2963 For a valid status that indicates that the command has been 2964 processed, but resulted in an exception (e.g., a SCSI CHECK 2965 CONDITION), the PDU data segment contains the associated sense 2966 data. The use of Autosense ([SAM2]) is REQUIRED by iSCSI. 2968 Some data segment content may also be associated (in the data 2969 segment) with a non-zero response code. 2971 In addition, the SCSI-Response PDU carries information required 2972 for the proper operation of the iSCSI protocol: 2974 - The number of Data-In PDUs that a target has sent (to enable 2975 the initiator to check that all have arrived). 2977 - StatSN - the Status Sequence Number on this connection. 2979 - ExpCmdSN - the next Expected Command Sequence Number at the 2980 target. 2982 - MaxCmdSN - the maximum CmdSN acceptable at the target from 2983 this initiator. 2985 4.6.1.3. Task Management Function Request 2987 The Task Management function request provides an initiator with a 2988 way to explicitly control the execution of one or more SCSI Tasks 2989 or iSCSI functions. The PDU carries a function identifier (which 2990 task management function to perform) and enough information to 2991 unequivocally identify the task or task-set on which to perform 2992 the action, even if the task(s) to act upon has not yet arrived or 2993 has been discarded due to an error. 2995 The referenced tag identifies an individual task if the function 2996 refers to an individual task. 2998 The I_T_L nexus identifies task sets. In iSCSI the I_T_L nexus is 2999 identified by the LUN and the session identification (the session 3000 identifies an I_T nexus). 3002 For task sets, the CmdSN of the Task Management function request 3003 helps identify the tasks upon which to act, namely all tasks 3004 associated with a LUN and having a CmdSN preceding the Task 3005 Management function request CmdSN. 3007 For a Task Management function, the coordination between responses 3008 to the tasks affected and the Task Management function response is 3009 done by the target. 3011 4.6.1.4. Task Management Function Response 3013 The Task Management function response carries an indication of 3014 function completion for a Task Management function request 3015 including how it completed (response and qualifier) and additional 3016 information for failure responses. 3018 After the Task Management response indicates Task Management 3019 function completion, the initiator will not receive any additional 3020 responses from the affected tasks. 3022 4.6.1.5. SCSI Data-out and SCSI Data-in 3024 SCSI Data-out and SCSI Data-in are the main vehicles by which SCSI 3025 data payload is carried between initiator and target. Data payload 3026 is associated with a specific SCSI command through the Initiator 3027 Task Tag. For target convenience, outgoing solicited data also 3028 carries a Target Transfer Tag (copied from R2T) and the LUN. Each 3029 PDU contains the payload length and the data offset relative to 3030 the buffer address contained in the SCSI execute command procedure 3031 call. 3033 In each direction, the data transfer is split into "sequences". An 3034 end-of-sequence is indicated by the F bit. 3036 An outgoing sequence is either unsolicited (only the first 3037 sequence can be unsolicited) or consists of all the Data-Out PDUs 3038 sent in response to an R2T. 3040 Input sequences enable the switching of direction for 3041 bidirectional commands as required. 3043 For input, the target may request positive acknowledgement of 3044 input data. This is limited to sessions that support error 3045 recovery and is implemented through the A bit in the SCSI Data-in 3046 PDU header. 3048 Data-in and Data-out PDUs also carry the DataSN to enable the 3049 initiator and target to detect missing PDUs (discarded due to an 3050 error). 3052 In addition, StatSN is carried by the Data-In PDUs. 3054 To enable a SCSI command to be processed while involving a minimum 3055 number of messages, the last SCSI Data-in PDU passed for a command 3056 may also contain the status if the status indicates termination 3057 with no exceptions (no sense or response involved). 3059 4.6.1.6. Ready To Transfer (R2T) 3061 R2T is the mechanism by which the SCSI target "requests" the 3062 initiator for output data. R2T specifies to the initiator the 3063 offset of the requested data relative to the buffer address from 3064 the execute command procedure call and the length of the solicited 3065 data. 3067 To help the SCSI target associate the resulting Data-out with an 3068 R2T, the R2T carries a Target Transfer Tag that will be copied by 3069 the initiator in the solicited SCSI Data-out PDUs. There are no 3070 protocol specific requirements with regard to the value of these 3071 tags, but it is assumed that together with the LUN, they will 3072 enable the target to associate data with an R2T. 3074 R2T also carries information required for proper operation of the 3075 iSCSI protocol, such as: 3077 - R2TSN (to enable an initiator to detect a missing R2T) 3079 - StatSN 3081 - ExpCmdSN 3083 - MaxCmdSN 3085 4.6.2. Requests/Responses carrying SCSI and iSCSI Payload 3087 4.6.2.1. Asynchronous Message 3089 Asynchronous Messages are used to carry SCSI asynchronous events 3090 (AEN) and iSCSI asynchronous messages. 3092 When carrying an AEN, the event details are reported as sense data 3093 in the data segment. 3095 4.6.3. Requests/Responses Carrying iSCSI Only Payload 3097 4.6.3.1. Text Request and Text Response 3099 Text requests and responses are designed as a parameter 3100 negotiation vehicle and as a vehicle for future extension. 3102 In the data segment Text Requests/Responses carry text information 3103 using a simple "key=value" syntax. 3105 Text Request/Responses may form extended sequences using the same 3106 Initiator Task Tag. The initiator uses the F (Final) flag bit in 3107 the text request header to indicate its readiness to terminate a 3108 sequence. The target uses the F (Final) flag bit in the text 3109 response header to indicate its consent to sequence termination. 3111 Text Request and Responses also use the Target Transfer Tag to 3112 indicate continuation of an operation or a new beginning. A target 3113 that wishes to continue an operation will set the Target Transfer 3114 Tag in a Text Response to a value different from the default 3115 0xffffffff. An initiator willing to continue will copy this value 3116 into the Target Transfer Tag of the next Text Request. If the 3117 initiator wants to restart the current target negotiation (start 3118 fresh) will set the Target Transfer Tag to 0xffffffff. 3120 Although a complete exchange is always started by the initiator, 3121 specific parameter negotiations may be initiated by the initiator 3122 or target. 3124 4.6.3.2. Login Request and Login Response 3126 Login Requests and Responses are used exclusively during the Login 3127 Phase of each connection to set up the session and connection 3128 parameters. (The Login Phase consists of a sequence of login 3129 requests and responses carrying the same Initiator Task Tag.) 3131 A connection is identified by an arbitrarily selected connection- 3132 ID (CID) that is unique within a session. 3134 Similar to the Text Requests and Responses, Login 3135 Requests/Responses carry key=value text information with a simple 3136 syntax in the data segment. 3138 The Login Phase proceeds through several stages (security 3139 negotiation, operational parameter negotiation) that are selected 3140 with two binary coded fields in the header -- the "current stage" 3141 (CSG) and the "next stage" (NSG) with the appearance of the latter 3142 being signaled by the "transit" flag (T). 3144 The first Login Phase of a session plays a special role, called 3145 the leading login, which determines some header fields (e.g., the 3146 version number, the maximum number of connections, and the session 3147 identification). 3149 The CmdSN initial value is also set by the leading login. 3151 StatSN for each connection is initiated by the connection login. 3153 A login request may indicate an implied logout (cleanup) of the 3154 connection to be logged in (a connection restart) by using the 3155 same Connection ID (CID) as an existing connection as well as the 3156 same session identifying elements of the session to which the old 3157 connection was associated. 3159 4.6.3.3. Logout Request and Response 3161 Logout Requests and Responses are used for the orderly closing of 3162 connections for recovery or maintenance. The logout request may be 3163 issued following a target prompt (through an asynchronous message) 3164 or at an initiators initiative. When issued on the connection to 3165 be logged out no other request may follow it. 3167 The Logout response indicates that the connection or session 3168 cleanup is completed and no other responses will arrive on the 3169 connection (if received on the logging out connection). In 3170 addition, the Logout Response indicates how long the target will 3171 continue to hold resources for recovery (e.g., command execution 3172 that continues on a new connection) in the Time2Retain field and 3173 how long the initiator must wait before proceeding with recovery 3174 in the Time2Wait field. 3176 4.6.3.4. SNACK Request 3178 With the SNACK Request, the initiator requests retransmission of 3179 numbered-responses or data from the target. A single SNACK request 3180 covers a contiguous set of missing items, called a run, of a given 3181 type of items. The type is indicated in a type field in the PDU 3182 header. The run is composed of an initial item (StatSN, DataSN, 3183 R2TSN) and the number of missed Status, Data, or R2T PDUs. For 3184 long data-in sequences, the target may request (at predefined 3185 minimum intervals) a positive acknowledgement for the data sent. A 3186 SNACK request with a type field that indicates ACK and the number 3187 of Data-In PDUs acknowledged conveys this positive 3188 acknowledgement. 3190 4.6.3.5. Reject 3192 Reject enables the target to report an iSCSI error condition 3193 (e.g., protocol, unsupported option) that uses a Reason field in 3194 the PDU header and includes the complete header of the bad PDU in 3195 the Reject PDU data segment. 3197 4.6.3.6. NOP-Out Request and NOP-In Response 3199 This request/response pair may be used by an initiator and target 3200 as a "ping" mechanism to verify that a connection/session is still 3201 active and all of its components are operational. Such a ping may 3202 be triggered by the initiator or target. The triggering party 3203 indicates that it wants a reply by setting a value different from 3204 the default 0xffffffff in the corresponding Initiator/Target 3205 Transfer Tag. 3207 NOP-In/NOP-Out may also be used "unidirectional" to convey to the 3208 initiator/target command, status or data counter values when there 3209 is no other "carrier" and there is a need to update the 3210 initiator/target. 3212 5. SCSI Mode Parameters for iSCSI 3214 There are no iSCSI specific mode pages. 3216 6. Login and Full Feature Phase Negotiation 3218 iSCSI parameters are negotiated at session or connection 3219 establishment by using Login Requests and Responses (see Section 3220 4.2.4) and during Full Feature Phase (Section 4.2.5) by using Text 3221 Requests and Responses. In both cases the mechanism used is an 3222 exchange of iSCSI-text-key=value pairs. For brevity, iSCSI-text- 3223 keys are called just keys in the rest of this document. 3225 Keys are either declarative or require negotiation and the key 3226 description indicates if the key is declarative or requires 3227 negotiation. 3229 For the declarative keys the declaring party sets a value for the 3230 key. The key specification indicates if the key can be declared by 3231 the initiator, target or both. 3233 For the keys that require negotiation, one of the parties (the 3234 proposing party) proposes a value or set of values by including 3235 the key=value in the data part of a Login or Text Request or 3236 Response. The other party (the accepting party) makes a selection 3237 based on the value or list of values proposed and includes the 3238 selected value in a key=value in the data part of the following 3239 Login or Text Response or Request. For most of the keys, both the 3240 initiator and target can be proposing parties. 3242 The login process proceeds in two stages - the security 3243 negotiation stage and the operational parameter negotiation stage. 3244 Both stages are optional but at least one of them has to be 3245 present to enable setting some mandatory parameters. 3247 If present, the security negotiation stage precedes the 3248 operational parameter negotiation stage. 3250 Progression from stage to stage is controlled by the T 3251 (Transition) bit in the Login Request/Response PDU header. Through 3252 the T bit set to 1, the initiator indicates that it would like to 3253 transition. The target agrees to the transition (and selects the 3254 next stage) when ready. A field in the Login PDU header indicates 3255 the current stage (CSG) and during transition, another field 3256 indicates the next stage (NSG) proposed (initiator) and selected 3257 (target). 3259 The Text negotiation process is used to negotiate or declare 3260 operational parameters. The negotiation process is controlled by 3261 the F (final) bit in the PDU header. During text negotiations, the 3262 F bit is used by the initiator to indicate that it is ready to 3263 finish the negotiation and by the Target to acquiesce the end of 3264 negotiation. 3266 Since some key=value pairs may not fit entirely in a single PDU, 3267 the C (continuation) bit is used (both in Login and Text) to 3268 indicate that "more follows". 3270 The text negotiation uses an additional mechanism by which a 3271 target may deliver larger amounts of data to an enquiring 3272 initiator. The target sets a Target Task Tag to be used as a 3273 bookmark which when returned by the initiator, means "go on". If 3274 reset to a "neutral value", it means "forget about the rest". 3276 This Section details types of keys and values used, the syntax 3277 rules for parameter formation, and the negotiation schemes to be 3278 used with different types of parameters. 3280 6.1. Text Format 3282 The initiator and target send a set of key=value pairs encoded in 3283 UTF-8 Unicode. All the text keys and text values specified in this 3284 document are to be presented and interpreted in the case in which 3285 they appear in this document. They are case sensitive. 3287 The following character symbols are used in this document for text 3288 items (the hexadecimal values represent Unicode code points): 3290 (a-z, A-Z) ) (0x61-0x7a, 0x41-0x5a) - letters 3291 (0-9) (0x30-0x39) - digits 3292 " " (0x20) - space 3293 "." (0x2e) - dot 3294 "-" (0x2d) - minus 3295 "+" (0x2b) - plus 3296 "@" (0x40) - commercial at 3297 "_" (0x5f) - underscore 3298 "=" (0x3d) - equal 3299 ":" (0x3a) - colon 3301 "/" (0x2f) - solidus or slash 3302 "[" (0x5b) - left bracket 3303 "]" (0x5d) - right bracket 3304 null (0x00) - null separator 3305 "," (0x2c) - comma 3306 "~" (0x7e) - tilde 3308 Key=value pairs may span PDU boundaries. An initiator or target 3309 that sends partial key=value text within a PDU indicates that more 3310 text follows by setting the C bit in the Text or Login Request or 3311 Text or Login Response to 1. Data segments in a series of PDUs 3312 that have the C bit set to 1 and end with a PDU that have the C 3313 bit set to 0, or include a single PDU that has the C bit set to 0 3314 have to be considered as forming a single logical-text-data- 3315 segment (LTDS). 3317 Every key=value pair, including the last or only pair in a LTDS, 3318 MUST be followed by one null (0x00) delimiter. 3320 A key-name is whatever precedes the first = in the key=value pair. 3321 The term key is used frequently in this document in place of key- 3322 name. 3324 A value is whatever follows the first = in the key=value pair up 3325 to the end of the key=value pair, but not including the null 3326 delimiter. 3328 The following definitions will be used in the rest of this 3329 document: 3331 - standard-label: A string of one or more characters that 3332 consist of letters, digits, dot, minus, plus, commercial at, 3333 or underscore. A standard-label MUST begin with a capital 3334 letter and must not exceed 63 characters. 3336 - key-name: A standard-label. 3338 - text-value: A string of zero or more characters that consist 3339 of letters, digits, dot, minus, plus, commercial at, 3340 underscore, slash, left bracket, right bracket, or colon. 3342 - iSCSI-name-value: A string of one or more characters that 3343 consist of minus, dot, colon, or any character allowed by 3344 the output of the iSCSI string-prep template as specified in 3345 [RFC3722] (see also Section 4.2.7.2). 3347 - iSCSI-local-name-value: A UTF-8 string; no null characters 3348 are allowed in the string. This encoding is to be used for 3349 localized (internationalized) aliases. 3351 - boolean-value: The string "Yes" or "No". 3353 - hex-constant: A hexadecimal constant encoded as a string 3354 that starts with "0x" or "0X" followed by one or more digits 3355 or the letters a, b, c, d, e, f, A, B, C, D, E, or F. Hex- 3356 constants are used to encode numerical values or binary 3357 strings. When used to encode numerical values, the excessive 3358 use of leading 0 digits is discouraged. The string following 3359 0X (or 0x) represents a base16 number that starts with the 3360 most significant base16 digit, followed by all other digits 3361 in decreasing order of significance and ending with the 3362 least-significant base16 digit. When used to encode binary 3363 strings, hexadecimal constants have an implicit byte-length 3364 that includes four bits for every hexadecimal digit of the 3365 constant, including leading zeroes. For example, a hex- 3366 constant of n hexadecimal digits has a byte-length of (the 3367 integer part of) (n+1)/2. 3369 - decimal-constant: An unsigned decimal number with the digit 3370 0 or a string of one or more digits that start with a non- 3371 zero digit. Decimal-constants are used to encode numerical 3372 values or binary strings. Decimal constants can only be used 3373 to encode binary strings if the string length is explicitly 3374 specified. There is no implicit length for decimal strings. 3375 Decimal-constant MUST NOT be used for parameter values if 3376 the values can be equal or greater than 2**64 (numerical) or 3377 for binary strings that can be longer than 64 bits. 3379 - base64-constant: base64 constant encoded as a string that 3380 starts with "0b" or "0B" followed by 1 or more digits or 3381 letters or plus or slash or equal. The encoding is done 3382 according to [RFC4648] and each character, except equal, 3383 represents a base64 digit or a 6-bit binary string. Base64- 3385 constants are used to encode numerical-values or binary 3386 strings. When used to encode numerical values, the excessive 3387 use of leading 0 digits (encoded as A) is discouraged. The 3388 string following 0B (or 0b) represents a base64 number that 3389 starts with the most significant base64 digit, followed by 3390 all other digits in decreasing order of significance and 3391 ending with the least-significant base64 digit; the least 3392 significant base64 digit may be optionally followed by pad 3393 digits (encoded as equal) that are not considered as part of 3394 the number. When used to encode binary strings, base64- 3395 constants have an implicit byte-length that includes six 3396 bits for every character of the constant, excluding trailing 3397 equals (i.e., a base64-constant of n base64 characters 3398 excluding the trailing equals has a byte-length of ((the 3399 integer part of) (n*3/4)). Correctly encoded base64 strings 3400 cannot have n values of 1, 5 ... k*4+1. 3402 - numerical-value: An unsigned integer always less than 2**64 3403 encoded as a decimal-constant or a hex-constant. Unsigned 3404 integer arithmetic applies to numerical-values. 3406 - large-numerical-value: An unsigned integer that can be 3407 larger than or equal to 2**64 encoded as a hex constant, or 3408 base64-constant. Unsigned integer arithmetic applies to 3409 large-numeric-values. 3411 - numeric-range: Two numerical-values separated by a tilde 3412 where the value to the right of tilde must not be lower than 3413 the value to the left. 3415 - regular-binary-value: A binary string not longer than 64 3416 bits encoded as a decimal constant, hex constant, or base64- 3417 constant. The length of the string is either specified by 3418 the key definition or is the implicit byte-length of the 3419 encoded string. 3421 - large-binary-value: A binary string longer than 64 bits 3422 encoded as a hex-constant or base64-constant. The length of 3423 the string is either specified by the key definition or is 3424 the implicit byte-length of the encoded string. 3426 - binary-value: A regular-binary-value or a large-binary- 3427 value. Operations on binary values are key specific. 3429 - simple-value: Text-value, iSCSI-name-value, boolean-value, 3430 numeric-value, a numeric-range, or a binary-value. 3432 - list-of-values: A sequence of text-values separated by a 3433 comma. 3435 If not otherwise specified, the maximum length of a simple-value 3436 (not its encoded representation) is 255 bytes not including the 3437 delimiter (comma or zero byte). 3439 Any iSCSI target or initiator MUST support receiving at least 8192 3440 bytes of key=value data in a negotiation sequence. When proposing 3441 or accepting authentication methods that explicitly require 3442 support for very long authentication items, the initiator and 3443 target MUST support receiving of at least 64 kilobytes of 3444 key=value data. 3446 6.2. Text Mode Negotiation 3448 During login, and thereafter, some session or connection 3449 parameters are either declared or negotiated through an exchange 3450 of textual information. 3452 The initiator starts the negotiation and/or declaration through a 3453 Text or Login request and indicates when it is ready for 3454 completion (by setting the F bit to 1 and keeping it to 1 in a 3455 Text Request or the T bit in the Login Request). As negotiation 3456 text may span PDU boundaries, a Text or Login Request or Text or 3457 Login Response PDU that have the C bit set to 1 MUST NOT have the 3458 F/T bit set to 1. 3460 A target receiving a Text or Login Request with the C bit set to 1 3461 MUST answer with a Text or Login Response with no data segment 3462 (DataSegmentLength 0). An initiator receiving a Text or Login 3463 Response with the C bit set to 1 MUST answer with a Text or Login 3464 Request with no data segment (DataSegmentLength 0). 3466 A target or initiator SHOULD NOT use a Text or Login Response or 3467 Text or Login Request with no data segment (DataSegmentLength 0) 3468 unless explicitly required by a general or a key-specific 3469 negotiation rule. 3471 There MUST NOT be more than one outstanding Text Request, or Text 3472 Response PDU on an iSCSI connection. An outstanding PDU in this 3473 context is one that has not been acknowledged by the remote iSCSI 3474 side. 3476 The format of a declaration is: 3478 Declarer-> = 3480 The general format of text negotiation is: 3482 Proposer-> = 3484 Acceptor-> ={|NotUnderstood|Irrelevant|Reject} 3486 Thus a declaration is a one-way textual exchange (unless the key 3487 is not understood by the receiver) while a negotiation is a two- 3488 way exchange. 3490 The proposer or declarer can either be the initiator or the 3491 target, and the acceptor can either be the target or initiator, 3492 respectively. Targets are not limited to respond to key=value 3493 pairs as proposed by the initiator. The target may propose 3494 key=value pairs of its own. 3496 All negotiations are explicit (i.e., the result MUST only be based 3497 on newly exchanged or declared values). There are no implicit 3498 proposals. If a proposal is not made, then a reply cannot be 3499 expected. Conservative design also requires that default values 3500 should not be relied upon when use of some other value has serious 3501 consequences. 3503 The value proposed or declared can be a numerical-value, a 3504 numerical-range defined by lower and upper value with both 3505 integers separated by tilde, a binary value, a text-value, an 3506 iSCSI-name-value, an iSCSI-local-name-value, a boolean-value (Yes 3507 or No), or a list of comma separated text-values. A range, a 3508 large-numerical-value, an iSCSI-name-value and an iSCSI-local- 3509 name-value MAY ONLY be used if it is explicitly allowed. An 3510 accepted value can be a numerical-value, a large-numerical-value, 3511 a text-value, or a boolean-value. 3513 If a specific key is not relevant for the current negotiation, the 3514 acceptor may answer with the constant "Irrelevant" for all types 3515 of negotiation. However the negotiation is not considered as 3516 failed if the answer is "Irrelevant". The "Irrelevant" answer is 3517 meant for those cases in which several keys are presented by a 3518 proposing party but the selection made by the acceptor for one of 3519 the keys makes other keys irrelevant. The following example 3520 illustrates the use of "Irrelevant": 3522 I->T InitialR2T=No,ImmediateData=Yes,FirstBurstLength=4192 3523 T->I InitialR2T=Yes,ImmediateData=No,FirstBurstLength=Irrelevant 3525 I->T X-rdname-vkey1=(bla,alb,None), X-rdname-vkey2=(bla,alb) 3526 T->I X-rdname-vkey1=None, X-rdname-vkey2=Irrelevant 3528 Any key not understood by the acceptor may be ignored by the 3529 acceptor without affecting the basic function. However, the answer 3530 for a key not understood MUST be key=NotUnderstood. Note that 3531 NotUnderstood is a valid answer for both declarative and 3532 negotiated keys. The general iSCSI philosophy is that 3533 comprehension precedes processing for any iSCSI key. A proposer 3534 of an iSCSI key, negotiated or declarative, in a text key exchange 3535 MUST thus be able to properly handle a NotUnderstood response. 3537 The proper way to handle a NotUnderstood response depends on where 3538 the key is specified and whether the key is declarative vs. 3539 negotiated. An iSCSI implementation MUST comprehend all text keys 3540 defined in iSCSI Protocol specifications from RFC 3720 through the 3541 RFC associated with the highest protocol version that the 3542 implementation has offered (or has negotiated, in the case of an 3543 acceptor) for the iSCSIProtocolLevel key in a negotiation. 3544 Returning a NotUnderstood response on any of these text keys 3545 therefore MUST be considered a protocol error and handled 3546 accordingly. For all other "later" keys, i.e. text keys defined 3547 in specifications associated with higher values of 3548 iSCSIProtocolLevel, a NotUnderstood answer concludes the 3549 negotiation for a negotiated key whereas for a declarative key, a 3550 NotUnderstood answer simply informs the declarer of a lack of 3551 comprehension by the receiver. 3553 In either case, a NotUnderstood answer always requires that the 3554 protocol behavior associated with that key not be used within the 3555 scope of the key (connection/session) by either side. 3557 The constants "None", "Reject", "Irrelevant", and "NotUnderstood" 3558 are reserved and MUST ONLY be used as described here. Violation of 3559 this rule is a protocol error (in particular the use of "Reject", 3560 "Irrelevant", and "NotUnderstood" as proposed values). 3562 Reject or Irrelevant are legitimate negotiation options where 3563 allowed but their excessive use is discouraged. A negotiation is 3564 considered complete when the acceptor has sent the key value pair 3565 even if the value is "Reject", "Irrelevant", or "NotUnderstood". 3566 Sending the key again would be a re-negotiation and is forbidden 3567 for many keys. 3569 If the acceptor sends "Reject" as an answer the negotiated key is 3570 left at its current value (or default if no value was set). If the 3571 current value is not acceptable to the proposer on the connection 3572 or to the session it is sent, the proposer MAY choose to terminate 3573 the connection or session. 3575 All keys in this document MUST be supported by iSCSI initiators 3576 and targets when used as specified here. If used as specified, 3577 these keys MUST NOT be answered with NotUnderstood. 3579 Implementers may introduce new private keys by prefixing them with 3580 X- followed by their (reversed) domain name, or with new public 3581 keys registered with IANA. For example, the entity owning the 3582 domain example.com can issue: 3584 X-com.example.bar.foo.do_something=3 3586 Each new public key in the course of standardization MUST define 3587 the acceptable responses to the key, including NotUnderstood as 3588 appropriate. Unlike [RFC3720], note that this document prohibits 3589 the X# prefix for new public keys. Based on iSCSI implementation 3590 experience, we know that there is no longer a need for a standard 3591 name prefix for keys that allow NotUnderstood response. Note that 3592 NotUnderstood will generally have to be allowed for new public 3593 keys for backwards compatibility, as well as for private X- keys. 3594 Thus the name prefix "X#" in new public key names does not carry 3595 any significance. New public key names MUST NOT begin with "X#" 3596 prefix to avoid confusion. 3598 Implementers MAY also introduce new values, but ONLY for new keys 3599 or authentication methods (see Section 12), or digests (see 3600 Section 13.1). 3602 Whenever parameter action or acceptance are dependent on other 3603 parameters, the dependency rules and parameter sequence must be 3604 specified with the parameters. 3606 In the Login Phase (see Section 6.3), every stage is a separate 3607 negotiation. In the FullFeaturePhase, a Text Request Response 3608 sequence is a negotiation. Negotiations MUST be handled as atomic 3609 operations. For example, all negotiated values go into effect 3610 after the negotiation concludes in agreement or are ignored if the 3611 negotiation fails. 3613 Some parameters may be subject to integrity rules (e.g., 3614 parameter-x must not exceed parameter-y or parameter-u not 1 3615 implies parameter-v be Yes). Whenever required, integrity rules 3616 are specified with the keys. Checking for compliance with the 3617 integrity rule must only be performed after all the parameters are 3618 available (the existent and the newly negotiated). An iSCSI target 3619 MUST perform integrity checking before the new parameters take 3620 effect. An initiator MAY perform integrity checking. 3622 An iSCSI initiator or target MAY terminate a negotiation that does 3623 not terminate within an implementation-specific reasonable time or 3624 number of exchanges, but SHOULD allow at least six (6) exchanges. 3626 6.2.1. List negotiations 3628 In list negotiation, the originator sends a list of values (which 3629 may include "None") in its order of preference. 3631 The responding party MUST respond with the same key and the first 3632 value that it supports (and is allowed to use for the specific 3633 originator) selected from the originator list. 3635 The constant "None" MUST always be used to indicate a missing 3636 function. However, "None" is only a valid selection if it is 3637 explicitly proposed. When "None" is proposed as a selection item 3638 in a negotiation for a key, it indicates to the responder that not 3639 supporting any functionality related to that key is legal, and if 3640 "None" is the negotiation result for such a key, it means that 3641 key-specific semantics are not operational for the negotiation 3642 scope (connection or session) of that key. 3644 If an acceptor does not understand any particular value in a list, 3645 it MUST ignore it. If an acceptor does not support, does not 3646 understand, or is not allowed to use any of the proposed options 3647 with a specific originator, it may use the constant "Reject" or 3648 terminate the negotiation. The selection of a value not proposed 3649 MUST be handled by the originator as a protocol error. 3651 6.2.2. Simple-value Negotiations 3653 For simple-value negotiations, the accepting party MUST answer 3654 with the same key. The value it selects becomes the negotiation 3655 result. 3657 Proposing a value not admissible (e.g., not within the specified 3658 bounds) MAY be answered with the constant "Reject", otherwise the 3659 acceptor MUST select an admissible value. 3661 The selection, by the acceptor, of a value not admissible under 3662 the selection rules is considered a protocol error. The selection 3663 rules are key-specific. 3665 For a numerical range the value selected MUST be an integer within 3666 the proposed range or "Reject" (if the range is unacceptable). 3668 For Boolean negotiations (i.e., keys taking the values Yes or No), 3669 the accepting party MUST answer with the same key and the result 3670 of the negotiation when the received value does not determine that 3671 result by itself. The last value transmitted becomes the 3672 negotiation result. The rules for selecting the value to answer 3673 with are expressed as Boolean functions of the value received, and 3674 the value that the accepting party would have selected if given a 3675 choice. 3677 Specifically, the two cases in which answers are OPTIONAL are: 3679 - The Boolean function is "AND" and the value "No" is 3680 received. The outcome of the negotiation is "No". 3682 - The Boolean function is "OR" and the value "Yes" is 3683 received. The outcome of the negotiation is "Yes". 3685 Responses are REQUIRED in all other cases, and the value chosen 3686 and sent by the acceptor becomes the outcome of the negotiation. 3688 6.3. Login Phase 3690 The Login Phase establishes an iSCSI connection between an 3691 initiator and a target; it creates also a new session or 3692 associates the connection to an existing session. The Login Phase 3693 sets the iSCSI protocol parameters, security parameters, and 3694 authenticates the initiator and target to each other. 3696 The Login Phase is only implemented via Login request and 3697 responses. The whole Login Phase is considered as a single task 3698 and has a single Initiator Task Tag (similar to the linked SCSI 3699 commands). 3701 There MUST NOT be more than one outstanding Login Request, or 3702 Login Response on an iSCSI connection. An outstanding PDU in this 3703 context is one that has not been acknowledged by the remote iSCSI 3704 side. 3706 The default MaxRecvDataSegmentLength is used during Login. 3708 The Login Phase sequence of requests and responses proceeds as 3709 follows: 3711 - Login initial request 3713 - Login partial response (optional) 3714 - More Login requests and responses (optional) 3716 - Login Final-Response (mandatory) 3718 The initial login request of any connection MUST include the 3719 InitiatorName key=value pair. The initial login request of the 3720 first connection of a session MAY also include the SessionType 3721 key=value pair. For any connection within a session whose type is 3722 not "Discovery", the first login request MUST also include the 3723 TargetName key=value pair. 3725 The Login Final-response accepts or rejects the Login request. 3727 The Login Phase MAY include a SecurityNegotiation stage and a 3728 LoginOperationalNegotiation stage and MUST include at least one of 3729 them, but the included stage MAY be empty except for the mandatory 3730 names. 3732 The login requests and responses contain a field (CSG) that 3733 indicates the current negotiation stage (SecurityNegotiation or 3734 LoginOperationalNegotiation). If both stages are used, the 3735 SecurityNegotiation MUST precede the LoginOperationalNegotiation. 3737 Some operational parameters can be negotiated outside the login 3738 through Text requests and responses. 3740 Authentication-related security keys (Section 12 ) MUST be 3741 completely negotiated within the Login Phase. The use of 3742 underlying IPsec security is specified in Section 9.3 and in 3743 [RFC3723]. iSCSI support for security within the protocol only 3744 consists of authentication in the Login Phase. 3746 In some environments, a target or an initiator is not interested 3747 in authenticating its counterpart. It is possible to bypass 3748 authentication through the Login request and response. 3750 The initiator and target MAY want to negotiate iSCSI 3751 authentication parameters. Once this negotiation is completed, the 3752 channel is considered secure. 3754 Most of the negotiation keys are only allowed in a specific stage. 3755 The SecurityNegotiation keys appear in Section 12 and the 3756 LoginOperationalNegotiation keys appear in Section 13. Only a 3757 limited set of keys (marked as Any-Stage in Section 13) may be 3758 used in any of the two stages. 3760 Any given Login request or response belongs to a specific stage; 3761 this determines the negotiation keys allowed with the request or 3762 response. It is considered to be a protocol error to send a key 3763 not allowed in the current stage. 3765 Stage transition is performed through a command exchange 3766 (request/response) that carries the T bit and the same CSG code. 3767 During this exchange, the next stage is selected by the target 3768 through the "next stage" code (NSG). The selected NSG MUST NOT 3769 exceed the value stated by the initiator. The initiator can 3770 request a transition whenever it is ready, but a target can only 3771 respond with a transition after one is proposed by the initiator. 3773 In a negotiation sequence, the T bit settings in one pair of login 3774 request-responses have no bearing on the T bit settings of the 3775 next pair. An initiator that has a T bit set to 1 in one pair and 3776 is answered with a T bit setting of 0 may issue the next request 3777 with T bit set to 0. 3779 When a transition is requested by the initiator and acknowledged 3780 by the target, both the initiator and target switch to the 3781 selected stage. 3783 Targets MUST NOT submit parameters that require an additional 3784 initiator login request in a login response with the T bit set to 3785 1. 3787 Stage transitions during login (including entering and exit) are 3788 only possible as outlined in the following table: 3790 +-----------------------------------------------------------+ 3791 |From To -> | Security | Operational | FullFeature | 3792 | | | | | | 3793 | V | | | | 3794 +-----------------------------------------------------------+ 3795 | (start) | yes | yes | no | 3796 +-----------------------------------------------------------+ 3797 | Security | no | yes | yes | 3798 +-----------------------------------------------------------+ 3799 | Operational | no | no | yes | 3800 +-----------------------------------------------------------+ 3802 The Login Final-Response that accepts a Login Request can only 3803 come as a response to a Login request with the T bit set to 1, and 3804 both the request and response MUST indicate FullFeaturePhase as 3805 the next phase via the NSG field. 3807 Neither the initiator nor the target should attempt to declare or 3808 negotiate a parameter more than once during login except for 3809 responses to specific keys that explicitly allow repeated key 3810 declarations (e.g., TargetAddress). An attempt to 3811 renegotiate/redeclare parameters not specifically allowed MUST be 3812 detected by the initiator and target. If such an attempt is 3813 detected by the target, the target MUST respond with Login reject 3814 (initiator error); if detected by the initiator, the initiator 3815 MUST drop the connection. 3817 6.3.1. Login Phase Start 3819 The Login Phase starts with a login request from the initiator to 3820 the target. The initial login request includes: 3822 -Protocol version supported by the initiator. 3824 -iSCSI Initiator Name and iSCSI Target Name 3826 -ISID, TSIH, and connection Ids 3828 -Negotiation stage that the initiator is ready to enter. 3830 A login may create a new session or it may add a connection to an 3831 existing session. Between a given iSCSI Initiator Node (selected 3832 only by an InitiatorName) and a given iSCSI target defined by an 3833 iSCSI TargetName and a Target Portal Group Tag, the login results 3834 are defined by the following table: 3836 +----------------------------------------------------------------+ 3837 |ISID | TSIH | CID | Target action | 3838 +----------------------------------------------------------------+ 3839 |new | non-zero | any | fail the login | 3840 | | | | ("session does not exist") | 3841 +----------------------------------------------------------------+ 3842 |new | zero | any | instantiate a new session | 3843 +----------------------------------------------------------------+ 3844 |existing| zero | any | do session reinstatement | 3845 | | | | (see Section 6.3.5) | 3846 +----------------------------------------------------------------+ 3847 |existing| non-zero | new | add a new connection to | 3848 | | existing | | the session | 3849 +----------------------------------------------------------------+ 3850 |existing| non-zero |existing| do connection reinstatement| 3851 | | existing | | (see Section 7.1.4.3) | 3852 +----------------------------------------------------------------+ 3853 |existing| non-zero | any | fail the login | 3854 | | new | | ("session does not exist") | 3855 +----------------------------------------------------------------+ 3857 Determination of "existing" or "new" are made by the target. 3859 Optionally, the login request may include: 3861 -Security parameters 3862 OR 3864 -iSCSI operational parameters 3865 AND/OR 3867 -The next negotiation stage that the initiator is ready to 3868 enter. 3870 The target can answer the login in the following ways: 3872 -Login Response with Login reject. This is an immediate 3873 rejection from the target that causes the connection to 3874 terminate and the session to terminate if this is the first 3875 (or only) connection of a new session. The T bit and the CSG 3876 and NSG fields are reserved. 3878 -Login Response with Login accept as a final response (T bit 3879 set to 1 and the NSG in both request and response are set to 3880 FullFeaturePhase). The response includes the protocol 3881 version supported by the target and the session ID, and may 3882 include iSCSI operational or security parameters (that 3883 depend on the current stage). 3885 -Login Response with Login Accept as a partial response (NSG 3886 not set to FullFeaturePhase in both request and response) 3887 that indicates the start of a negotiation sequence. The 3888 response includes the protocol version supported by the 3889 target and either security or iSCSI parameters (when no 3890 security mechanism is chosen) supported by the target. 3892 If the initiator decides to forego the SecurityNegotiation stage, 3893 it issues the Login with the CSG set to 3894 LoginOperationalNegotiation and the target may reply with a Login 3895 Response that indicates that it is unwilling to accept the 3896 connection (see Section 11.13) without SecurityNegotiation and 3897 will terminate the connection with a response of Authentication 3898 failure (see Section 11.13.5). 3900 If the initiator is willing to negotiate iSCSI security, but is 3901 unwilling to make the initial parameter proposal and may accept a 3902 connection without iSCSI security, it issues the Login with the T 3903 bit set to 1, the CSG set to SecurityNegotiation, and NSG set to 3904 LoginOperationalNegotiation. If the target is also ready to skip 3905 security, the login response only contains the 3906 TargetPortalGroupTag key (see Section 13.9), the T bit set to 1, 3907 the CSG set to SecurityNegotiation, and NSG set to 3908 LoginOperationalNegotiation. 3910 An initiator that chooses to operate without iSCSI security and 3911 with all the operational parameters taking the default values 3912 issues the Login with the T bit set to 1, the CSG set to 3913 LoginOperationalNegotiation, and NSG set to FullFeaturePhase. If 3914 the target is also ready to forego security and can finish its 3915 LoginOperationalNegotiation, the Login response has T bit set to 3916 1, the CSG set to LoginOperationalNegotiation, and NSG set to 3917 FullFeaturePhase in the next stage. 3919 During the Login Phase the iSCSI target MUST return the 3920 TargetPortalGroupTag key with the first Login Response PDU with 3921 which it is allowed to do so (i.e., the first Login Response 3922 issued after the first Login Request with the C bit set to 0) for 3923 all session types. The TargetPortalGroupTag key value indicates 3924 the iSCSI portal group servicing the Login Request PDU. If the 3925 reconfiguration of iSCSI portal groups is a concern in a given 3926 environment, the iSCSI initiator should use this key to ascertain 3927 that it had indeed initiated the Login Phase with the intended 3928 target portal group. 3930 6.3.2. iSCSI Security Negotiation 3932 The security exchange sets the security mechanism and 3933 authenticates the initiator user and the target to each other. The 3934 exchange proceeds according to the authentication method chosen in 3935 the negotiation phase and is conducted using the login requests' 3936 and responses' key=value parameters. 3938 An initiator directed negotiation proceeds as follows: 3940 -The initiator sends a login request with an ordered list of 3941 the options it supports (authentication algorithm). The 3942 options are listed in the initiator's order of preference. 3943 The initiator MAY also send private or public extension 3944 options. 3945 -The target MUST reply with the first option in the list it 3946 supports and is allowed to use for the specific initiator 3947 unless it does not support any in which case it MUST answer 3948 with "Reject" (see Section 6.2). The parameters are encoded 3949 in UTF8 as key=value. For security parameters, see Section 3950 12. 3952 -When the initiator considers that it is ready to conclude the 3953 SecurityNegotiation stage, it sets the T bit to 1 and the 3954 NSG to what it would like the next stage to be. The target 3955 will then set the T bit to 1 and set NSG to the next stage 3956 in the Login response when it finishes sending its security 3957 keys. The next stage selected will be the one the target 3958 selected. If the next stage is FullFeaturePhase, the target 3959 MUST respond with a Login Response with the TSIH value. 3961 If the security negotiation fails at the target, then the target 3962 MUST send the appropriate Login Response PDU. If the security 3963 negotiation fails at the initiator, the initiator SHOULD close the 3964 connection. 3966 It should be noted that the negotiation might also be directed by 3967 the target if the initiator does support security, but is not 3968 ready to direct the negotiation (propose options) - see Appendix B 3969 for an example. 3971 6.3.3. Operational Parameter Negotiation During the Login Phase 3973 Operational parameter negotiation during the login MAY be done: 3975 - Starting with the first Login request if the initiator does 3976 not propose any security/ integrity option. 3978 - Starting immediately after the security negotiation if the 3979 initiator and target perform such a negotiation. 3981 Operational parameter negotiation MAY involve several Login 3982 request-response exchanges started and terminated by the 3983 initiator. The initiator MUST indicate its intent to terminate the 3984 negotiation by setting the T bit to 1; the target sets the T bit 3985 to 1 on the last response. 3987 Even when the initiator indicates its intent to switch stage by 3988 setting the T bit to 1 in a Login request, the target MAY respond 3989 with a Login response with the T bit set to 0. In that case, the 3990 initiator SHOULD continue to set the T bit to 1 in subsequent 3991 Login requests (even empty) that it sends, until target sends a 3992 Login response with the T bit set to 1 or sends a key that 3993 requires initiator to set the T bit to 0. 3995 Some session specific parameters can only be specified during the 3996 Login Phase of the first connection of a session (i.e., begun by a 3997 login request that contains a zero-valued TSIH) - the leading 3998 Login Phase (e.g., the maximum number of connections that can be 3999 used for this session). 4001 A session is operational once it has at least one connection in 4002 FullFeaturePhase. New or replacement connections can only be added 4003 to a session after the session is operational. 4005 For operational parameters, see Section 13. 4007 6.3.4. Connection Reinstatement 4009 Connection reinstatement is the process of an initiator logging in 4010 with a ISID-TSIH-CID combination that is possibly active from the 4011 target's perspective, which causes the implicit logging out of the 4012 connection corresponding to the CID and reinstating a new Full 4013 Feature Phase iSCSI connection in its place (with the same CID). 4014 Thus, the TSIH in the Login Request PDU MUST be non-zero and CID 4015 does not change during a connection reinstatement. The Login 4016 request performs the logout function of the old connection if an 4017 explicit logout was not performed earlier. In sessions with a 4018 single connection, this may imply the opening of a second 4019 connection with the sole purpose of cleaning up the first. Targets 4020 MUST support opening a second connection even when they do not 4021 support multiple connections in Full Feature Phase if 4022 ErrorRecoveryLevel is 2 and SHOULD support opening a second 4023 connection if ErrorRecoveryLevel is less than 2. 4025 If the operational ErrorRecoveryLevel is 2, connection 4026 reinstatement enables future task reassignment. If the operational 4027 ErrorRecoveryLevel is less than 2, connection reinstatement is the 4028 replacement of the old CID without enabling task reassignment. In 4029 this case, all the tasks that were active on the old CID must be 4030 immediately terminated without further notice to the initiator. 4032 The initiator connection state MUST be CLEANUP_WAIT (Section 4033 8.1.3) when the initiator attempts a connection reinstatement. 4035 In practical terms, in addition to the implicit logout of the old 4036 connection, reinstatement is equivalent to a new connection login. 4038 6.3.5. Session Reinstatement, Closure, and Timeout 4040 Session reinstatement is the process of the initiator logging in 4041 with an ISID that is possibly active from the target's 4042 perspective. Thus implicitly logging out the session that 4043 corresponds to the ISID and reinstating a new iSCSI session in its 4044 place (with the same ISID). Therefore, the TSIH in the Login PDU 4045 MUST be zero to signal session reinstatement. Session 4046 reinstatement causes all the tasks that were active on the old 4047 session to be immediately terminated by the target without further 4048 notice to the initiator. 4050 The initiator session state MUST be FAILED (Section 8.3) when the 4051 initiator attempts a session reinstatement. 4053 Session closure is an event defined to be one of the following: 4055 - A successful "session close" logout. 4057 - A successful "connection close" logout for the last Full 4058 Feature Phase connection when no other connection in the 4059 session is waiting for cleanup (Section 8.2) and no tasks in 4060 the session are waiting for reassignment. 4062 Session timeout is an event defined to occur when the last 4063 connection state timeout expires and no tasks are waiting for 4064 reassignment. This takes the session to the FREE state (N6 4065 transition in the session state diagram). 4067 6.3.5.1. Loss of Nexus Notification 4069 The iSCSI layer provides the SCSI layer with the "I_T nexus loss" 4070 notification when any one of the following events happens: 4072 Successful completion of session reinstatement. 4073 Session closure event. 4074 Session timeout event. 4076 Certain SCSI object clearing actions may result due to the 4077 notification in the SCSI end nodes, as documented in Appendix E. 4079 6.3.6. Session Continuation and Failure 4081 Session continuation is the process by which the state of a 4082 preexisting session continues to be used by connection 4083 reinstatement (Section 6.3.4), or by adding a connection with a 4084 new CID. Either of these actions associates the new transport 4085 connection with the session state. 4087 Session failure is an event where the last Full Feature Phase 4088 connection reaches the CLEANUP_WAIT state (Section 8.2), or 4089 completes a successful recovery logout thus causing all active 4090 tasks (that are formerly allegiant to the connection) to start 4091 waiting for task reassignment. 4093 6.4. Operational Parameter Negotiation Outside the Login Phase 4095 Some operational parameters MAY be negotiated outside (after) the 4096 Login Phase. 4098 Parameter negotiation in Full Feature Phase is done through Text 4099 requests and responses. Operational parameter negotiation MAY 4100 involve several Text request-response exchanges, which the 4101 initiator always starts, terminates, and uses the same Initiator 4102 Task Tag. The initiator MUST indicate its intent to finish the 4103 negotiation by setting the F bit to 1; the target sets the F bit 4104 to 1 on the last response. 4106 If the target responds to a Text request with the F bit set to 1 4107 with a Text response with the F bit set to 0, the initiator should 4108 keep sending the Text request (even empty) with the F bit set to 4109 1, while it still wants to finish the negotiation, until it 4110 receives the Text response with the F bit set to 1. Responding to 4111 a Text request with the F bit set to 1 with an empty (no key=value 4112 pairs) response with the F bit set to 0 is discouraged. 4114 Even when the initiator indicates its intent to finish the 4115 negotiation by setting the F bit to 1 in a Text request, the 4116 target MAY respond with a Text response with the F bit set to 0. 4118 In that case, the initiator SHOULD continue to set the F bit to 1 4119 in subsequent Text requests (even empty) that it sends, until 4120 target sends the final Text response with the F bit set to 1. Note 4121 that in the same case of Text request with the F bit set to 1, 4122 target SHOULD NOT respond with an empty (no key=value pairs) Text 4123 response with the F bit set to 0, because such a response may 4124 cause the initiator to abandon negotiation. 4126 Targets MUST NOT submit parameters that require an additional 4127 initiator Text request in a Text response with the F bit set to 1. 4129 In a negotiation sequence, the F bit settings in one pair of Text 4130 request-responses have no bearing on the F bit settings of the 4131 next pair. An initiator that has the F bit set to 1 in a request 4132 and is being answered with an F bit setting of 0 may issue the 4133 next request with the F bit set to 0. 4135 Whenever the target responds with the F bit set to 0, it MUST set 4136 the Target Transfer Tag to a value other than the default 4137 0xffffffff. 4139 An initiator MAY reset an operational parameter negotiation by 4140 issuing a Text request with the Target Transfer Tag set to the 4141 value 0xffffffff after receiving a response with the Target 4142 Transfer Tag set to a value other than 0xffffffff. A target may 4143 reset an operational parameter negotiation by answering a Text 4144 request with a Reject PDU. 4146 Neither the initiator nor the target should attempt to declare or 4147 negotiate a parameter more than once during any negotiation 4148 sequence, except for responses to specific keys that explicitly 4149 allow repeated key declarations (e.g., TargetAddress). If detected 4150 by the target, this MUST result in a Reject PDU with a reason of 4151 "protocol error". The initiator MUST reset the negotiation as 4152 outlined above. 4154 Parameters negotiated by a text exchange negotiation sequence only 4155 become effective after the negotiation sequence is completed. 4157 7. iSCSI Error Handling and Recovery 4159 7.1. Overview 4161 7.1.1. Background 4163 The following two considerations prompted the design of much of 4164 the error recovery functionality in iSCSI: 4166 An iSCSI PDU may fail the digest check and be dropped, despite 4167 being received by the TCP layer. The iSCSI layer must 4168 optionally be allowed to recover such dropped PDUs. 4170 A TCP connection may fail at any time during the data 4171 transfer. All the active tasks must optionally be allowed 4172 to be continued on a different TCP connection within the 4173 same session. 4175 Implementations have considerable flexibility in deciding what 4176 degree of error recovery to support, when to use it and by which 4177 mechanisms to achieve the required behavior. Only the externally 4178 visible actions of the error recovery mechanisms must be 4179 standardized to ensure interoperability. 4181 This Section describes a general model for recovery in support of 4182 interoperability. See Appendix D for further detail on how the 4183 described model may be implemented. Compliant implementations do 4184 not have to match the implementation details of this model as 4185 presented, but the external behavior of such implementations must 4186 correspond to the externally observable characteristics of the 4187 presented model. 4189 7.1.2. Goals 4191 The major design goals of the iSCSI error recovery scheme are as 4192 follows: 4194 Allow iSCSI implementations to meet different requirements by 4195 defining a collection of error recovery mechanisms that 4196 implementations may choose from. 4198 Ensure interoperability between any two implementations 4199 supporting different sets of error recovery capabilities. 4201 Define the error recovery mechanisms to ensure command 4202 ordering even in the face of errors, for initiators that 4203 demand ordering. 4205 Do not make additions in the fast path, but allow moderate 4206 complexity in the error recovery path. 4208 Prevent both the initiator and target from attempting to 4209 recover the same set of PDUs at the same time. For example, 4210 there must be a clear "error recovery functionality 4211 distribution" between the initiator and target. 4213 7.1.3. Protocol Features and State Expectations 4215 The initiator mechanisms defined in connection with error recovery 4216 are: 4218 a) NOP-OUT to probe sequence numbers of the target (Section 4219 11.18) 4220 b) Command retry (Section 7.2.1) 4221 c) Recovery R2T support (Section 7.8) 4222 d) Requesting retransmission of status/data/R2T using the 4223 SNACK facility (Section 11.16) 4224 e) Acknowledging the receipt of the data (Section 11.16) 4225 f) Reassigning the connection allegiance of a task to a 4226 different TCP connection (Section 7.2.2) 4227 g) Terminating the entire iSCSI session to start afresh 4228 (Section 7.1.4.4) 4230 The target mechanisms defined in connection with error recovery 4231 are: 4233 a) NOP-IN to probe sequence numbers of the initiator (Section 4234 11.19) 4235 b) Requesting retransmission of data using the recovery R2T 4236 feature (Section 7) 4237 c) SNACK support (Section 11.16) 4238 d) Requesting that parts of read data be acknowledged (Section 4239 11.7.2) 4240 e) Allegiance reassignment support (Section 7.2.2) 4241 f) Terminating the entire iSCSI session to force the initiator 4242 to start over (Section 7.1.4.4) 4244 For any outstanding SCSI command, it is assumed that iSCSI, in 4245 conjunction with SCSI at the initiator, is able to keep enough 4246 information to be able to rebuild the command PDU, and that 4247 outgoing data is available (in host memory) for retransmission 4248 while the command is outstanding. It is also assumed that at the 4249 target, incoming data (read data) MAY be kept for recovery or it 4250 can be reread from a device server. 4252 It is further assumed that a target will keep the "status & sense" 4253 for a command it has executed if it supports status 4254 retransmission. 4256 A target that agrees to support data retransmission is expected to 4257 be prepared to retransmit the outgoing data (i.e., Data-In) on 4258 request until either the status for the completed command is 4259 acknowledged, or the data in question has been separately 4260 acknowledged. 4262 7.1.4. Recovery Classes 4264 iSCSI enables the following classes of recovery (in the order of 4265 increasing scope of affected iSCSI tasks): 4267 - Within a command (i.e., without requiring command restart). 4269 - Within a connection (i.e., without requiring the connection 4270 to be rebuilt, but perhaps requiring command restart). 4272 - Connection recovery (i.e., perhaps requiring connections to 4273 be rebuilt and commands to be reissued). 4275 - Session recovery. 4277 The recovery scenarios detailed in the rest of this Section are 4278 representative rather than exclusive. In every case, they detail 4279 the lowest class recovery that MAY be attempted. The implementer 4280 is left to decide under which circumstances to escalate to the 4281 next recovery class and/or what recovery classes to implement. 4282 Both the iSCSI target and initiator MAY escalate the error 4283 handling to an error recovery class, which impacts a larger number 4284 of iSCSI tasks in any of the cases identified in the following 4285 discussion. 4287 In all classes, the implementer has the choice of deferring errors 4288 to the SCSI initiator (with an appropriate response code), in 4289 which case the task, if any, has to be removed from the target and 4290 all the side-effects, such as ACA, must be considered. 4292 Use of within-connection and within-command recovery classes MUST 4293 NOT be attempted before the connection is in Full Feature Phase. 4295 In the detailed description of the recovery classes, the mandating 4296 terms (MUST, SHOULD, MAY, etc.) indicate normative actions to be 4297 executed if the recovery class is supported (see Section 7.1.5 for 4298 the related negotiation semantics) and used. 4300 7.1.4.1. Recovery Within-command 4302 At the target, the following cases lend themselves to within- 4303 command recovery: 4305 a) Lost data PDU - realized through one of the following: 4306 b) Data digest error - dealt with as specified in Section 7.8, 4307 using the option of a recovery R2T. 4308 c) Sequence reception timeout (no data or partial-data-and-no-F- 4309 bit) - considered an implicit sequence error and dealt with 4310 as specified in Section 7.9, using the option of a recovery 4311 R2T. 4312 d) Header digest error, which manifests as a sequence reception 4313 timeout or a sequence error - dealt with as specified in 4314 Section 7.9, using the option of a recovery R2T. 4316 At the initiator, the following cases lend themselves to within- 4317 command recovery: 4319 a) Lost data PDU or lost R2T - realized through one of the 4320 following: 4321 b) Data digest error - dealt with as specified in Section 7.8, 4322 using the option of a SNACK. 4323 c) Sequence reception timeout (no status) or response reception 4324 timeout - dealt with as specified in Section 7.9, using the 4325 option of a SNACK. 4326 d) Header digest error, which manifests as a sequence reception 4327 timeout or a sequence error - dealt with as specified in 4328 Section 7.9, using the option of a SNACK. 4330 To avoid a race with the target, which may already have a recovery 4331 R2T or a termination response on its way, an initiator SHOULD NOT 4332 originate a SNACK for an R2T based on its internal timeouts (if 4333 any). Recovery in this case is better left to the target. 4335 The timeout values used by the initiator and target are outside 4336 the scope of this document. Sequence reception timeout is 4337 generally a large enough value to allow the data sequence transfer 4338 to be complete. 4340 7.1.4.2. Recovery Within-connection 4342 At the initiator, the following cases lend themselves to within- 4343 connection recovery: 4345 a) Requests not acknowledged for a long time. Requests are 4346 acknowledged explicitly through ExpCmdSN or implicitly by 4347 receiving data and/or status. The initiator MAY retry non- 4348 acknowledged commands as specified in Section 7.2. 4349 b) Lost iSCSI numbered Response. It is recognized by either 4350 identifying a data digest error on a Response PDU or a Data- 4351 In PDU carrying the status, or by receiving a Response PDU 4352 with a higher StatSN than expected. In the first case, digest 4353 error handling is done as specified in Section 7.8 using the 4354 option of a SNACK. In the second case, sequence error 4355 handling is done as specified in Section 7.9, using the 4356 option of a SNACK. 4358 At the target, the following cases lend themselves to within- 4359 connection recovery: 4361 - Status/Response not acknowledged for a long time. The target 4362 MAY issue a NOP-IN (with a valid Target Transfer Tag or 4363 otherwise) that carries the next status sequence number it 4364 is going to use in the StatSN field. This helps the 4365 initiator detect any missing StatSN(s) and issue a SNACK for 4366 the status. 4368 The timeout values used by the initiator and the target are 4369 outside the scope of this document. 4371 7.1.4.3. Connection Recovery 4373 At an iSCSI initiator, the following cases lend themselves to 4374 connection recovery: 4376 a) TCP connection failure: The initiator MUST close the 4377 connection. It then MUST either implicitly or explicitly 4378 logout the failed connection with the reason code "remove the 4379 connection for recovery" and reassign connection allegiance 4380 for all commands still in progress associated with the failed 4381 connection on one or more connections (some or all of which 4382 MAY be newly established connections) using the "Task 4383 reassign" task management function (see Section 11.5.1). For 4384 an initiator, a command is in progress as long as it has not 4385 received a response or a Data-In PDU including status. 4387 Note: The logout function is mandatory. However, a new 4388 connection establishment is only mandatory if the failed 4389 connection was the last or only connection in the session. 4390 b) Receiving an Asynchronous Message that indicates one or all 4391 connections in a session has been dropped. The initiator 4392 MUST handle it as a TCP connection failure for the 4393 connection(s) referred to in the Message. 4395 At an iSCSI target, the following cases lend themselves to 4396 connection recovery: 4398 - TCP connection failure. The target MUST close the connection 4399 and, if more than one connection is available, the target 4400 SHOULD send an Asynchronous Message that indicates it has 4401 dropped the connection. Then, the target will wait for the 4402 initiator to continue recovery. 4404 7.1.4.4. Session Recovery 4406 Session recovery should be performed when all other recovery 4407 attempts have failed. Very simple initiators and targets MAY 4408 perform session recovery on all iSCSI errors and rely on recovery 4409 on the SCSI layer and above. 4411 Session recovery implies the closing of all TCP connections, 4412 internally aborting all executing and queued tasks for the given 4413 initiator at the target, terminating all outstanding SCSI commands 4414 with an appropriate SCSI service response at the initiator, and 4415 restarting a session on a new set of connection(s) (TCP connection 4416 establishment and login on all new connections). 4418 For possible clearing effects of session recovery on SCSI and 4419 iSCSI objects, refer to Appendix E. 4421 7.1.5. Error Recovery Hierarchy 4423 The error recovery classes described so far are organized into a 4424 hierarchy for ease in understanding and to limit the 4425 implementation complexity. With few and well defined recovery 4426 levels interoperability is easier to achieve. The attributes of 4427 this hierarchy are as follows: 4429 a) Each level is a superset of the capabilities of the 4430 previous level. For example, Level 1 support implies 4431 supporting all capabilities of Level 0 and more. 4432 b) As a corollary, supporting a higher error recovery level 4433 means increased sophistication and possibly an increase 4434 in resource requirements. 4435 c) Supporting error recovery level "n" is advertised and 4436 negotiated by each iSCSI entity by exchanging the text 4437 key "ErrorRecoveryLevel=n". The lower of the two 4438 exchanged values is the operational ErrorRecoveryLevel 4439 for the session. 4441 The following diagram represents the error recovery hierarchy. 4443 + 4444 / \ 4445 / 2 \ <-- Connection recovery 4446 +-----+ 4447 / 1 \ <-- Digest failure recovery 4448 +----------+ 4449 / 0 \ <-- Session failure recovery 4450 +---------------+ 4452 The following table lists the error recovery capabilities expected 4453 from the implementations that support each error recovery level. 4455 +-------------------+--------------------------------------------+ 4456 |ErrorRecoveryLevel | Associated Error recovery capabilities | 4457 +-------------------+--------------------------------------------+ 4458 | 0 | Session recovery class | 4459 | | (Session Recovery) | 4460 +-------------------+--------------------------------------------+ 4461 | 1 | Digest failure recovery (See Note below.) | 4462 | | plus the capabilities of ER Level 0 | 4463 +-------------------+--------------------------------------------+ 4464 | 2 | Connection recovery class | 4465 | | (Connection Recovery) | 4466 | | plus the capabilities of ER Level 1 | 4467 +-------------------+--------------------------------------------+ 4469 Note: Digest failure recovery is comprised of two recovery 4470 classes: Within-Connection recovery class (Recovery Within- 4471 connection) and Within-Command recovery class (Recovery Within- 4472 command). 4474 When a defined value of ErrorRecoveryLevel is proposed by an 4475 originator in a text negotiation, the originator MUST support the 4476 functionality defined for the proposed value and additionally, 4477 functionality corresponding to any defined value numerically less 4478 than the proposed. When a defined value of ErrorRecoveryLevel is 4479 returned by a responder in a text negotiation, the responder MUST 4480 support the functionality corresponding to the ErrorRecoveryLevel 4481 it is accepting. 4483 When either party attempts to use error recovery functionality 4484 beyond what is negotiated, the recovery attempts MAY fail unless 4485 an apriori agreement outside the scope of this document exists 4486 between the two parties to provide such support. 4488 Implementations MUST support error recovery level "0", while the 4489 rest are OPTIONAL to implement. In implementation terms, the 4490 above striation means that the following incremental 4491 sophistication with each level is required. 4493 +-------------------+--------------------------------------------+ 4494 |Level transition | Incremental requirement | 4495 +-------------------+--------------------------------------------+ 4496 | 0->1 | PDU retransmissions on the same connection| 4497 +-------------------+--------------------------------------------+ 4498 | 1->2 | Retransmission across connections and | 4499 | | allegiance reassignment | 4500 +-------------------+--------------------------------------------+ 4502 7.2. Retry and Reassign in Recovery 4504 This Section summarizes two important and somewhat related iSCSI 4505 protocol features used in error recovery. 4507 7.2.1. Usage of Retry 4509 By resending the same iSCSI command PDU ("retry") in the absence 4510 of a command acknowledgement (by way of an ExpCmdSN update) or a 4511 response, an initiator attempts to "plug" (what it thinks are) the 4512 discontinuities in CmdSN ordering on the target end. Discarded 4513 command PDUs, due to digest errors, may have created these 4514 discontinuities. 4516 Retry MUST NOT be used for reasons other than plugging command 4517 sequence gaps, and in particular, cannot be used for requesting 4518 PDU retransmissions from a target. Any such PDU retransmission 4519 requests for a currently allegiant command in progress may be made 4520 using the SNACK mechanism described in Section 11.16, although the 4521 usage of SNACK is OPTIONAL. 4523 If initiators, as part of plugging command sequence gaps as 4524 described above, inadvertently issue retries for allegiant 4525 commands already in progress (i.e., targets did not see the 4526 discontinuities in CmdSN ordering), the duplicate commands are 4527 silently ignored by targets as specified in Section 4.2.2.1. 4529 When an iSCSI command is retried, the command PDU MUST carry the 4530 original Initiator Task Tag and the original operational 4531 attributes (e.g., flags, function names, LUN, CDB etc.) as well as 4532 the original CmdSN. The command being retried MUST be sent on the 4533 same connection as the original command unless the original 4534 connection was already successfully logged out. 4536 7.2.2. Allegiance Reassignment 4538 By issuing a "task reassign" task management request (Section 4539 11.5.1), the initiator signals its intent to continue an already 4540 active command (but with no current connection allegiance) as part 4541 of connection recovery. This means that a new connection 4542 allegiance is requested for the command, which seeks to associate 4543 it to the connection on which the task management request is being 4544 issued. Before the allegiance reassignment is attempted for a 4545 task, an implicit or explicit Logout with the reason code "remove 4546 the connection for recovery" (see Section 11.14.1) MUST be 4547 successfully completed for the previous connection to which the 4548 task was allegiant. 4550 In reassigning connection allegiance for a command, the targets 4551 SHOULD continue the command from its current state. For example, 4552 when reassigning read commands, the target SHOULD take advantage 4553 of the ExpDataSN field provided by the Task Management function 4554 request (which must be set to zero if there was no data transfer) 4555 and bring the read command to completion by sending the remaining 4556 data and sending (or resending) the status. ExpDataSN 4557 acknowledges all data sent up to, but not including, the Data-In 4558 PDU and or R2T with DataSN (or R2TSN) equal to ExpDataSN. However, 4559 targets may choose to send/receive all unacknowledged data or all 4560 of the data on a reassignment of connection allegiance if unable 4561 to recover or maintain accurate state. Initiators MUST NOT 4562 subsequently request data retransmission through Data SNACK for 4563 PDUs numbered less than ExpDataSN (i.e., prior to the acknowledged 4564 sequence number). For all types of commands, a reassignment 4565 request implies that the task is still considered in progress by 4566 the initiator and the target must conclude the task appropriately 4567 if the target returns the "Function Complete" response to the 4568 reassignment request. This might possibly involve retransmission 4569 of data/R2T/status PDUs as necessary, but MUST involve the 4570 (re)transmission of the status PDU. 4572 It is OPTIONAL for targets to support the allegiance reassignment. 4573 This capability is negotiated via the ErrorRecoveryLevel text key 4574 during the login time. When a target does not support allegiance 4575 reassignment, it MUST respond with a Task Management response code 4576 of "Allegiance reassignment not supported". If allegiance 4577 reassignment is supported by the target, but the task is still 4578 allegiant to a different connection, or a successful recovery 4579 Logout of the previously allegiant connection was not performed, 4580 the target MUST respond with a Task Management response code of 4581 "Task still allegiant". 4583 If allegiance reassignment is supported by the target, the Task 4584 Management response to the reassignment request MUST be issued 4585 before the reassignment becomes effective. 4587 If a SCSI Command that involves data input is reassigned, any 4588 SNACK Tag it holds for a final response from the original 4589 connection is deleted and the default value of 0 MUST be used 4590 instead. 4592 7.3. Usage Of Reject PDU in Recovery 4594 Targets MUST NOT implicitly terminate an active task by sending a 4595 Reject PDU for any PDU exchanged during the life of the task. If 4596 the target decides to terminate the task, a Response PDU (SCSI, 4597 Text, Task, etc.) must be returned by the target to conclude the 4598 task. If the task had never been active before the Reject (i.e., 4599 the Reject is on the command PDU), targets should not send any 4600 further responses because the command itself is being discarded. 4602 The above rule means that the initiator can eventually expect a 4603 response on receiving Rejects, if the received Reject is for a PDU 4604 other than the command PDU itself. The non-command Rejects only 4605 have diagnostic value in logging the errors, and they can be used 4606 for retransmission decisions by the initiators. 4608 The CmdSN of the rejected command PDU (if it is a non-immediate 4609 command) MUST NOT be considered received by the target (i.e., a 4610 command sequence gap must be assumed for the CmdSN), even though 4611 the CmdSN of the rejected command PDU may be reliably ascertained. 4612 Upon receiving the Reject, the initiator MUST plug the CmdSN gap 4613 in order to continue to use the session. The gap may be plugged 4614 either by transmitting a command PDU with the same CmdSN, or by 4615 aborting the task (see SCS on how an abort may plug a CmdSN gap). 4617 When a data PDU is rejected and its DataSN can be ascertained, a 4618 target MUST advance ExpDataSN for the current data burst if a 4619 recovery R2T is being generated. The target MAY advance its 4620 ExpDataSN if it does not attempt to recover the lost data PDU. 4622 7.4. Error Recovery Considerations for Discovery Sessions 4624 7.4.1. ErrorRecoveryLevel for Discovery Sessions 4626 The negotiation of the key ErrorRecoveryLevel is not required for 4627 Discovery sessions -- i.e., for sessions that negotiated 4628 "SessionType=Discovery" -- because the default value of 0 is 4629 necessary and sufficient for Discovery sessions. It is however 4630 possible that some legacy iSCSI implementations might attempt to 4631 negotiate the ErrorRecoveryLevel key on Discovery sessions. When 4632 such a negotiation attempt is made by the remote side, a compliant 4633 iSCSI implementation MUST propose a value of 0 (zero) in response. 4634 The operational ErrorRecoveryLevel for Discovery sessions thus 4635 MUST 4636 be 0. This naturally follows from the functionality constraints 4637 that Section 4.3 imposes on Discovery sessions. 4639 7.4.2. Reinstatement Semantics for Discovery Sessions 4641 Discovery sessions are intended to be relatively short-lived. 4642 Initiators are not expected to establish multiple Discovery 4643 sessions to the same iSCSI Network Portal. An initiator may use 4644 the same iSCSI Initiator Name and ISID when establishing different 4645 unique sessions with different targets and/or different portal 4646 groups. This behavior is discussed in Section 10.1.1 and is, in 4647 fact, encouraged as conservative reuse of ISIDs. 4649 The ISID RULE in Section 4.4.3 states that there must not be more 4650 than one session with a matching 4-tuple: . While the spirit of the ISID 4652 RULE applies to Discovery sessions the same as it does for Normal 4653 sessions, note that some Discovery sessions differ from the Normal 4654 sessions in two important aspects: 4656 a) Because Appendix C allows a Discovery session to be 4657 established without specifying a TargetName key in the 4658 Login Request PDU (let us call such a session an "Unnamed" 4659 Discovery session), there is no Target Node context to 4660 enforce the ISID RULE. 4662 b) Portal Groups are defined only in the context of a Target 4663 Node. When the TargetName key is NULL-valued (i.e., not 4664 specified), the TargetPortalGroupTag thus cannot be 4665 ascertained to enforce the ISID RULE. 4667 The following two sections describe each of the two scenarios -- 4668 Named Discovery sessions and Unnamed Discovery sessions. 4670 7.4.2.1. Unnamed Discovery Sessions 4672 For Unnamed Discovery sessions, neither the TargetName nor the 4673 TargetPortalGroupTag is available to the targets in order to 4674 enforce the ISID RULE. So the following rule applies. 4676 UNNAMED ISID RULE: Targets MUST enforce the uniqueness of the 4677 following 4-tuple for Unnamed Discovery sessions: . The following semantics are implied by 4679 this uniqueness requirement. 4681 Targets SHOULD allow concurrent establishment of one Discovery 4682 session with each of its Network Portals by the same initiator 4683 port with a given iSCSI Node Name and an ISID. Each of the 4684 concurrent Discovery sessions, if established by the same 4685 initiator port to other Network Portals, MUST be treated as 4686 independent sessions -- i.e., one session MUST NOT reinstate the 4687 other. 4689 A new Unnamed Discovery session that has a matching 4690 to an existing 4691 Discovery session MUST reinstate the existing Unnamed Discovery 4692 session. Note thus that only an Unnamed Discovery session may 4693 reinstate an Unnamed Discovery session. 4695 7.4.2.2. Named Discovery Session 4697 For a Named Discovery session, the TargetName key is specified by 4698 the initiator and thus the target can unambiguously ascertain the 4699 TargetPortalGroupTag as well. Since all the four elements of the 4700 4-tuple are known, the ISID RULE MUST be enforced by targets with 4701 no changes from Section 4.4.3 semantics. A new session with a 4702 matching 4703 thus will reinstate an existing session. Note in this case that 4704 any new iSCSI session (Discovery or Normal) with the matching 4- 4705 tuple may reinstate an existing Named Discovery iSCSI session. 4707 7.4.3. Target PDUs During Discovery 4709 Targets SHOULD NOT send any responses other than a Text Response 4710 and Logout Response on a Discovery session, once in Full Feature 4711 Phase. 4713 Implementation Note: A target may simply drop the connection in a 4714 Discovery session when it would have requested a Logout via an 4715 Async Message on Normal sessions. 4717 7.5. Connection Timeout Management 4719 iSCSI defines two session-global timeout values (in seconds) - 4720 Time2Wait and Time2Retain - that are applicable when an iSCSI Full 4721 Feature Phase connection is taken out of service either 4722 intentionally or by an exception. Time2Wait is the initial 4723 "respite time" before attempting an explicit/implicit Logout for 4724 the CID in question or task reassignment for the affected tasks 4725 (if any). Time2Retain is the maximum time after the initial 4726 respite interval that the task and/or connection state(s) is/are 4727 guaranteed to be maintained on the target to cater to a possible 4728 recovery attempt. Recovery attempts for the connection and/or 4729 task(s) SHOULD NOT be made before Time2Wait seconds, but MUST be 4730 completed within Time2Retain seconds after that initial Time2Wait 4731 waiting period. 4733 7.5.1. Timeouts on Transport Exception Events 4735 A transport connection shutdown or a transport reset without any 4736 preceding iSCSI protocol interactions informing the end-points of 4737 the fact causes a Full Feature Phase iSCSI connection to be 4738 abruptly terminated. The timeout values to be used in this case 4739 are the negotiated values of DefaultTime2Wait (Section 13.15) and 4740 DefaultTime2Retain (Section 13.16) text keys for the session. 4742 7.5.2. Timeouts on Planned Decommissioning 4744 Any planned decommissioning of a Full Feature Phase iSCSI 4745 connection is preceded by either a Logout Response PDU, or an 4746 Async Message PDU. The Time2Wait and Time2Retain field values 4747 (Section 11.15) in a Logout Response PDU, and the Parameter2 and 4748 Parameter3 fields of an Async Message (AsyncEvent types "drop the 4749 connection" or "drop all the connections"; Section 11.9.1) specify 4750 the timeout values to be used in each of these cases. 4752 These timeout values are only applicable for the affected 4753 connection, and the tasks active on that connection. These 4754 timeout values have no bearing on initiator timers (if any) that 4755 are already running on connections or tasks associated with that 4756 session. 4758 7.6. Implicit Termination of Tasks 4760 A target implicitly terminates the active tasks due to iSCSI 4761 protocol dynamics in the following cases: 4763 a) When a connection is implicitly or explicitly logged out 4764 with the reason code of "Close the connection" and there 4765 are active tasks allegiant to that connection. 4767 b) When a connection fails and eventually the connection 4768 state times out (state transition M1 in Section 8.2.2) 4769 and there are active tasks allegiant to that connection. 4771 c) When a successful Logout with the reason code of "remove 4772 the connection for recovery" is performed while there are 4773 active tasks allegiant to that connection, and those 4774 tasks eventually time out after the Time2Wait and 4775 Time2Retain periods without allegiance reassignment. 4777 d) When a connection is implicitly or explicitly logged out 4778 with the reason code of "Close the session" and there are 4779 active tasks in that session. 4781 If the tasks terminated in the above cases a), b), c) and d)are 4782 SCSI tasks, they must be internally terminated as if with CHECK 4783 CONDITION status. This status is only meaningful for appropriately 4784 handling the internal SCSI state and SCSI side effects with 4785 respect to ordering because this status is never communicated back 4786 as a terminating status to the initiator. However additional 4787 actions may have to be taken at SCSI level depending on the SCSI 4788 context as defined by the SCSI standards (e.g., queued commands 4789 and ACA, UA for the next command on the I_T nexus in cases a), b), 4790 and c) etc. - see [SAM2] and [SPC3]). 4792 7.7. Format Errors 4794 The following two explicit violations of PDU layout rules are 4795 format errors: 4797 a) Illegal contents of any PDU header field except the 4798 Opcode (legal values are specified in Section 11). 4799 b) Inconsistent field contents (consistent field contents 4800 are specified in Section 11). 4802 Format errors indicate a major implementation flaw in one of the 4803 parties. 4805 When a target or an initiator receives an iSCSI PDU with a format 4806 error, it MUST immediately terminate all transport connections in 4807 the session either with a connection close or with a connection 4808 reset and escalate the format error to session recovery (see 4809 Section 7.1.4.4). 4811 All initiator-detected PDU construction errors MUST be considered 4812 as format errors. Some examples of such errors are: 4813 - NOP-In with a valid TTT but an invalid LUN 4815 - NOP-In with a valid ITT (i.e., a NOP-In response) and also a 4816 valid TTT 4818 - SCSI Response PDU with Status=CHECK CONDITION, but 4819 DataSegmentLength = 0 4821 7.8. Digest Errors 4823 The discussion of the legal choices in handling digest errors 4824 below excludes session recovery as an explicit option, but either 4825 party detecting a digest error may choose to escalate the error to 4826 session recovery. 4828 When a target or an initiator receives any iSCSI PDU, with a 4829 header digest error, it MUST either discard the header and all 4830 data up to the beginning of a later PDU or close the connection. 4831 Because the digest error indicates that the length field of the 4832 header may have been corrupted, the location of the beginning of a 4833 later PDU needs to be reliably ascertained by other means such as 4834 the operation of a sync and steering layer. 4836 When a target receives any iSCSI PDU with a payload digest error, 4837 it MUST answer with a Reject PDU with a reason code of Data- 4838 Digest-Error and discard the PDU. 4840 - If the discarded PDU is a solicited or unsolicited iSCSI 4841 data PDU (for immediate data in a command PDU, non-data PDU 4842 rule below applies), the target MUST do one of the 4843 following: 4845 i) Request retransmission with a recovery R2T. 4846 ii) Terminate the task with a response PDU with a CHECK 4847 CONDITION Status and an iSCSI Condition of "protocol 4848 service CRC error" (Section 11.4.7.2). If the target 4849 chooses to implement this option, it MUST wait to 4850 receive all the data (signaled by a Data PDU with the 4851 final bit set for all outstanding R2Ts) before sending 4852 the response PDU. A task management command (such as an 4853 abort task) from the initiator during this wait may 4854 also conclude the task. 4855 - No further action is necessary for targets if the discarded 4856 PDU is a non-data PDU. In case of immediate data being 4857 present on a discarded command, the immediate data is 4858 implicitly recovered when the task is retried (see Section 4859 7.2.1) followed by the entire data transfer for the task. 4861 When an initiator receives any iSCSI PDU with a payload digest 4862 error, it MUST discard the PDU. 4864 - If the discarded PDU is an iSCSI data PDU, the initiator 4865 MUST do one of the following: 4867 a) Request the desired data PDU through SNACK. In 4868 response to the SNACK, the target MUST either resend 4869 the data PDU or reject the SNACK with a Reject PDU 4870 with a reason code of "SNACK reject" in which case: 4871 b) If the status has not already been sent for the 4872 command, the target MUST terminate the command with a 4873 CHECK CONDITION Status and an iSCSI Condition of 4874 "SNACK rejected" (Section 11.4.7.2). 4875 c) If the status was already sent, no further action is 4876 necessary for the target. The initiator in this case 4877 MUST wait for the status to be received and then 4878 discard it, so as to internally signal the completion 4879 with CHECK CONDITION Status and an iSCSI Condition of 4880 "protocol service CRC error" (Section 11.4.7.2). 4881 d) Abort the task and terminate the command with an 4882 error. 4884 - If the discarded PDU is a response PDU or an unsolicited PDU 4885 (e.g. Async, Reject), the initiator MUST do one of the 4886 following: 4888 a) Request PDU retransmission with a status SNACK. 4889 b) Logout the connection for recovery and continue the 4890 tasks on a different connection instance as described 4891 in Section 7.2. 4893 c) Logout to close the connection (abort all the 4894 commands associated with the connection). 4896 Note that an unsolicited PDU carries the next StatSN value on 4897 an iSCSI connection, thereby advancing the StatSN. When an 4898 initiator discards one of these PDUs due to a payload digest 4899 error, the entire PDU including the header MUST be discarded. 4900 Consequently, the initiator MUST treat the exception like a 4901 loss of any other solicited response PDU. 4903 7.9. Sequence Errors 4905 When an initiator receives an iSCSI R2T/data PDU with an out of 4906 order R2TSN/DataSN or a SCSI response PDU with an ExpDataSN that 4907 implies missing data PDU(s), it means that the initiator must have 4908 detected a header or payload digest error on one or more earlier 4909 R2T/data PDUs. The initiator MUST address these implied digest 4910 errors as described in Section 7.8. When a target receives a data 4911 PDU with an out of order DataSN, it means that the target must 4912 have hit a header or payload digest error on at least one of the 4913 earlier data PDUs. The target MUST address these implied digest 4914 errors as described in Section 7.8. 4916 When an initiator receives an iSCSI status PDU with an out of 4917 order StatSN that implies missing responses, it MUST address the 4918 one or more missing status PDUs as described in Section 7.8. As a 4919 side effect of receiving the missing responses, the initiator may 4920 discover missing data PDUs. If the initiator wants to recover the 4921 missing data for a command, it MUST NOT acknowledge the received 4922 responses that start from the StatSN of the relevant command, 4923 until it has completed receiving all the data PDUs of the command. 4925 When an initiator receives duplicate R2TSNs (due to proactive 4926 retransmission of R2Ts by the target) or duplicate DataSNs (due to 4927 proactive SNACKs by the initiator), it MUST discard the 4928 duplicates. 4930 7.10. Message Error Checking 4932 In the iSCSI implementations till date, there has been some 4933 uncertainty on the extent to which incoming messages have to be 4934 checked for protocol errors, beyond what is strictly required for 4935 processing the inbound message. This Section addresses this 4936 question. 4938 Unless this document requires it, an iSCSI implementation is not 4939 required to do an exhaustive protocol conformance check on an 4940 incoming iSCSI PDU. The iSCSI implementation especially is not 4941 required to double-check the remote iSCSI implementation's 4942 conformance to protocol requirements. 4944 7.11. SCSI Timeouts 4946 An iSCSI initiator MAY attempt to plug a command sequence gap on 4947 the target end (in the absence of an acknowledgement of the 4948 command by way of ExpCmdSN) before the ULP timeout by retrying the 4949 unacknowledged command, as described in Section 7.2. 4951 On a ULP timeout for a command (that carried a CmdSN of n), if the 4952 iSCSI initiator intends to continue the session it MUST abort the 4953 command by either using an appropriate Task Management function 4954 request for the specific command, or a "close the connection" 4955 Logout. When using an ABORT TASK, if the ExpCmdSN is still less 4956 than (n+1), the target may see the abort request while missing the 4957 original command itself due to one of the following reasons: 4959 - Original command was dropped due to digest error. 4961 - Connection on which the original command was sent was 4962 successfully logged out. On logout, the unacknowledged 4963 commands issued on the connection being logged out are 4964 discarded. 4966 If the abort request is received and the original command is 4967 missing, targets MUST consider the original command with that 4968 RefCmdSN to be received and issue a Task Management response with 4969 the response code: "Function Complete". This response concludes 4970 the task on both ends. If the abort request is received and the 4971 target can determine (based on the Referenced Task Tag) that the 4972 command was received and executed and also that the response was 4973 sent prior to the abort, then the target MUST respond with the 4974 response code of "Task Does Not Exist". 4976 7.12. Negotiation Failures 4978 Text request and response sequences, when used to set/negotiate 4979 operational parameters, constitute the negotiation/parameter 4980 setting. A negotiation failure is considered to be one or more of 4981 the following: 4983 - None of the choices, or the stated value, is acceptable to 4984 one of the sides in the negotiation. 4986 - The text request timed out and possibly terminated. 4988 - The text request was answered with a Reject PDU. 4990 The following two rules should be used to address negotiation 4991 failures: 4993 a) During Login, any failure in negotiation MUST be 4994 considered a login process failure and the Login Phase 4995 MUST be terminated, and with it, the connection. If the 4996 target detects the failure, it must terminate the login 4997 with the appropriate login response code. 4999 b) A failure in negotiation, while in the Full Feature 5000 Phase, will terminate the entire negotiation sequence 5001 that may consist of a series of text requests that use 5002 the same Initiator Task Tag. The operational parameters 5003 of the session or the connection MUST continue to be the 5004 values agreed upon during an earlier successful 5005 negotiation (i.e., any partial results of this 5006 unsuccessful negotiation MUST NOT take effect and MUST be 5007 discarded). 5009 7.13. Protocol Errors 5011 Mapping framed messages over a "stream" connection, such as TCP, 5012 makes the proposed mechanisms vulnerable to simple software 5013 framing errors. On the other hand, the introduction of framing 5014 mechanisms to limit the effects of these errors may be onerous on 5015 performance for simple implementations. Command Sequence Numbers 5016 and the above mechanisms for connection drop and reestablishment 5017 help handle this type of mapping errors. 5019 All violations of iSCSI PDU exchange sequences specified in this 5020 draft are also protocol errors. This category of errors can only 5021 be 5022 addressed by fixing the implementations; iSCSI defines Reject and 5023 response codes to enable this. 5025 7.14. Connection Failures 5027 iSCSI can keep a session in operation if it is able to 5028 keep/establish at least one TCP connection between the initiator 5029 and the target in a timely fashion. Targets and/or initiators may 5030 recognize a failing connection by either transport level means 5031 (TCP), a gap in the command sequence number, a response stream 5032 that is not filled for a long time, or by a failing iSCSI NOP 5033 (acting as a ping). The latter MAY be used periodically to 5034 increase the speed and likelihood of detecting connection 5035 failures. As an example for transport level means, initiators and 5036 targets MAY also use the keep-alive option, see [RFC1122], on the 5037 TCP connection to enable early link failure detection on otherwise 5038 idle links. 5040 On connection failure, the initiator and target MUST do one of the 5041 following: 5043 a) Attempt connection recovery within the session 5044 (Connection Recovery). 5046 b) Logout the connection with the reason code "closes the 5047 connection" (Section 10.14.5), re-issue missing commands, 5048 and implicitly terminate all active commands. This option 5049 requires support for the within-connection recovery class 5050 (Recovery Within-connection). 5052 c) Perform session recovery (Session Recovery). 5054 Either side may choose to escalate to session recovery (via the 5055 initiator dropping all the connections, or via an Async Message 5056 that announces the similar intent from a target), and the other 5057 side MUST give it precedence. On a connection failure, a target 5058 MUST terminate and/or discard all of the active immediate commands 5059 regardless of which of the above options is used (i.e., immediate 5060 commands are not recoverable across connection failures). 5062 7.15. Session Errors 5064 If all of the connections of a session fail and cannot be 5065 reestablished in a short time, or if initiators detect protocol 5066 errors repeatedly, an initiator may choose to terminate a session 5067 and establish a new session. 5069 In this case, the initiator takes the following actions: 5071 - Resets or closes all the transport connections. 5073 - Terminates all outstanding requests with an appropriate 5074 response before initiating a new session. If the same I_T 5075 nexus is intended to be reestablished, the initiator MUST 5076 employ session reinstatement (see Section 6.3.5). 5078 When the session timeout (the connection state timeout for the 5079 last failed connection) happens on the target, it takes the 5080 following actions: 5082 - Resets or closes the TCP connections (closes the session). 5084 - Terminates all active tasks that were allegiant to the 5085 connection(s) that constituted the session. 5087 A target MUST also be prepared to handle a session reinstatement 5088 request from the initiator that may be addressing session errors. 5090 8. State Transitions 5092 iSCSI connections and iSCSI sessions go through several well- 5093 defined states from the time they are created to the time they are 5094 cleared. 5096 The connection state transitions are described in two separate but 5097 dependent state diagrams for ease in understanding. The first 5098 diagram, "standard connection state diagram", describes the 5099 connection state transitions when the iSCSI connection is not 5100 waiting for, or undergoing, a cleanup by way of an explicit or 5101 implicit Logout. The second diagram, "connection cleanup state 5102 diagram", describes the connection state transitions while 5103 performing the iSCSI connection cleanup. 5105 The "session state diagram" describes the state transitions an 5106 iSCSI session would go through during its lifetime, and it depends 5107 on the states of possibly multiple iSCSI connections that 5108 participate in the session. 5110 States and transitions are described in text, tables and diagrams. 5111 The diagrams are used for illustration. The text and the tables 5112 are the governing specification. 5114 8.1. Standard Connection State Diagrams 5116 8.1.1. State Descriptions for Initiators and Targets 5118 State descriptions for the standard connection state diagram are 5119 as follows: 5120 -S1: FREE 5121 -initiator: State on instantiation, or after successful 5122 connection closure. 5123 -target: State on instantiation, or after successful 5124 connection closure. 5125 -S2: XPT_WAIT 5126 -initiator: Waiting for a response to its transport 5127 connection establishment request. 5128 -target: Illegal 5129 -S3: XPT_UP 5130 -initiator: Illegal 5131 -target: Waiting for the Login process to commence. 5133 -S4: IN_LOGIN 5134 -initiator: Waiting for the Login process to conclude, 5135 possibly involving several PDU exchanges. 5136 -target: Waiting for the Login process to conclude, 5137 possibly involving several PDU exchanges. 5138 -S5: LOGGED_IN 5139 -initiator: In Full Feature Phase, waiting for all 5140 internal, iSCSI, and transport events. 5141 -target: In Full Feature Phase, waiting for all internal, 5142 iSCSI, and transport events. 5143 -S6: IN_LOGOUT 5144 -initiator: Waiting for a Logout response. 5145 -target: Waiting for an internal event signaling completion 5146 of logout processing. 5147 -S7: LOGOUT_REQUESTED 5148 -initiator: Waiting for an internal event signaling 5149 readiness to proceed with Logout. 5150 -target: Waiting for the Logout process to start after 5151 having requested a Logout via an Async Message. 5152 -S8: CLEANUP_WAIT 5153 -initiator: Waiting for the context and/or resources to 5154 initiate the cleanup processing for this CSM. 5155 -target: Waiting for the cleanup process to start for this 5156 CSM. 5157 8.1.2. State Transition Descriptions for Initiators and Targets 5159 -T1: 5160 -initiator: Transport connect request was made (e.g., TCP 5161 SYN sent). 5162 -target: Illegal 5163 -T2: 5164 -initiator: Transport connection request timed out, a 5165 transport reset was received, or an internal event of 5166 receiving a Logout response (success) on another connection 5167 for a "close the session" Logout request was received. 5168 -target:Illegal 5169 -T3: 5170 -initiator: Illegal 5171 -target: Received a valid transport connection request that 5172 establishes the transport connection. 5173 -T4: 5175 -initiator: Transport connection established, thus 5176 prompting the initiator to start the iSCSI Login. 5177 -target: Initial iSCSI Login request was received. 5178 -T5: 5179 -initiator: The final iSCSI Login response with a Status- 5180 Class of zero was received. 5181 -target: The final iSCSI Login request to conclude the 5182 Login Phase was received, thus prompting the target to send 5183 the final iSCSI Login response with a Status-Class of zero. 5184 -T6: 5185 -initiator: Illegal 5186 -target: Timed out waiting for an iSCSI Login, transport 5187 disconnect indication was received, transport reset was 5188 received, or an internal event indicating a transport 5189 timeout was received. In all these cases, the connection is 5190 to be closed. 5191 -T7: 5192 -initiator - one of the following events caused the 5193 transition: 5194 a) The final iSCSI Login response was received with a 5195 non-zero Status-Class. 5196 b) Login timed out. 5197 c) A transport disconnect indication was received. 5198 d) A transport reset was received. 5199 e) An internal event indicating a transport timeout was 5200 received. 5201 f) An internal event of receiving a Logout response 5202 (success) on another connection for a "close the 5203 session" Logout request was received. 5205 In all these cases, the transport connection is closed. 5207 -target - one of the following events caused the 5208 transition: 5209 a) The final iSCSI Login request to conclude the Login 5210 Phase was received, prompting the target to send the 5211 final iSCSI Login response with a non-zero Status- 5212 Class. 5213 b) Login timed out. 5214 c) Transport disconnect indication was received. 5216 d) Transport reset was received. 5217 e) An internal event indicating a transport timeout was 5218 received. 5219 f) On another connection, a "close the session" Logout 5220 request was received. 5222 In all these cases, the connection is to be closed. 5223 -T8: 5224 -initiator: An internal event of receiving a Logout 5225 response (success) on another connection for a "close the 5226 session" Logout request was received, thus closing this 5227 connection requiring no further cleanup. 5228 -target: An internal event of sending a Logout response 5229 (success) on another connection for a "close the session" 5230 Logout request was received, or an internal event of a 5231 successful connection/session reinstatement is received, 5232 thus prompting the target to close this connection cleanly. 5233 -T9, T10: 5234 -initiator: An internal event that indicates the readiness 5235 to start the Logout process was received, thus prompting an 5236 iSCSI Logout to be sent by the initiator. 5237 -target: An iSCSI Logout request was received. 5238 -T11, T12: 5239 -initiator: Async PDU with AsyncEvent "Request Logout" was 5240 received. 5241 -target: An internal event that requires the 5242 decommissioning of the connection is received, thus causing 5243 an Async PDU with an AsyncEvent "Request Logout" to be 5244 sent. 5245 -T13: 5246 -initiator: An iSCSI Logout response (success) was 5247 received, or an internal event of receiving a Logout 5248 response (success) on another connection for a "close the 5249 session" Logout request was received. 5250 -target: An internal event was received that indicates 5251 successful processing of the Logout, which prompts an iSCSI 5252 Logout response (success) to be sent; an internal event of 5253 sending a Logout response (success) on another connection 5254 for a "close the session" Logout request was received; or 5255 an internal event of a successful connection/session 5256 reinstatement is received. In all these cases, the 5257 transport connection is closed. 5259 -T14: 5260 -initiator: Async PDU with AsyncEvent "Request Logout" was 5261 received again. 5262 -target: Illegal 5263 -T15, T16: 5264 -initiator: One or more of the following events caused this 5265 transition: 5266 a) Internal event that indicates a transport connection 5267 timeout was received thus prompting transport RESET 5268 or transport connection closure. 5269 b) A transport RESET. 5270 c) A transport disconnect indication. 5271 d) Async PDU with AsyncEvent "Drop connection" (for 5272 this CID). 5273 e) Async PDU with AsyncEvent "Drop all connections". 5274 -target: One or more of the following events caused this 5275 transition: 5276 a) Internal event that indicates a transport connection 5277 timeout was received, thus prompting transport RESET 5278 or transport connection closure. 5279 b) An internal event of a failed connection/session 5280 reinstatement is received. 5281 c) A transport RESET. 5282 d) A transport disconnect indication. 5283 e) Internal emergency cleanup event was received which 5284 prompts an Async PDU with AsyncEvent "Drop 5285 connection" (for this CID), or event "Drop all 5286 connections". 5288 -T17: 5289 -initiator: One or more of the following events caused this 5290 transition: 5291 a) Logout response, (failure i.e., a non-zero status) 5292 was received, or Logout timed out. 5293 b) Any of the events specified for T15 and T16. 5294 -target: One or more of the following events caused this 5295 transition: 5297 a) Internal event that indicates a failure of the 5298 Logout processing was received, which prompts a 5299 Logout response (failure, i.e., a non-zero status) 5300 to be sent. 5301 b) Any of the events specified for T15 and T16. 5302 -T18: 5303 -initiator: An internal event of receiving a Logout 5304 response (success) on another connection for a "close the 5305 session" Logout request was received. 5307 -target: An internal event of sending a Logout response 5308 (success) on another connection for a "close the session" 5309 Logout request was received, or an internal event of a 5310 successful connection/session reinstatement is received. 5311 In both these cases, the connection is closed. 5313 The CLEANUP_WAIT state (S8) implies that there are possible iSCSI 5314 tasks that have not reached conclusion and are still considered 5315 busy. 5317 8.1.3. Standard Connection State Diagram for an Initiator 5319 Symbolic names for States: 5321 S1: FREE 5323 S2: XPT_WAIT 5325 S4: IN_LOGIN 5327 S5: LOGGED_IN 5329 S6: IN_LOGOUT 5331 S7: LOGOUT_REQUESTED 5333 S8: CLEANUP_WAIT 5335 States S5, S6, and S7 constitute the Full Feature Phase operation 5336 of the connection. 5338 The state diagram is as follows: 5340 -------<-------------+ 5341 +--------->/ S1 \<----+ | 5342 T13| +->\ /<-+ \ | 5343 | / ---+--- \ \ | 5344 | / | T2 \ | | 5345 | T8 | |T1 | | | 5346 | | | / |T7 | 5347 | | | / | | 5348 | | | / | | 5349 | | V / / | 5350 | | ------- / / | 5351 | | / S2 \ / | 5352 | | \ / / | 5353 | | ---+--- / | 5354 | | |T4 / | 5355 | | V / | T18 5356 | | ------- / | 5357 | | / S4 \ | 5358 | | \ / | 5359 | | ---+--- | T15 5360 | | |T5 +--------+---------+ 5361 | | | /T16+-----+------+ | 5362 | | | / -+-----+--+ | | 5363 | | | / / S7 \ |T12| | 5364 | | | / +->\ /<-+ V V 5365 | | | / / -+----- ------- 5366 | | | / /T11 |T10 / S8 \ 5367 | | V / / V +----+ \ / 5368 | | ---+-+- ----+-- | ------- 5369 | | / S5 \T9 / S6 \<+ ^ 5370 | +-----\ /--->\ / T14 | 5371 | ------- --+----+------+T17 5372 +---------------------------+ 5374 The following state transition table represents the above diagram. 5375 Each row represents the starting state for a given transition, 5376 which after taking a transition marked in a table cell would end 5377 in the state represented by the column of the cell. For example, 5378 from state S1, the connection takes the T1 transition to arrive at 5379 state S2. The fields marked "-" correspond to undefined 5380 transitions. 5382 +----+---+---+---+---+----+---+ 5383 |S1 |S2 |S4 |S5 |S6 |S7 |S8 | 5384 ---+----+---+---+---+---+----+---+ 5385 S1| - |T1 | - | - | - | - | - | 5386 ---+----+---+---+---+---+----+---+ 5387 S2|T2 |- |T4 | - | - | - | - | 5388 ---+----+---+---+---+---+----+---+ 5389 S4|T7 |- |- |T5 | - | - | - | 5390 ---+----+---+---+---+---+----+---+ 5391 S5|T8 |- |- | - |T9 |T11 |T15| 5392 ---+----+---+---+---+---+----+---+ 5393 S6|T13 |- |- | - |T14|- |T17| 5394 ---+----+---+---+---+---+----+---+ 5395 S7|T18 |- |- | - |T10|T12 |T16| 5396 ---+----+---+---+---+---+----+---+ 5397 S8| - |- |- | - | - | - | - | 5398 ---+----+---+---+---+---+----+---+ 5400 8.1.4. Standard Connection State Diagram for a Target 5402 Symbolic names for States: 5403 S1: FREE 5405 S3: XPT_UP 5407 S4: IN_LOGIN 5409 S5: LOGGED_IN 5411 S6: IN_LOGOUT 5413 S7: LOGOUT_REQUESTED 5415 S8: CLEANUP_WAIT 5417 States S5, S6, and S7 constitute the Full Feature Phase operation 5418 of the connection. 5420 The state diagram is as follows: 5422 -------<-------------+ 5423 +--------->/ S1 \<----+ | 5424 T13| +->\ /<-+ \ | 5425 | / ---+--- \ \ | 5426 | / | T6 \ | | 5427 | T8 | |T3 | | | 5428 | | | / |T7 | 5429 | | | / | | 5430 | | | / | | 5431 | | V / / | 5432 | | ------- / / | 5433 | | / S3 \ / | 5434 | | \ / / | T18 5435 | | ---+--- / | 5436 | | |T4 / | 5437 | | V / | 5438 | | ------- / | 5439 | | / S4 \ | 5440 | | \ / | 5441 | | ---+--- T15 | 5442 | | |T5 +--------+---------+ 5443 | | | /T16+-----+------+ | 5444 | | | / -+-----+---+ | | 5445 | | | / / S7 \ |T12| | 5446 | | | / +->\ /<-+ V V 5447 | | | / / -+----- ------- 5448 | | | / /T11 |T10 / S8 \ 5449 | | V / / V \ / 5450 | | ---+-+- ------- ------- 5451 | | / S5 \T9 / S6 \ ^ 5452 | +-----\ /--->\ / | 5453 | ------- --+----+--------+T17 5454 +---------------------------+ 5456 The following state transition table represents the above diagram, 5457 and follows the conventions described for the initiator diagram. 5459 +----+---+---+---+---+----+---+ 5460 |S1 |S3 |S4 |S5 |S6 |S7 |S8 | 5461 ---+----+---+---+---+---+----+---+ 5462 S1| - |T3 | - | - | - | - | - | 5463 ---+----+---+---+---+---+----+---+ 5464 S3|T6 |- |T4 | - | - | - | - | 5465 ---+----+---+---+---+---+----+---+ 5466 S4|T7 |- |- |T5 | - | - | - | 5467 ---+----+---+---+---+---+----+---+ 5468 S5|T8 |- |- | - |T9 |T11 |T15| 5469 ---+----+---+---+---+---+----+---+ 5470 S6|T13 |- |- | - |- |- |T17| 5471 ---+----+---+---+---+---+----+---+ 5472 S7|T18 |- |- | - |T10|T12 |T16| 5473 ---+----+---+---+---+---+----+---+ 5474 S8| - |- |- | - | - | - | - | 5475 ---+----+---+---+---+---+----+---+ 5477 8.2. Connection Cleanup State Diagram for Initiators and Targets 5479 Symbolic names for states: 5481 R1: CLEANUP_WAIT (same as S8) 5483 R2: IN_CLEANUP 5485 R3: FREE (same as S1) 5487 Whenever a connection state machine in cleanup (let's call it CSM- 5488 C) enters the CLEANUP_WAIT state (S8), it must go through the 5489 state transitions described in the connection cleanup state 5490 diagram either a) using a separate full-feature phase connection 5491 (let's call it CSM-E, for explicit) in the LOGGED_IN state in the 5492 same session, or b) using a new transport connection (let's call 5493 it CSM-I, for implicit) in the FREE state that is to be added to 5494 the same session. In the CSM-E case, an explicit logout for the 5495 CID that corresponds to CSM-C (either as a connection or session 5496 logout) needs to be performed to complete the cleanup. In the CSM- 5497 I case, an implicit logout for the CID that corresponds to CSM-C 5498 needs to be performed by way of connection reinstatement (Section 5499 6.3.4) for that CID. In either case, the protocol exchanges on 5500 CSM-E or CSM-I determine the state transitions for CSM-C. 5501 Therefore, this cleanup state diagram is only applicable to the 5502 instance of the connection in cleanup (i.e., CSM-C). In the case 5503 of an implicit logout for example, CSM-C reaches FREE (R3) at the 5504 time CSM-I reaches LOGGED_IN. In the case of an explicit logout, 5505 CSM-C reaches FREE (R3) when CSM-E receives a successful logout 5506 response while continuing to be in the LOGGED_IN state. 5508 An initiator must initiate an explicit or implicit connection 5509 logout for a connection in the CLEANUP_WAIT state, if the 5510 initiator intends to continue using the associated iSCSI session. 5512 The following state diagram applies to both initiators and 5513 targets. 5515 ------- 5516 / R1 \ 5517 +--\ /<-+ 5518 / ---+--- \ 5519 / | \ M3 5520 M1 | |M2 | 5521 | | / 5522 | | / 5523 | | / 5524 | V / 5525 | ------- / 5526 | / R2 \ 5527 | \ / 5528 | ------- 5529 | | 5530 | |M4 5531 | | 5532 | | 5533 | | 5534 | V 5535 | ------- 5536 | / R3 \ 5537 +---->\ / 5538 ------- 5540 The following state transition table represents the above diagram, 5541 and follows the same conventions as in earlier sections. 5543 +----+----+----+ 5544 |R1 |R2 |R3 | 5545 -----+----+----+----+ 5546 R1 | - |M2 |M1 | 5547 -----+----+----+----+ 5548 R2 |M3 | - |M4 | 5549 -----+----+----+----+ 5550 R3 | - | - | - | 5551 -----+----+----+----+ 5553 8.2.1. State Descriptions for Initiators and Targets 5555 -R1: CLEANUP_WAIT (Same as S8) 5556 -initiator: Waiting for the internal event to initiate the 5557 cleanup processing for CSM-C. 5558 -target: Waiting for the cleanup process to start for CSM- 5559 C. 5560 -R2: IN_CLEANUP 5561 -initiator: Waiting for the connection cleanup process to 5562 conclude for CSM-C. 5563 -target: Waiting for the connection cleanup process to 5564 conclude for CSM-C. 5565 -R3: FREE (Same as S1) 5566 -initiator: End state for CSM-C. 5567 -target: End state for CSM-C. 5569 8.2.2. State Transition Descriptions for Initiators and Targets 5571 -M1: One or more of the following events was received: 5572 -initiator: 5573 -An internal event that indicates connection state 5574 timeout. 5575 -An internal event of receiving a successful Logout 5576 response on a different connection for a "close the 5577 session" Logout. 5578 -target: 5579 -An internal event that indicates connection state 5580 timeout. 5581 -An internal event of sending a Logout response 5582 (success) on a different connection for a "close the 5583 session" Logout request. 5585 -M2: An implicit/explicit logout process was initiated by the 5586 initiator. 5587 -In CSM-I usage: 5588 -initiator: An internal event requesting the connection 5589 (or session) reinstatement was received, thus prompting 5590 a connection (or session) reinstatement Login to be 5591 sent transitioning CSM-I to state IN_LOGIN. 5592 -target: A connection/session reinstatement Login was 5593 received while in state XPT_UP. 5594 -In CSM-E usage: 5596 -initiator: An internal event that indicates that an 5597 explicit logout was sent for this CID in state 5598 LOGGED_IN. 5599 -target: An explicit logout was received for this CID 5600 in state LOGGED_IN. 5601 -M3: Logout failure detected 5602 -In CSM-I usage: 5603 -initiator: CSM-I failed to reach LOGGED_IN and arrived 5604 into FREE instead. 5605 -target: CSM-I failed to reach LOGGED_IN and arrived 5606 into FREE instead. 5607 -In CSM-E usage: 5608 -initiator: CSM-E either moved out of LOGGED_IN, or 5609 Logout timed out and/or aborted, or Logout response 5610 (failure) was received. 5611 -target: CSM-E either moved out of LOGGED_IN, Logout 5612 timed out and/or aborted, or an internal event that 5613 indicates a failed Logout processing was received. A 5614 Logout response (failure) was sent in the last case. 5616 -M4: Successful implicit/explicit logout was performed. 5617 - In CSM-I usage: 5618 -initiator: CSM-I reached state LOGGED_IN, or an 5619 internal event of receiving a Logout response (success) 5620 on another connection for a "close the session" Logout 5621 request was received. 5622 -target: CSM-I reached state LOGGED_IN, or an internal 5623 event of sending a Logout response (success) on a 5624 different connection for a "close the session" Logout 5625 request was received. 5626 - In CSM-E usage: 5627 -initiator: CSM-E stayed in LOGGED_IN and received a 5628 Logout response (success), or an internal event of 5629 receiving a Logout response (success) on another 5630 connection for a "close the session" Logout request was 5631 received. 5632 -target: CSM-E stayed in LOGGED_IN and an internal 5633 event indicating a successful Logout processing was 5634 received, or an internal event of sending a Logout 5635 response (success) on a different connection for a 5636 "close the session" Logout request was received. 5638 8.3. Session State Diagrams 5640 8.3.1. Session State Diagram for an Initiator 5642 Symbolic Names for States: 5644 Q1: FREE 5646 Q3: LOGGED_IN 5648 Q4: FAILED 5650 State Q3 represents the Full Feature Phase operation of the 5651 session. 5653 The state diagram is as follows: 5655 ------- 5656 / Q1 \ 5657 +------>\ /<-+ 5658 / ---+--- | 5659 / | |N3 5660 N6 | |N1 | 5661 | | | 5662 | N4 | | 5663 | +----------+ | / 5664 | | | | / 5665 | | | | / 5666 | | V V / 5667 -+--+-- -----+- 5668 / Q4 \ N5 / Q3 \ 5669 \ /<------\ / 5670 ------- ------- 5672 The state transition table is as follows: 5674 +---+---+---+ 5675 |Q1 |Q3 |Q4 | 5676 -----+---+---+---+ 5677 Q1 | - |N1 | - | 5678 -----+---+---+---+ 5679 Q3 |N3 | - |N5 | 5680 -----+---+---+---+ 5681 Q4 |N6 |N4 | - | 5682 -----+---+---+---+ 5684 8.3.2. Session State Diagram for a Target 5686 Symbolic Names for States: 5688 Q1: FREE 5690 Q2: ACTIVE 5692 Q3: LOGGED_IN 5694 Q4: FAILED 5696 Q5: IN_CONTINUE 5698 State Q3 represents the Full Feature Phase operation of the 5699 session. 5701 The state diagram is as follows: 5703 ------- 5704 +------------------>/ Q1 \ 5705 / +-------------->\ /<-+ 5706 | | ---+--- | 5707 | | ^ | |N3 5708 N 6 | |N11 N9| V N1 | 5709 | | +------ | 5710 | | / Q2 \ | 5711 | | \ / | 5712 | --+---- +--+--- | 5713 | / Q5 \ | | 5714 | \ / N10 | | 5715 | +-+---+------------+ | N2 / 5716 | ^ | | | / 5717 | N7| |N8 | | / 5718 | | | | V / 5719 -+---+-V V------+- 5720 / Q4 \ N5 / Q3 \ 5721 \ /<-------------\ / 5722 ------- ------- 5724 The state transition table is as follows: 5726 +----+----+----+----+----+ 5727 |Q1 |Q2 |Q3 |Q4 |Q5 | 5728 -----+----+----+----+----+----+ 5729 Q1 | - |N1 | - | - | - | 5730 -----+----+----+----+----+----+ 5731 Q2 |N9 | - |N2 | - | - | 5732 -----+----+----+----+----+----+ 5733 Q3 |N3 | - | - |N5 | - | 5734 -----+----+----+----+----+----+ 5735 Q4 |N6 | - | - | - |N7 | 5736 -----+----+----+----+----+----+ 5737 Q5 |N11 | - |N10 |N8 | - | 5738 -----+----+----+----+----+----+ 5740 8.3.3. State Descriptions for Initiators and Targets 5742 -Q1: FREE 5743 -initiator: State on instantiation or after cleanup. 5745 -target: State on instantiation or after cleanup. 5746 -Q2: ACTIVE 5747 -initiator: Illegal. 5748 -target: The first iSCSI connection in the session 5749 transitioned to IN_LOGIN, waiting for it to complete the 5750 login process. 5751 -Q3: LOGGED_IN 5752 -initiator: Waiting for all session events. 5753 -target: Waiting for all session events. 5754 -Q4: FAILED 5755 -initiator: Waiting for session recovery or session 5756 continuation. 5757 -target: Waiting for session recovery or session 5758 continuation. 5759 -Q5: IN_CONTINUE 5760 -initiator: Illegal. 5761 -target: Waiting for session continuation attempt to reach 5762 a conclusion. 5764 8.3.4. State Transition Descriptions for Initiators and Targets 5766 -N1: 5767 -initiator: At least one transport connection reached the 5768 LOGGED_IN state. 5769 -target: The first iSCSI connection in the session had 5770 reached the IN_LOGIN state. 5771 -N2: 5772 -initiator: Illegal. 5773 -target: At least one iSCSI connection reached the 5774 LOGGED_IN state. 5775 -N3: 5776 -initiator: Graceful closing of the session via session 5777 closure (Section 6.3.6). 5778 -target: Graceful closing of the session via session 5779 closure (Section 6.3.6) or a successful session 5780 reinstatement cleanly closed the session. 5781 -N4: 5782 -initiator: A session continuation attempt succeeded. 5783 -target: Illegal. 5784 -N5: 5786 -initiator: Session failure (Section 6.3.6) occurred. 5787 -target: Session failure (Section 6.3.6) occurred. 5788 -N6: 5789 -initiator: Session state timeout occurred, or a session 5790 reinstatement cleared this session instance. This results 5791 in the freeing of all associated resources and the session 5792 state is discarded. 5793 -target: Session state timeout occurred, or a session 5794 reinstatement cleared this session instance. This results 5795 in the freeing of all associated resources and the session 5796 state is discarded. 5797 -N7: 5798 -initiator: Illegal. 5799 -target: A session continuation attempt is initiated. 5800 -N8: 5801 -initiator: Illegal. 5802 -target: The last session continuation attempt failed. 5803 -N9: 5804 -initiator: Illegal. 5805 -target: Login attempt on the leading connection failed. 5806 -N10: 5807 -initiator: Illegal. 5808 -target: A session continuation attempt succeeded. 5809 -N11: 5810 -initiator: Illegal. 5811 -target: A successful session reinstatement cleanly closed 5812 the session. 5814 9. Security Considerations 5816 Historically, native storage systems have not had to consider 5817 security because their environments offered minimal security 5818 risks. That is, these environments consisted of storage devices 5819 either directly attached to hosts or connected via a Storage Area 5820 Network (SAN) distinctly separate from the communications network. 5821 The use of storage protocols, such as SCSI, over IP-networks 5822 requires that security concerns be addressed. iSCSI 5823 implementations must provide means of protection against active 5824 attacks (e.g., pretending to be another identity, message 5825 insertion, deletion, modification, and replaying) and passive 5826 attacks (e.g.,eavesdropping, gaining advantage by analyzing the 5827 data sent over the line). 5829 Although technically possible, iSCSI SHOULD NOT be configured 5830 without security, specifically in-band authentication, see Section 5831 9.2. iSCSI configured without security should be confined to 5832 closed environments that have very limited and well controlled 5833 security risks. [RFC3723] specifies the mechanisms that must be 5834 used in order to mitigate risks fully described in that document. 5836 The following Section describes the security mechanisms provided 5837 by an iSCSI implementation. 5839 9.1. iSCSI Security Mechanisms 5841 The entities involved in iSCSI security are the initiator, target, 5842 and the IP communication end points. iSCSI scenarios in which 5843 multiple initiators or targets share a single communication end 5844 point are expected. To accommodate such scenarios, iSCSI uses two 5845 separate security mechanisms: In-band authentication between the 5846 initiator and the target at the iSCSI connection level (carried 5847 out by exchange of iSCSI Login PDUs), and packet protection 5848 (integrity, authentication, and confidentiality) by IPsec at the 5849 IP level. The two security mechanisms complement each other. The 5850 in-band authentication provides end-to-end trust (at login time) 5851 between the iSCSI initiator and the target while IPsec provides a 5852 secure channel between the IP communication end points. iSCSI can 5853 be used to access sensitive information for which significant 5854 security protection is appropriate. As further specified in the 5855 rest of this security considerations section, both iSCSI security 5856 mechanisms are mandatory to implement (MUST). Use of in-band 5857 authentication is strongly recommended (SHOULD). In contrast, use 5858 of IPsec is optional (MAY) as the security risks that it addresses 5859 may only be present over a subset of the networks used by an iSCSI 5860 connection or a session; a specific example is that when an iSCSI 5861 session spans data centers, IPsec VPN gateways at the data center 5862 boundaries to protect the WAN connectivity between data centers 5863 may be appropriate in combination with in-band iSCSI 5864 authentication. 5866 Further details on typical iSCSI scenarios and the relation 5867 between the initiators, targets, and the communication end points 5868 can be found in [RFC3723]. 5870 9.2. In-band Initiator-Target Authentication 5872 During login, the target MAY authenticate the initiator and the 5873 initiator MAY authenticate the target. The authentication is 5874 performed on every new iSCSI connection by an exchange of iSCSI 5875 Login PDUs using a negotiated authentication method. 5877 The authentication method cannot assume an underlying IPsec 5878 protection, because IPsec is optional to use. An attacker should 5879 gain as little advantage as possible by inspecting the 5880 authentication phase PDUs. Therefore, a method using clear text 5881 (or equivalent) passwords MUST NOT be used; on the other hand, 5882 identity protection is not strictly required. 5884 The authentication mechanism protects against an unauthorized 5885 login to storage resources by using a false identity (spoofing). 5886 Once the authentication phase is completed, if the underlying 5887 IPsec is not used, all PDUs are sent and received in clear. The 5888 authentication mechanism alone (without underlying IPsec) should 5889 only be used when there is no risk of eavesdropping, message 5890 insertion, deletion, modification, and replaying. 5892 Section 11 defines several authentication methods and the exact 5893 steps that must be followed in each of them, including the iSCSI- 5894 text-keys and their allowed values in each step. Whenever an iSCSI 5895 initiator gets a response whose keys, or their values, are not 5896 according to the step definition, it MUST abort the connection. 5898 Whenever an iSCSI target gets a response whose keys, or their 5899 values, are not according to the step definition, it MUST answer 5900 with a Login reject with the "Initiator Error" or "Missing 5901 Parameter" status. These statuses are not intended for 5902 cryptographically incorrect values such as the CHAP response, for 5903 which "Authentication Failure" status MUST be specified. The 5904 importance of this rule can be illustrated in CHAP with target 5905 authentication (see Section 12.1.3) where the initiator would have 5906 been able to conduct a reflection attack by omitting his response 5907 key (CHAP_R) using the same CHAP challenge as the target and 5908 reflecting the target's response back to the target. In CHAP, this 5909 is prevented because the target must answer the missing CHAP_R key 5910 with a Login reject with the "Missing Parameter" status. 5912 For some of the authentication methods, a key specifies the 5913 identity of the iSCSI initiator or target for authentication 5914 purposes. The value associated with that key MAY be different from 5915 the iSCSI name and SHOULD be configurable. (CHAP_N, see Section 5916 12.1.3 and SRP_U, see Section 12.1.2). 5918 9.2.1. CHAP Considerations 5920 Compliant iSCSI initiators and targets MUST implement the CHAP 5921 authentication method [RFC1994] (according to Section 12.1.3 5922 including the target authentication option). 5924 When CHAP is performed over a non-encrypted channel, it is 5925 vulnerable to an off-line dictionary attack. Implementations MUST 5926 support use of up to 128 bit random CHAP secrets, including the 5927 means to generate such secrets and to accept them from an external 5928 generation source. Implementations MUST NOT provide secret 5929 generation (or expansion) means other than random generation. 5931 An administrative entity of an environment in which CHAP is used 5932 with a secret that has less than 96 random bits MUST enforce IPsec 5933 encryption (according to the implementation requirements in 5934 Confidentiality) to protect the connection. Moreover, in this case 5935 IKE authentication with group pre-shared cryptographic keys SHOULD 5936 NOT be used unless it is not essential to protect group members 5937 against off-line dictionary attacks by other members. 5939 CHAP secrets MUST be an integral number of bytes (octets). A 5940 compliant implementation SHOULD NOT continue with the login step 5941 in which it should send a CHAP response (CHAP_R, Section 12.1.3) 5942 unless it can verify that the CHAP secret is at least 96 bits, or 5943 that IPsec encryption is being used to protect the connection. 5945 Any CHAP secret used for initiator authentication MUST NOT be 5946 configured for authentication of any target, and any CHAP secret 5947 used for target authentication MUST NOT be configured for 5948 authentication of any initiator. If the CHAP response received by 5949 one end of an iSCSI connection is the same as the CHAP response 5950 that the receiving endpoint would have generated for the same CHAP 5951 challenge, the response MUST be treated as an authentication 5952 failure and cause the connection to close (this ensures that the 5953 same CHAP secret is not used for authentication in both 5954 directions). Also, if an iSCSI implementation can function as 5955 both initiator and target, different CHAP secrets and identities 5956 MUST be configured for these two roles. The following is an 5957 example of the attacks prevented by the above requirements: 5959 a) Rogue wants to impersonate Storage to Alice, and knows 5960 that a single secret is used for both directions of 5961 Storage-Alice authentication. 5963 b) Rogue convinces Alice to open two connections to Rogue, 5964 and Rogue identifies itself as Storage on both 5965 connections. 5967 c) Rogue issues a CHAP challenge on connection 1, waits for 5968 Alice to respond, and then reflects Alice's challenge as 5969 the initial challenge to Alice on connection 2. 5971 d) If Alice doesn't check for the reflection across 5972 connections, Alice's response on connection 2 enables 5973 Rogue to impersonate Storage on connection 1, even though 5974 Rogue does not know the Alice-Storage CHAP secret. 5976 Originators MUST NOT reuse the CHAP challenge sent by the 5977 Responder for the other direction of a bidirectional 5978 authentication. Responders MUST check for this condition and close 5979 the iSCSI TCP connection if it occurs. 5981 The same CHAP secret SHOULD NOT be configured for authentication 5982 of multiple initiators or multiple targets, as this enables any of 5983 them to impersonate any other one of them, and compromising one of 5984 them enables the attacker to impersonate any of them. It is 5985 recommended that iSCSI implementations check for use of identical 5986 CHAP secrets by different peers when this check is feasible, and 5987 take appropriate measures to warn users and/or administrators when 5988 this is detected. 5990 When an iSCSI initiator or target authenticates itself to 5991 counterparts in multiple administrative domains, it SHOULD use a 5992 different CHAP secret for each administrative domain to avoid 5993 propagating security compromises across domains. 5995 Within a single administrative domain: 5996 - A single CHAP secret MAY be used for authentication of an 5997 initiator to multiple targets. 5999 - A single CHAP secret MAY be used for an authentication of a 6000 target to multiple initiators when the initiators use an 6001 external server (e.g., RADIUS, [RFC2865]) to verify the 6002 target's CHAP responses and do not know the target's CHAP 6003 secret. 6005 If an external response verification server (e.g., RADIUS) is not 6006 used, employing a single CHAP secret for authentication of a 6007 target to multiple initiators requires that all such initiators 6008 know that target secret. Any of these initiators can impersonate 6009 the target to any other such initiator, and compromise of such an 6010 initiator enables an attacker to impersonate the target to all 6011 such initiators. Targets SHOULD use separate CHAP secrets for 6012 authentication to each initiator when such risks are of concern; 6013 in this situation it may be useful to configure a separate logical 6014 iSCSI target with its own iSCSI Node Name for each initiator or 6015 group of initiators among which such separation is desired. 6017 The above requirements strengthen the security properties of CHAP 6018 authentication for iSCSI by comparison to the basic CHAP 6019 authentication mechanism [RFC1994]. It is very important to 6020 adhere to these requirements, especially the requirements for 6021 strong (large randomly generated) CHAP secrets, as iSCSI 6022 implementations and deployments that fail to use strong CHAP 6023 secrets are likely to be highly vulnerable to off-line dictionary 6024 attacks on CHAP secrets. 6026 Replacement of CHAP with a better authentication mechanism is 6027 anticipated in a future version of iSCSI. The FC-SP-2 standard 6028 [FC-SP-2] has specified the EAP-GPSK authentication mechanism 6029 [RFC5433] as an alternative to (and possible future replacement 6030 for) Fibre Channel's similar usage of strengthened CHAP. Another 6031 possible replacement for CHAP is a secure password mechanism, 6032 e.g., an updated version of iSCSI's current SRP authentication 6033 mechanism. 6035 9.2.2. SRP Considerations 6037 The strength of the SRP authentication method (specified in 6038 [RFC2945]) is dependent on the characteristics of the group being 6039 used (i.e., the prime modulus N and generator g). As described in 6040 [RFC2945], N is required to be a Sophie-German prime (of the form 6041 N = 2q + 1, where q is also prime) and the generator g is a 6042 primitive root of GF(n). In iSCSI authentication, the prime 6043 modulus N MUST be at least 768 bits. 6045 The list of allowed SRP groups is provided in [RFC3723]. 6047 9.3. IPsec 6049 iSCSI uses the IPsec mechanism for packet protection 6050 (cryptographic integrity, authentication, and confidentiality) at 6051 the IP level between the iSCSI communicating end points. The 6052 following sections describe the IPsec protocols that must be 6053 implemented for data integrity and authentication, 6054 confidentiality, and cryptographic key management. 6056 An iSCSI initiator or target may provide the required IPsec 6057 support fully integrated or in conjunction with an IPsec front-end 6058 device. In the latter case, the compliance requirements with 6060 regard to IPsec support apply to the "combined device". Only the 6061 "combined device" is to be considered an iSCSI device. 6063 Detailed considerations and recommendations for using IPsec for 6064 iSCSI are provided in [RFC3723]. 6066 This document updates RFC 3723 to add requirements for IPsec v3 6067 as specified in [RFC4301] and related RFCs. The IPsec v2 "MUST 6068 implement" requirements from [RFC3723] are left unchanged by this 6069 document; this document adds requirements that IPsec v3, as 6070 specified in [RFC4301] and related RFCs (e.g., IKEv2 [RFC5996]), 6071 SHOULD be implemented. The mandatory requirement for IPsec v2 6072 preserves interoperability with existing implementations, and the 6073 strong recommendation for IPsec v3 encourages implementers to move 6074 forward to that newer version of IPsec. 6076 9.3.1. Data Integrity and Authentication 6078 Data authentication and integrity is provided by a cryptographic 6079 keyed Message Authentication Code in every sent packet. This code 6080 protects against message insertion, deletion, and modification. 6081 Protection against message replay is realized by using a sequence 6082 counter. 6084 An iSCSI-compliant initiator or target MUST provide data integrity 6085 and authentication by implementing IPsec v2 [RFC2401] with ESPv2 6086 [RFC2406] in tunnel mode, SHOULD provide data integrity and 6087 authentication by implementing IPsec v3 [RFC4301] with ESPv3 6088 [RFC4303] in tunnel mode, and MAY provide data integrity and 6089 authentication by implementing either IPsec v2 or v3 with the 6090 appropriate version of ESP in transport mode. The IPsec 6091 implementation MUST fulfill the following iSCSI specific 6092 requirements: 6094 - HMAC-SHA1 MUST be implemented [RFC2404]. 6096 - AES CBC MAC with XCBC extensions SHOULD be implemented 6097 [RFC3566]. 6099 - Implementations that support IKEv2 [RFC5996] SHOULD also 6100 implement AES GMAC [RFC4543] 6102 The ESP anti-replay service MUST also be implemented. 6104 At the high speeds iSCSI is expected to operate, a single IPsec SA 6105 could rapidly cycle through the ESP 32-bit sequence number space. 6106 In view of this, an iSCSI implementation that is capable of 6107 operating at speeds of 1 Gbps and that implements both IKEv2 6108 [RFC5996] and ESPv3 [RFC4303] MUST also implement extended (64- 6109 bit) sequence numbers for ESPv3 and SHOULD use ESPv3 extended 6110 sequence numbers for all security associations that use ESPv3 to 6111 protect iSCSI connections. 6113 9.3.2. Confidentiality 6115 Confidentiality is provided by encrypting the data in every 6116 packet. When confidentiality is used it MUST be accompanied by 6117 data integrity and authentication to provide comprehensive 6118 protection against eavesdropping, message insertion, deletion, 6119 modification, and replaying. 6121 An iSCSI compliant initiator or target MUST provide 6122 confidentiality by implementing IPsec v2 [RFC2401] with ESPv2 6123 [RFC2406] in tunnel mode, SHOULD provide confidentiality by 6124 implementing IPsec v3 [RFC4301] with ESPv3 [RFC4303] in tunnel 6125 mode and MAY provide confidentiality by implementing either IPsec 6126 v2 or v3 with the appropriate version of ESP in transport mode, 6127 with the following iSCSI specific requirements that apply to IPsec 6128 v2 and IPsec v3: 6129 - 3DES in CBC mode MUST be implemented [RFC2451]. 6131 - AES in Counter mode SHOULD be implemented [RFC3686]. 6133 - Implementations that support IKEv2 [RFC5996] SHOULD also 6134 implement AES GCM [RFC4106] 6136 DES in CBC mode MUST NOT be used due to its inherent weakness. 6138 The NULL encryption algorithm MUST also be implemented. 6140 9.3.3. Policy, Security Associations, and Cryptographic Key 6141 Management 6143 A compliant iSCSI implementation MUST meet the cryptographic key 6144 management requirements of the IPsec protocol suite. 6145 Authentication, security association negotiation, and 6146 cryptographic key management MUST be provided by implementing IKE 6147 [RFC2409] using the IPsec DOI [RFC2407], and SHOULD be provided by 6148 implementing IKEv2 [RFC5996], with the following iSCSI-specific 6149 requirements: 6151 a) Peer authentication using a pre-shared cryptographic key MUST 6152 be supported. Certificate-based peer authentication using 6153 digital signatures MAY be supported. For IKEv1 ([RFC2409]), 6154 peer authentication using the public key encryption methods 6155 outlined in IKE sections 5.2 and 5.3 of [RFC2409] SHOULD NOT 6156 be used. 6157 b) When digital signatures are used to achieve authentication, 6158 an IKE negotiator SHOULD use IKE Certificate Request 6159 Payload(s) to specify the certificate authority. IKE 6160 negotiators SHOULD check the pertinent Certificate Revocation 6161 List (CRL) before accepting a PKI certificate for use in IKE 6162 authentication procedures. 6163 c) Conformant iSCSI implementations of IKEv1 MUST support Main 6164 Mode and SHOULD support Aggressive Mode. Main Mode with pre- 6165 shared key authentication method SHOULD NOT be used when 6166 either the initiator or the target uses dynamically assigned 6167 addresses. While in many cases pre-shared keys offer good 6168 security, situations in which dynamically assigned addresses 6169 are used force the use of a group pre-shared key, which 6170 creates vulnerability to a man-in-the-middle attack. 6171 d) In the IKEv1 Phase 2 Quick Mode, exchanges for creating the 6172 Phase 2 SA, the Identification Payload MUST be present. 6173 e) The following identification type requirements apply to 6174 IKEv1. ID_IPV4_ADDR, ID_IPV6_ADDR (if the protocol stack 6175 supports IPv6) and ID_FQDN Identification Types MUST be 6176 supported; ID_USER_FQDN SHOULD be supported. The IP Subnet, 6177 IP Address Range, ID_DER_ASN1_DN, and ID_DER_ASN1_GN 6178 Identification Types SHOULD NOT be used. The ID_KEY_ID 6179 Identification Type MUST NOT be used. 6180 f) If IKEv2 is supported, the following identification 6181 requirements apply. ID_IPV4_ADDR, ID_IPV6_ADDR (if the 6183 protocol stack supports IPv6) and ID_FQDN Identification 6184 Types MUST be supported; ID_RFC822_ADDR SHOULD be supported. 6185 The ID_DER_ASN1_DN, and ID_DER_ASN1_GN Identification Types 6186 SHOULD NOT be used. The ID_KEY_ID Identification Type MUST 6187 NOT be used. 6189 Manual cryptographic keying MUST NOT be used because it does not 6190 provide the necessary re-keying support. 6192 When DH groups are used, a DH group of at least 2048 bits SHOULD 6193 be offered as a part of all proposals to create IPsec Security 6194 Associations to protect iSCSI traffic. 6196 When IPsec is used, the receipt of an IKEv1 Phase 2 delete message 6197 or an IKEv2 INFORMATIONAL exchange that deletes the SA SHOULD NOT 6198 be interpreted as a reason for tearing down the iSCSI TCP 6199 connection. If additional traffic is sent on it, a new IKE SA will 6200 be created to protect it. 6202 The method used by the initiator to determine whether the target 6203 should be connected using IPsec is regarded as an issue of IPsec 6204 policy administration, and thus not defined in the iSCSI standard. 6206 The method used by an initiator that supports both IPsec v2 and v3 6207 to determine which versions of IPsec are supported by the target 6208 is also regarded as an issue of IPsec policy administration, and 6209 thus not defined in the iSCSI standard. If both IPsec v2 and v3 6210 are supported by both the initiator and target, use of IPsec v3 is 6211 recommended. 6213 If an iSCSI target is discovered via a SendTargets request in a 6214 discovery session not using IPsec, the initiator should assume 6215 that it does not need IPsec to establish a session to that target. 6216 If an iSCSI target is discovered using a discovery session that 6217 does use IPsec, the initiator SHOULD use IPsec when establishing a 6218 session to that target. 6220 9.4. Security Considerations for the X#NodeArchitecture Key 6222 The security considerations in this Section are specific to the 6223 X#NodeArchitecture discussed in Section 13.26. 6225 This extension key transmits specific implementation details about 6226 the node that sends it; such details may be considered sensitive 6227 in some environments. For example, if a certain software or 6228 firmware version is known to contain security weaknesses, 6229 announcing the presence of that version via this key may not be 6230 desirable. The countermeasures for this security concern are: 6232 a) sending less detailed information in the key values, 6233 b) not sending the extension key, or 6234 c) using IPsec ([RFC4303]) to provide confidentiality for the 6235 iSCSI connection on which the key is sent 6236 To support the first and second countermeasures, all 6237 implementations of this extension key MUST provide an 6238 administrative mechanism to disable sending the key. In addition, 6239 all implementations SHOULD provide an administrative mechanism to 6240 configure a verbosity level of the key value, thereby controlling 6241 the amount of information sent. 6243 For example, a lower verbosity might enable transmission of node 6244 architecture component names only, but no version numbers. The 6245 choice of which countermeasure is most appropriate depends on the 6246 environment. However, sending less detailed information in the key 6247 values may be an acceptable countermeasure in many environments, 6248 since it provides a compromise between sending too much 6249 information and the other more complete countermeasures of not 6250 sending the key at all or using IPsec. 6252 In addition to security considerations involving transmission of 6253 the key contents, any logging method(s) used for the key values 6254 MUST keep the information secure from intruders. For all 6255 implementations, the requirements to address this security concern 6256 are: 6258 a) Display of the log MUST only be possible with administrative 6259 rights to the node. 6260 b) Options to disable logging to disk and to keep logs for a 6261 fixed duration SHOULD be provided. 6263 Finally, it is important to note that different nodes may have 6264 different levels of risk, and these differences may affect the 6265 implementation. The components of risk include assets, threats, 6266 and vulnerabilities. Consider the following example iSCSI nodes, 6267 which demonstrate differences in assets and vulnerabilities of the 6268 nodes, and as a result, differences in implementation: 6270 a) One iSCSI target based on a special-purpose operating 6271 system: Since the iSCSI target controls access to the 6272 data storage containing company assets, the asset level 6273 is seen as very high. Also, because of the special- 6274 purpose operating system, in which vulnerabilities are 6275 less well-known, the vulnerability level is viewed as 6276 low. 6278 b) Multiple iSCSI initiators in a blade farm, each running a 6279 general purpose operating system: The asset level of each 6280 node is viewed as low, since blades are replaceable and 6281 low cost. However, the vulnerability level is viewed as 6282 high, since there may be many well-known vulnerabilities 6283 to that general-purpose operating system. For this 6284 target, an appropriate implementation might be logging of 6285 received key values, but no transmission of the key. For 6286 this initiator, an appropriate implementation might be 6287 transmission of the key, but no logging of received key 6288 values. 6290 9.5. SCSI Access Control Considerations 6292 iSCSI is a SCSI transport protocol and as such does not apply any 6293 access controls on SCSI-level operations such as SCSI task 6294 management functions (e.g. LU Reset, see Section 11.5.1). SCSI- 6295 level access controls (e.g. ACCESS CONTROL OUT, see [SPC3]) have 6296 to be appropriately deployed in practice to address SCSI-level 6297 security considerations, in addition to security at iSCSI 6298 connection and packet protection mechanisms that were already 6299 discussed in preceding Sections. 6301 10. Notes to Implementers 6303 This Section notes some of the performance and reliability 6304 considerations of the iSCSI protocol. This protocol was designed 6305 to allow efficient silicon and software implementations. The iSCSI 6306 task tag mechanism was designed to enable Direct Data Placement 6307 (DDP - a DMA form) at the iSCSI level or lower. 6309 The guiding assumption made throughout the design of this protocol 6310 is that targets are resource constrained relative to initiators. 6312 Implementers are also advised to consider the implementation 6313 consequences of the iSCSI to SCSI mapping model as outlined in 6314 Section 4.4.3. 6316 10.1. Multiple Network Adapters 6318 The iSCSI protocol allows multiple connections, not all of which 6319 need to go over the same network adapter. If multiple network 6320 connections are to be utilized with hardware support, the iSCSI 6321 protocol command-data-status allegiance to one TCP connection 6322 ensures that there is no need to replicate information across 6323 network adapters or otherwise require them to cooperate. 6325 However, some task management commands may require some loose form 6326 of cooperation or replication at least on the target. 6328 10.1.1. Conservative Reuse of ISIDs 6330 Historically, the SCSI model (and implementations and applications 6331 based on that model) has assumed that SCSI ports are static, 6332 physical entities. Recent extensions to the SCSI model have taken 6333 advantage of persistent worldwide unique names for these ports. In 6334 iSCSI however, the SCSI initiator ports are the endpoints of 6335 dynamically created sessions, so the presumptions of "static and 6336 physical" do not apply. In any case, the model clauses 6337 (particularly, Section 4.4.1) provide for persistent, reusable 6338 names for the iSCSI-type SCSI initiator ports even though there 6339 does not need to be any physical entity bound to these names. 6341 To both minimize the disruption of legacy applications and to 6342 better facilitate the SCSI features that rely on persistent names 6343 for SCSI ports, iSCSI implementations SHOULD attempt to provide a 6344 stable presentation of SCSI Initiator Ports (both to the upper OS- 6345 layers and to the targets to which they connect). This can be 6346 achieved in an initiator implementation by conservatively reusing 6347 ISIDs. In other words, the same ISID should be used in the Login 6348 process to multiple target portal groups (of the same iSCSI Target 6349 or different iSCSI Targets). The ISID RULE (Section 4.4.3) only 6350 prohibits reuse to the same target portal group. It does not 6351 "preclude" reuse to other target portal groups. 6352 The principle of conservative reuse "encourages" reuse to other 6353 target portal groups. When a SCSI target device sees the same 6354 (InitiatorName, ISID) pair in different sessions to different 6355 target portal groups, it can identify the underlying SCSI 6356 Initiator Port on each session as the same SCSI port. In effect, 6357 it can recognize multiple paths from the same source. 6359 10.1.2. iSCSI Name, ISID, and TPGT Use 6361 The designers of the iSCSI protocol are aware that legacy SCSI 6362 transports rely on initiator identity to assign access to storage 6363 resources. Although newer techniques are available and simplify 6364 access control, support for configuration and authentication 6365 schemes that are based on initiator identity is deemed important 6366 in order to support legacy systems and administration software. 6367 iSCSI thus supports the notion that it should be possible to 6368 assign access to storage resources based on "initiator device" 6369 identity. 6371 When there are multiple hardware or software components 6372 coordinated as a single iSCSI Node, there must be some (logical) 6373 entity that represents the iSCSI Node that makes the iSCSI Node 6374 Name available to all components involved in session creation and 6375 login. Similarly, this entity that represents the iSCSI Node must 6376 be able to coordinate session identifier resources (ISID for 6377 initiators) to enforce both the ISID and TSIH RULES (see Section 6378 4.4.3). 6380 For targets, because of the closed environment, implementation of 6381 this entity should be straightforward. However, vendors of iSCSI 6382 hardware (e.g., NICs or HBAs) intended for targets, SHOULD provide 6383 mechanisms for configuration of the iSCSI Node Name across the 6384 portal groups instantiated by multiple instances of these 6385 components within a target. 6387 However, complex targets making use of multiple Target Portal 6388 Group Tags may reconfigure them to achieve various quality goals. 6389 The initiators have two mechanisms at their disposal to discover 6390 and/or check reconfiguring targets - the discovery session type 6391 and a key returned by the target during login to confirm the TPGT. 6392 An initiator should attempt to "rediscover" the target 6393 configuration anytime a session is terminated unexpectedly. 6395 For initiators, in the long term, it is expected that operating 6396 system vendors will take on the role of this entity and provide 6397 standard APIs that can inform components of their iSCSI Node Name 6398 and can configure and/or coordinate ISID allocation, use, and 6399 reuse. 6401 Recognizing that such initiator APIs are not available today, 6402 other implementations of the role of this entity are possible. For 6403 example, a human may instantiate the (common) Node name as part of 6404 the installation process of each iSCSI component involved in 6405 session creation and login. This may be done either by pointing 6406 the component to a vendor-specific location for this datum or to a 6407 system-wide location. The structure of the ISID namespace (see 6408 Section 11.12.5 and [RFC3721]) facilitates implementation of the 6409 ISID coordination by allowing each component vendor to 6410 independently (of other vendor's components) coordinate 6411 allocation, use, and reuse of its own partition of the ISID 6412 namespace in a vendor-specific manner. Partitioning of the ISID 6413 namespace within initiator portal groups managed by that vendor 6414 allows each such initiator portal group to act independently of 6415 all other portal groups when selecting an ISID for a login; this 6416 facilitates enforcement of the ISID RULE (see Section 4.4.3) at 6417 the initiator. 6419 A vendor of iSCSI hardware (e.g., NICs or HBAs) intended for use 6420 in initiators MUST implement a mechanism for configuring the iSCSI 6421 Node Name. Vendors, and administrators must ensure that iSCSI Node 6422 Names are unique worldwide. It is therefore important that when 6423 one chooses to reuse the iSCSI Node Name of a disabled unit, not 6424 to re-assign that name to the original unit unless its worldwide 6425 uniqueness can be ascertained again. 6427 In addition, a vendor of iSCSI hardware must implement a mechanism 6428 to configure and/or coordinate ISIDs for all sessions managed by 6429 multiple instances of that hardware within a given iSCSI Node. 6430 Such configuration might be either permanently pre-assigned at the 6431 factory (in a necessarily globally unique way), statically 6432 assigned (e.g., partitioned across all the NICs at initialization 6433 in a locally unique way), or dynamically assigned (e.g., on-line 6434 allocator, also in a locally unique way). In the latter two cases, 6435 the configuration may be via public APIs (perhaps driven by an 6436 independent vendor's software, such as the OS vendor) or via 6437 private APIs driven by the vendor's own software. 6439 The process of name assignment and coordination has to be as 6440 encompassing and automated as possible as years of legacy usage 6441 have shown it to be highly error-prone. It is to be mentioned 6442 that SCSI has today alternative schemes of access control that can 6443 be used by all transports and their security is not dependent on 6444 strict naming coordination. 6446 10.2. Autosense and Auto Contingent Allegiance (ACA) 6448 Autosense refers to the automatic return of sense data to the 6449 initiator in case a command did not complete successfully. iSCSI 6450 initiators and targets MUST support and use autosense. 6452 ACA helps preserve ordered command execution in the presence of 6453 errors. As there can be many commands in-flight between an 6454 initiator and a target, SCSI initiator functionality in some 6455 operating systems depends on ACA to enforce ordered command 6456 execution during error recovery, and hence iSCSI initiator 6457 implementations for those operating systems need to support ACA. 6458 In order to support error recovery for these operating systems and 6459 iSCSI initiators, iSCSI targets SHOULD support ACA. 6461 10.3. iSCSI Timeouts 6463 iSCSI recovery actions are often dependent on iSCSI time-outs 6464 being recognized and acted upon before SCSI time-outs. Determining 6465 the right time-outs to use for various iSCSI actions (command 6466 acknowledgements expected, status acknowledgements, etc.) is very 6467 much dependent on infrastructure (hardware, links, TCP/IP stack, 6468 iSCSI driver). As a guide, the implementer may use an average Nop- 6469 Out/Nop-In turnaround delay multiplied by a "safety factor" (e.g., 6470 4) as a good estimate for the basic delay of the iSCSI stack for a 6471 given connection. The safety factor should account for the network 6472 load variability. For connection teardown the implementer may 6473 want to consider also TCP common practice for the given 6474 infrastructure. 6476 Text negotiations MAY also be subject to either time-limits or 6477 limits in the number of exchanges. Those SHOULD be generous enough 6478 to avoid affecting interoperability (e.g., allowing each key to be 6479 negotiated on a separate exchange). 6481 The relation between iSCSI timeouts and SCSI timeouts should also 6482 be considered. SCSI timeouts should be longer than iSCSI timeouts 6483 plus the time required for iSCSI recovery whenever iSCSI recovery 6484 is planned. Alternatively, an implementer may choose to interlock 6485 iSCSI timeouts and recovery with SCSI timeouts so that SCSI 6486 recovery will become active only where iSCSI is not planned to, or 6487 failed to, recover. 6489 The implementer may also want to consider the interaction between 6490 various iSCSI exception events - such as a digest failure - and 6491 subsequent timeouts. When iSCSI error recovery is active, a digest 6492 failure is likely to result in discovering a missing command or 6493 data PDU. In these cases, an implementer may want to lower the 6494 timeout values to enable faster initiation for recovery 6495 procedures. 6497 10.4. Command Retry and Cleaning Old Command Instances 6499 To avoid having old, retried command instances appear in a valid 6500 command window after a command sequence number wrap around, the 6501 protocol requires (see Section 4.2.2.1) that on every connection 6502 on which a retry has been issued, a non-immediate command be 6503 issued and acknowledged within a 2**31-1 commands interval from 6504 the CmdSN of the retried command. This requirement can be 6505 fulfilled by an implementation in several ways. 6507 The simplest technique to use is to send a (non-retry) non- 6508 immediate SCSI command (or a NOP if no SCSI command is available 6509 for a while) after every command retry on the connection on which 6510 the retry was attempted. As errors are deemed rare events, this 6511 technique is probably the most effective, as it does not involve 6512 additional checks at the initiator when issuing commands. 6514 10.5. Synch and Steering Layer and Performance 6516 While a synch and steering layer is optional, an initiator/target 6517 that does not have it working against a target/initiator that 6518 demands synch and steering may experience performance degradation 6519 caused by packet reordering and loss. Providing a synch and 6520 steering mechanism is recommended for all high-speed 6521 implementations. 6523 10.6. Considerations for State-dependent Devices and Long-lasting 6524 SCSI Operations 6526 Sequential access devices operate on the principle that the 6527 position of the device is based on the last command processed. As 6528 such, command processing order and knowledge of whether or not the 6529 previous command was processed is of the utmost importance to 6530 maintain data integrity. For example, inadvertent retries of SCSI 6531 commands when it is not known if the previous SCSI command was 6532 processed is a potential data integrity risk. 6534 For a sequential access device, consider the scenario in which a 6535 SCSI SPACE command to backspace one filemark is issued and then 6536 re-issued due to no status received for the command. If the first 6537 SPACE command was actually processed, the re-issued SPACE command, 6538 if processed, will cause the position to change. Thus, a 6539 subsequent write operation will write data to the wrong position 6540 and any previous data at that position will be overwritten. 6542 For a medium changer device, consider the scenario in which an 6543 EXCHANGE MEDIUM command (the SOURCE ADDRESS and DESTINATION 6544 ADDRESS are the same thus performing a swap) is issued and then 6545 re-issued due to no status received for the command. If the first 6546 EXCHANGE MEDIUM command was actually processed, the re-issued 6547 EXCHANGE MEDIUM command, if processed, will perform the swap 6548 again. The net effect is no swap was performed thus leaving a data 6549 integrity exposure. 6551 All commands that change the state of the device (as in SPACE 6552 commands for sequential access devices, and EXCHANGE MEDIUM for 6553 medium changer device), MUST be issued as non-immediate commands 6554 for deterministic and in order delivery to iSCSI targets. 6556 For many of those state changing commands, the execution model 6557 also assumes that the command is executed exactly once. Devices 6558 implementing READ POSITION and LOCATE provide a means for SCSI 6559 level command recovery and new tape-class devices should support 6560 those commands. In their absence a retry at SCSI level is 6561 difficult and error recovery at iSCSI level is advisable. 6563 Devices operating on long latency delivery subsystems and 6564 performing long lasting SCSI operations may need mechanisms that 6565 enable connection replacement while commands are running (e.g., 6566 during an extended copy operation). 6568 10.6.1. Determining the Proper ErrorRecoveryLevel 6570 The implementation and use of a specific ErrorRecoveryLevel should 6571 be determined based on the deployment scenarios of a given iSCSI 6572 implementation. Generally, the following factors must be 6573 considered before deciding on the proper level of recovery: 6575 a) Application resilience to I/O failures. 6576 b) Required level of availability in the face of transport 6577 connection failures. 6578 c) Probability of transport layer "checksum escape" (message 6579 error undetected by TCP checksum - see [RFC3385] for 6580 related discussion). This in turn decides the iSCSI 6581 digest failure frequency, and thus the criticality of 6582 iSCSI-level error recovery. The details of estimating 6583 this probability are outside the scope of this document. 6585 A consideration of the above factors for SCSI tape devices as an 6586 example suggests that implementations SHOULD use 6587 ErrorRecoveryLevel=1 when transport connection failure is not a 6588 concern and SCSI level recovery is unavailable, and 6589 ErrorRecoveryLevel=2 when the connection failure is also of high 6590 likelihood during a backup/retrieval. 6592 For extended copy operations, implementations SHOULD use 6593 ErrorRecoveryLevel=2 whenever there is a relatively high 6594 likelihood of connection failure. 6596 10.7. Multi-task Abort Implementation Considerations 6598 Multi-task abort operations are typically issued in emergencies - 6599 such as clearing a device lock-up, HA failover/failback etc. In 6600 these circumstances, it is desirable to rapidly go through the 6601 error handling process as opposed to the target waiting on 6602 multiple third-party initiators who may not even be functional 6603 anymore - especially if this emergency is triggered because of one 6604 such initiator failure. Therefore, both iSCSI target and 6605 initiator implementations SHOULD support FastAbort multi-task 6606 abort semantics (Section 4.2.3.4). 6608 Note that both in standard semantics (Section 4.2.3.3) and 6609 FastAbort semantics (Section 4.2.3.4), there may be outstanding 6610 data transfers even after the TMF completion is reported on the 6611 issuing session. In the case of iSCSI/iSER [iSER], these would be 6612 tagged data transfers for STags not owned by any active tasks. 6613 Whether or not real buffers support these data transfers is 6614 implementation-dependent. However, the data transfers logically 6615 MUST be silently discarded by the target iSCSI layer in all cases. 6616 A target MAY, on an implementation-defined internal timeout, also 6617 choose to drop the connections on which it did not receive the 6618 expected Data-Out sequences (Section 4.2.3.3) or NOP-Out 6619 acknowledgements (Section 4.2.3.4) so as to reclaim the associated 6620 buffer, STag, and TTT resources as appropriate. 6622 11. iSCSI PDU Formats 6624 All multi-byte integers that are specified in formats defined in 6625 this document are to be represented in network byte order (i.e., 6626 big endian). Any field that appears in this document assumes that 6627 the most significant byte is the lowest numbered byte and the most 6628 significant bit (within byte or field) is the lowest numbered bit 6629 unless specified otherwise. 6631 Any compliant sender MUST set all bits not defined and all 6632 reserved fields to zero unless specified otherwise. Any compliant 6633 receiver MUST ignore any bit not defined and all reserved fields 6634 unless specified otherwise. Receipt of reserved code values in 6635 defined fields MUST be reported as a protocol error. 6637 Reserved fields are marked by the word "reserved", some 6638 abbreviation of "reserved", or by "." for individual bits when no 6639 other form of marking is technically feasible. 6641 11.1. iSCSI PDU Length and Padding 6643 iSCSI PDUs are padded to the closest integer number of four byte 6644 words. The padding bytes SHOULD be sent as 0. 6646 11.2. PDU Template, Header, and Opcodes 6648 All iSCSI PDUs have one or more header segments and, optionally, a 6649 data segment. After the entire header segment group a header- 6650 digest MAY follow. The data segment MAY also be followed by a 6651 data-digest. 6653 The Basic Header Segment (BHS) is the first segment in all of the 6654 iSCSI PDUs. The BHS is a fixed-length 48-byte header segment. It 6655 MAY be followed by Additional Header Segments (AHS), a Header- 6656 Digest, a Data Segment, and/or a Data-Digest. 6658 The overall structure of an iSCSI PDU is as follows: 6660 Byte/ 0 | 1 | 2 | 3 | 6661 / | | | | 6662 |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 67| 6663 +---------------+---------------+---------------+--------------+ 6664 0/ Basic Header Segment (BHS) / 6665 +/ / 6666 +---------------+---------------+---------------+--------------+ 6667 48/ Additional Header Segment 1 (AHS) (optional) / 6668 +/ / 6669 +---------------+---------------+---------------+--------------+ 6670 / Additional Header Segment 2 (AHS) (optional) / 6671 +/ / 6672 +---------------+---------------+---------------+--------------+ 6673 +---------------+---------------+---------------+--------------+ 6674 / Additional Header Segment n (AHS) (optional) / 6675 +/ / 6676 +---------------+---------------+---------------+--------------+ 6677 k/ Header-Digest (optional) / 6678 +/ / 6679 +---------------+---------------+---------------+--------------+ 6680 l/ Data Segment(optional) / 6681 +/ / 6682 +---------------+---------------+---------------+--------------+ 6683 m/ Data-Digest (optional) / 6684 +/ / 6685 +---------------+---------------+---------------+--------------+ 6687 All PDU segments and digests are padded to the closest integer 6688 number of four byte words. For example, all PDU segments and 6689 digests start at a four byte word boundary and the padding ranges 6690 from 0 to 3 bytes. The padding bytes SHOULD be sent as 0. 6692 iSCSI response PDUs do not have AH Segments. 6694 11.2.1. Basic Header Segment (BHS) 6696 The BHS is 48 bytes long. The Opcode and DataSegmentLength fields 6697 appear in all iSCSI PDUs. In addition, when used, the Initiator 6698 Task Tag and Logical Unit Number always appear in the same 6699 location in the header. 6701 The format of the BHS is: 6703 Byte/ 0 | 1 | 2 | 3 | 6704 / | | | | 6705 |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 67| 6706 +---------------+---------------+---------------+--------------+ 6707 0|.|I| Opcode |F| Opcode-specific fields | 6708 +---------------+---------------+---------------+--------------+ 6709 4|TotalAHSLength | DataSegmentLength | 6710 +---------------+---------------+---------------+--------------+ 6711 8| LUN or Opcode-specific fields | 6712 + + 6713 12| | 6714 +---------------+---------------+---------------+--------------+ 6715 16| Initiator Task Tag | 6716 +---------------+---------------+---------------+--------------+ 6717 20/ Opcode-specific fields / 6718 +/ / 6719 +---------------+---------------+---------------+--------------+ 6720 48 6722 11.2.1.1. I 6724 For request PDUs, the I bit set to 1 is an immediate delivery 6725 marker. 6727 11.2.1.2. Opcode 6729 The Opcode indicates the type of iSCSI PDU the header 6730 encapsulates. 6732 The Opcodes are divided into two categories: initiator opcodes and 6733 target opcodes. Initiator opcodes are in PDUs sent by the 6734 initiator (request PDUs). Target opcodes are in PDUs sent by the 6735 target (response PDUs). 6737 Initiators MUST NOT use target opcodes and targets MUST NOT use 6738 initiator opcodes. 6740 Initiator opcodes defined in this specification are: 6742 0x00 NOP-Out 6744 0x01 SCSI Command (encapsulates a SCSI Command Descriptor 6745 Block) 6747 0x02 SCSI Task Management function request 6749 0x03 Login Request 6751 0x04 Text Request 6753 0x05 SCSI Data-out (for WRITE operations) 6755 0x06 Logout Request 6757 0x10 SNACK Request 6759 0x1c-0x1e Vendor specific codes 6761 Target opcodes are: 6763 0x20 NOP-In 6765 0x21 SCSI Response - contains SCSI status and possibly sense 6766 information or other response information. 6768 0x22 SCSI Task Management function response 6770 0x23 Login Response 6772 0x24 Text Response 6774 0x25 SCSI Data-in - for READ operations. 6776 0x26 Logout Response 6778 0x31 Ready To Transfer (R2T) - sent by target when it is ready 6779 to receive data. 6781 0x32 Asynchronous Message - sent by target to indicate certain 6782 special conditions. 6784 0x3c-0x3e Vendor specific codes 6786 0x3f Reject 6788 All other opcodes are reserved. 6790 11.2.1.3. Final (F) bit 6792 When set to 1 it indicates the final (or only) PDU of a sequence. 6794 11.2.1.4. Opcode-specific Fields 6796 These fields have different meanings for different opcode types. 6798 11.2.1.5. TotalAHSLength 6800 Total length of all AHS header segments in units of four byte 6801 words including padding, if any. 6803 The TotalAHSLength is only used in PDUs that have an AHS and MUST 6804 be 0 in all other PDUs. 6806 11.2.1.6. DataSegmentLength 6808 This is the data segment payload length in bytes (excluding 6809 padding). The DataSegmentLength MUST be 0 whenever the PDU has no 6810 data segment. 6812 11.2.1.7. LUN 6814 Some opcodes operate on a specific Logical Unit. The Logical Unit 6815 Number (LUN) field identifies which Logical Unit. If the opcode 6816 does not relate to a Logical Unit, this field is either ignored or 6817 may be used in an opcode specific way. The LUN field is 64-bits 6818 and should be formatted in accordance with [SAM2]. For example, 6819 LUN[0] from [SAM2] is BHS byte 8 and so on up to LUN[7] from 6820 [SAM2], which is BHS byte 15. 6822 11.2.1.8. Initiator Task Tag 6824 The initiator assigns a Task Tag to each iSCSI task it issues. 6825 While a task exists, this tag MUST uniquely identify the task 6826 session-wide. SCSI may also use the initiator task tag as part of 6827 the SCSI task identifier when the timespan during which an iSCSI 6828 initiator task tag must be unique extends over the timespan during 6829 which a SCSI task tag must be unique. However, the iSCSI Initiator 6830 Task Tag must exist and be unique even for untagged SCSI commands. 6832 An ITT value of 0xffffffff is reserved and MUST NOT be assigned 6833 for a task by the initiator. The only instance in which it may be 6834 seen on the wire is in a target-initiated NOP-In PDU (Section 6835 11.19) and in the initiator response to that PDU, if necessary. 6837 11.2.2. Additional Header Segment (AHS) 6839 The general format of an AHS is: 6841 Byte/ 0 | 1 | 2 | 3 | 6842 / | | | | 6843 |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 67| 6844 +---------------+---------------+---------------+--------------+ 6845 0| AHSLength | AHSType | AHS-Specific | 6846 +---------------+---------------+---------------+--------------+ 6847 4/ AHS-Specific / 6848 +/ / 6849 +---------------+---------------+---------------+--------------+ 6850 x 6852 11.2.2.1. AHSType 6854 The AHSType field is coded as follows: 6856 bit 0-1 - Reserved 6858 bit 2-7 - AHS code 6860 0 - Reserved 6862 1 - Extended CDB 6863 2 - Expected Bidirectional Read Data Length 6865 3 - 63 Reserved 6867 11.2.2.2. AHSLength 6869 This field contains the effective length in bytes of the AHS 6870 excluding AHSType and AHSLength and padding, if any. The AHS is 6871 padded to the smallest integer number of 4 byte words (i.e., from 6872 0 up to 3 padding bytes). 6874 11.2.2.3. Extended CDB AHS 6876 The format of the Extended CDB AHS is: 6878 Byte/ 0 | 1 | 2 | 3 | 6879 / | | | | 6880 |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 67| 6881 +---------------+---------------+---------------+--------------+ 6882 0| AHSLength (CDBLength-15) | 0x01 | Reserved | 6883 +---------------+---------------+---------------+--------------+ 6884 4/ ExtendedCDB...+padding / 6885 +/ / 6886 +---------------+---------------+---------------+--------------+ 6887 x 6889 This type of AHS MUST NOT be used if the CDBLength is less than 6890 17. 6891 The length includes the reserved byte 3. 6893 11.2.2.4. Bidirectional Expected Read-Data Length AHS 6895 The format of the Bidirectional Read Expected Data Transfer Length 6896 AHS is: 6898 Byte/ 0 | 1 | 2 | 3 | 6899 / | | | | 6900 |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 67| 6901 +---------------+---------------+---------------+--------------+ 6902 0| AHSLength (0x0005) | 0x02 | Reserved | 6903 +---------------+---------------+---------------+--------------+ 6904 4| Expected Read-Data Length | 6905 +---------------+---------------+---------------+--------------+ 6906 8 6908 11.2.3. Header Digest and Data Digest 6910 Optional header and data digests protect the integrity of the 6911 header and data, respectively. The digests, if present, are 6912 located, respectively, after the header and PDU-specific data, and 6913 cover respectively the header and the PDU data, each including 6914 the padding bytes, if any. 6916 The existence and type of digests are negotiated during the Login 6917 Phase. 6919 The separation of the header and data digests is useful in iSCSI 6920 routing applications, in which only the header changes when a 6921 message is forwarded. In this case, only the header digest should 6922 be recalculated. 6924 Digests are not included in data or header length fields. 6926 A zero-length Data Segment also implies a zero-length data-digest. 6928 11.2.4. Data Segment 6930 The (optional) Data Segment contains PDU associated data. Its 6931 payload effective length is provided in the BHS field - 6932 DataSegmentLength. The Data Segment is also padded to an integer 6933 number of 4 byte words. 6935 11.3. SCSI Command 6937 The format of the SCSI Command PDU is: 6939 Byte/ 0 | 1 | 2 | 3 | 6940 / | | | | 6941 |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 67| 6942 +---------------+---------------+---------------+--------------+ 6943 0|.|I| 0x01 |F|R|W|. .|ATTR | Reserved | 6944 +---------------+---------------+---------------+--------------+ 6945 4|TotalAHSLength | DataSegmentLength | 6946 +---------------+---------------+---------------+--------------+ 6947 8| Logical Unit Number (LUN) | 6948 + + 6949 12| | 6950 +---------------+---------------+---------------+--------------+ 6951 16| Initiator Task Tag | 6952 +---------------+---------------+---------------+--------------+ 6953 20| Expected Data Transfer Length | 6954 +---------------+---------------+---------------+--------------+ 6955 24| CmdSN | 6956 +---------------+---------------+---------------+--------------+ 6957 28| ExpStatSN | 6958 +---------------+---------------+---------------+--------------+ 6959 32/ SCSI Command Descriptor Block (CDB) / 6960 +/ / 6961 +---------------+---------------+---------------+--------------+ 6962 48/ AHS (Optional) / 6963 +---------------+---------------+---------------+--------------+ 6964 x/ Header Digest (Optional) / 6965 +---------------+---------------+---------------+--------------+ 6966 y/ (DataSegment, Command Data) (Optional) / 6967 +/ / 6968 +---------------+---------------+---------------+--------------+ 6969 z/ Data Digest (Optional) / 6970 +---------------+---------------+---------------+--------------+ 6972 11.3.1. Flags and Task Attributes (byte 1) 6974 The flags for a SCSI Command are: 6976 bit 0 (F) is set to 1 when no unsolicited SCSI Data-Out PDUs 6977 follow this PDU. When F=1 for a write and if Expected Data 6978 Transfer Length is larger than the DataSegmentLength, the 6979 target may solicit additional data through R2T. 6981 bit 1 (R) is set to 1 when the command is expected to input 6982 data. 6984 bit 2 (W) is set to 1 when the command is expected to output 6985 data. 6987 bit 3-4 Reserved. 6989 bit 5-7 contains Task Attributes. 6991 Task Attributes (ATTR) have one of the following integer values 6992 (see [SAM2] for details): 6994 0 - Untagged 6996 1 - Simple 6998 2 - Ordered 7000 3 - Head of Queue 7002 4 - ACA 7004 5-7 - Reserved 7006 At least one of the W and F bits MUST be set to 1. 7007 Either or both of R and W MAY be 1 when either the Expected Data 7008 Transfer Length and/or Bidirectional Read Expected Data Transfer 7009 Length are 0, but they MUST NOT both be 0 when the Expected Data 7010 Transfer Length and/or Bidirectional Read Expected Data Transfer 7011 Length are not 0 (i.e., when some data transfer is expected the 7012 transfer direction is indicated by the R and/or W bit). 7014 11.3.2. CmdSN - Command Sequence Number 7016 Enables ordered delivery across multiple connections in a single 7017 session. 7019 11.3.3. ExpStatSN 7021 Command responses up to ExpStatSN-1 (mod 2**32) have been received 7022 (acknowledges status) on the connection. 7024 11.3.4. Expected Data Transfer Length 7026 For unidirectional operations, the Expected Data Transfer Length 7027 field contains the number of bytes of data involved in this SCSI 7028 operation. For a unidirectional write operation (W flag set to 1 7029 and R flag set to 0), the initiator uses this field to specify the 7030 number of bytes of data it expects to transfer for this operation. 7031 For a unidirectional read operation (W flag set to 0 and R flag 7032 set to 1), the initiator uses this field to specify the number of 7033 bytes of data it expects the target to transfer to the initiator. 7034 It corresponds to the SAM2 byte count. 7036 For bidirectional operations (both R and W flags are set to 1), 7037 this field contains the number of data bytes involved in the write 7038 transfer. For bidirectional operations, an additional header 7039 segment MUST be present in the header sequence that indicates the 7040 Bidirectional Read Expected Data Transfer Length. The Expected 7041 Data Transfer Length field and the Bidirectional Read Expected 7042 Data Transfer Length field correspond to the SAM2 byte count. 7044 If the Expected Data Transfer Length for a write and the length of 7045 the immediate data part that follows the command (if any) are the 7046 same, then no more data PDUs are expected to follow. In this 7047 case, the F bit MUST be set to 1. 7049 If the Expected Data Transfer Length is higher than the 7050 FirstBurstLength (the negotiated maximum amount of unsolicited 7051 data the target will accept), the initiator MUST send the maximum 7052 amount of unsolicited data OR ONLY the immediate data, if any. 7054 Upon completion of a data transfer, the target informs the 7055 initiator (through residual counts) of how many bytes were 7056 actually processed (sent and/or received) by the target. 7058 11.3.5. CDB - SCSI Command Descriptor Block 7060 There are 16 bytes in the CDB field to accommodate the commonly 7061 used CDBs. Whenever the CDB is larger than 16 bytes, an Extended 7062 CDB AHS MUST be used to contain the CDB spillover. 7064 11.3.6. Data Segment - Command Data 7066 Some SCSI commands require additional parameter data to accompany 7067 the SCSI command. This data may be placed beyond the boundary of 7068 the iSCSI header in a data segment. Alternatively, user data 7069 (e.g., from a WRITE operation) can be placed in the data segment 7070 (both cases are referred to as immediate data). These data are 7071 governed by the rules for solicited vs. unsolicited data outlined 7072 in Section 4.2.5.2. 7074 11.4. SCSI Response 7076 The format of the SCSI Response PDU is: 7078 Byte/ 0 | 1 | 2 | 3 | 7079 / | | | | 7080 |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 67| 7081 +---------------+---------------+---------------+--------------+ 7082 0|.|.| 0x21 |1|. .|o|u|O|U|.| Response | Status | 7083 +---------------+---------------+---------------+--------------+ 7084 4|TotalAHSLength | DataSegmentLength | 7085 +---------------+---------------+---------------+--------------+ 7086 8| Reserved | 7087 + + 7088 12| | 7089 +---------------+---------------+---------------+--------------+ 7090 16| Initiator Task Tag | 7091 +---------------+---------------+---------------+--------------+ 7092 20| SNACK Tag or Reserved | 7093 +---------------+---------------+---------------+--------------+ 7094 24| StatSN | 7095 +---------------+---------------+---------------+--------------+ 7096 28| ExpCmdSN | 7097 +---------------+---------------+---------------+--------------+ 7098 32| MaxCmdSN | 7099 +---------------+---------------+---------------+--------------+ 7100 36| ExpDataSN or Reserved | 7101 +---------------+---------------+---------------+--------------+ 7102 40| Bidirectional Read Residual Count or Reserved | 7103 +---------------+---------------+---------------+--------------+ 7104 44| Residual Count or Reserved | 7105 +---------------+---------------+---------------+--------------+ 7106 48| Header-Digest (Optional) | 7107 +---------------+---------------+---------------+--------------+ 7108 / Data Segment (Optional) / 7109 +/ / 7110 +---------------+---------------+---------------+--------------+ 7111 | Data-Digest (Optional) | 7112 +---------------+---------------+---------------+--------------+ 7114 11.4.1. Flags (byte 1) 7116 bit 1-2 Reserved. 7118 bit 3 - (o) set for Bidirectional Read Residual Overflow. In 7119 this case, the Bidirectional Read Residual Count indicates 7120 the number of bytes that were not transferred to the 7121 initiator because the initiator's Expected Bidirectional 7122 Read Data Transfer Length was not sufficient. 7124 bit 4 - (u) set for Bidirectional Read Residual Underflow. In 7125 this case, the Bidirectional Read Residual Count indicates 7126 the number of bytes that were not transferred to the 7127 initiator out of the number of bytes expected to be 7128 transferred. 7130 bit 5 - (O) set for Residual Overflow. In this case, the 7131 Residual Count indicates the number of bytes that were not 7132 transferred because the initiator's Expected Data Transfer 7133 Length was not sufficient. For a bidirectional operation, 7134 the Residual Count contains the residual for the write 7135 operation. 7137 bit 6 - (U) set for Residual Underflow. In this case, the 7138 Residual Count indicates the number of bytes that were not 7139 transferred out of the number of bytes that were expected to 7140 be transferred. For a bidirectional operation, the Residual 7141 Count contains the residual for the write operation. 7143 bit 7 - (0) Reserved. 7145 Bits O and U and bits o and u are mutually exclusive (i.e., having 7146 both o and u or O and U set to 1 is a protocol error). 7148 For a response other than "Command Completed at Target", bits 3-6 7149 MUST be 0. 7151 11.4.2. Status 7153 The Status field is used to report the SCSI status of the command 7154 (as specified in [SAM2]) and is only valid if the Response Code is 7155 Command Completed at target. 7157 Some of the status codes defined in [SAM2] are: 7159 0x00 GOOD 7160 0x02 CHECK CONDITION 7162 0x08 BUSY 7164 0x18 RESERVATION CONFLICT 7166 0x28 TASK SET FULL 7168 0x30 ACA ACTIVE 7170 0x40 TASK ABORTED 7172 See [SAM2] for the complete list and definitions. 7174 If a SCSI device error is detected while data from the initiator 7175 is still expected (the command PDU did not contain all the data 7176 and the target has not received a Data PDU with the final bit 7177 Set), the target MUST wait until it receives a Data PDU with the F 7178 bit set in the last expected sequence before sending the Response 7179 PDU. 7181 11.4.3. Response 7183 This field contains the iSCSI service response. 7185 iSCSI service response codes defined in this specification are: 7187 0x00 - Command Completed at Target 7189 0x01 - Target Failure 7191 0x80-0xff - Vendor specific 7193 All other response codes are reserved. 7195 The Response is used to report a Service Response. The mapping of 7196 the response code into a SCSI service response code value, if 7197 needed, is outside the scope of this document. However, in 7198 symbolic terms response value 0x00 maps to the SCSI service 7199 response (see [SAM2] and [SPC3]) of TASK COMPLETE or LINKED 7200 COMMAND COMPLETE. All other Response values map to the SCSI 7201 service response of SERVICE DELIVERY OR TARGET FAILURE. 7203 If a SCSI Response PDU does not arrive before the session is 7204 terminated, the SCSI service response is SERVICE DELIVERY OR 7205 TARGET FAILURE. 7207 A non-zero response field indicates a failure to execute the 7208 command in which case the Status and Flag fields are undefined and 7209 MUST be ignored on reception. 7211 11.4.4. SNACK Tag 7213 This field contains a copy of the SNACK Tag of the last SNACK Tag 7214 accepted by the target on the same connection and for the command 7215 for which the response is issued. Otherwise it is reserved and 7216 should be set to 0. 7218 After issuing a R-Data SNACK the initiator must discard any SCSI 7219 status unless contained in an SCSI Response PDU carrying the same 7220 SNACK Tag as the last issued R-Data SNACK for the SCSI command on 7221 the current connection. 7223 For a detailed discussion on R-Data SNACK see 11.16.3. 7225 11.4.5. Residual Count 7227 11.4.5.1. Field Semantics 7229 The Residual Count field MUST be valid in the case where either 7230 the U bit or the O bit is set. If neither bit is set, the Residual 7231 Count field MUST be ignored on reception and SHOULD be set to 0 7232 when sending. Targets may set the residual count and initiators 7233 may use it when the response code is "completed at target" (even 7234 if the status returned is not GOOD). If the O bit is set, the 7235 Residual Count indicates the number of bytes that were not 7236 transferred because the initiator's Expected Data Transfer Length 7237 was not sufficient. If the U bit is set, the Residual Count 7238 indicates the number of bytes that were not transferred out of the 7239 number of bytes expected to be transferred. 7241 11.4.5.2. Residuals Concepts Overview 7243 SCSI-Presented Data Transfer Length (SPDTL) is the term this 7244 document uses (see Section 2.1 for definition) to represent the 7245 aggregate data length that the target SCSI layer attempts to 7246 transfer using the local iSCSI layer for a task. Expected Data 7247 Transfer Length (EDTL) is the iSCSI term that represents the 7248 length of data that the iSCSI layer expects to transfer for a 7249 task. EDTL is specified in the SCSI Command PDU. 7251 When SPDTL = EDTL for a task, the target iSCSI layer completes the 7252 task with no residuals. Whenever SPDTL differs from EDTL for a 7253 task, that task is said to have a residual. 7255 If SPDTL > EDTL for a task, iSCSI Overflow MUST be signaled in the 7256 SCSI Response PDU as specified in Section 11.4.5.1. The Residual 7257 Count MUST be set to the numerical value of (SPDTL - EDTL). 7259 If SPDTL < EDTL for a task, iSCSI Underflow MUST be signaled in 7260 the SCSI Response PDU as specified in Section 11.4.5.1. The 7261 Residual Count MUST be set to the numerical value of (EDTL - 7262 SPDTL). 7264 Note that the Overflow and Underflow scenarios are independent of 7265 Data-In and Data-Out. Either scenario is logically possible in 7266 either direction of data transfer. 7268 11.4.5.3. SCSI REPORT LUNS and Residual Overflow 7270 This Section discusses the residual overflow issues citing the 7271 example of the SCSI REPORT LUNS command. Note however that there 7272 are several SCSI commands (e.g., INQUIRY) with ALLOCATION LENGTH 7273 fields following the same underlying rules. The semantics in the 7274 rest of the Section apply to all such SCSI commands. 7276 The specification of the SCSI REPORT LUNS command requires that 7277 the SCSI target limit the amount of data transferred to a maximum 7278 size (ALLOCATION LENGTH) provided by the initiator in the REPORT 7279 LUNS CDB. 7281 If the Expected Data Transfer Length (EDTL) in the iSCSI header of 7282 the SCSI Command PDU for a REPORT LUNS command is set to at least 7283 as large as that ALLOCATION LENGTH, the SCSI layer truncation 7284 prevents an iSCSI Residual Overflow from occurring. A SCSI 7285 initiator can detect that such truncation has occurred via other 7286 information at the SCSI layer. The rest of the Section elaborates 7287 this required behavior. 7289 The SCSI REPORT LUNS command requests a target SCSI layer to 7290 return a logical unit inventory (LUN list) to the initiator SCSI 7291 layer (see Section 6.21 of [SPC3]). The size of this LUN list may 7292 not be known to the initiator SCSI layer when it issues the REPORT 7293 LUNS command; to avoid transferring more LUN list data than the 7294 initiator is prepared for, the REPORT LUNS CDB contains an 7295 ALLOCATION LENGTH field to specify the maximum amount of data to 7296 be transferred to the initiator for this command. If the initiator 7297 SCSI layer has underestimated the number of logical units at the 7298 target, it is possible that the complete logical unit inventory 7299 does not fit in the specified ALLOCATION LENGTH. In this 7300 situation, Section 4.3.3.6 in [SPC3] requires that the target SCSI 7301 layer "shall terminate transfers to the Data-In Buffer" when the 7302 number of bytes specified by the ALLOCATION LENGTH field have been 7303 transferred. 7305 Therefore, in response to a REPORT LUNS command, the SCSI layer at 7306 the target presents at most ALLOCATION LENGTH bytes of data 7307 (logical unit inventory) to iSCSI for transfer to the initiator. 7308 For a REPORT LUNS command, if the iSCSI EDTL is at least as large 7309 as the ALLOCATION LENGTH, the SCSI truncation ensures that the 7310 EDTL will accommodate all of the data to be transferred. If all of 7311 the logical unit inventory data presented to the iSCSI layer -- 7312 i.e., the data remaining after any SCSI truncation -- is 7313 transferred to the initiator by the iSCSI layer, an iSCSI Residual 7314 Overflow has not occurred and the iSCSI (O) bit MUST NOT be set in 7315 the SCSI Response or final SCSI Data-Out PDU. Note that this 7316 behavior is implied by the combination of Section 11.4.5.1 along 7317 with the specification of the REPORT LUNS command in [SPC3]. 7318 However, if the iSCSI EDTL is larger than the ALLOCATION LENGTH in 7319 this scenario, note that the iSCSI Underflow MUST be signaled in 7320 the SCSI Response PDU. An iSCSI Underflow MUST also be signaled 7321 when the iSCSI EDTL is equal to the ALLOCATION LENGTH but the 7322 logical unit inventory data presented to the iSCSI layer is 7323 smaller than the ALLOCATION LENGTH. 7325 The LUN LIST LENGTH field in the logical unit inventory (the first 7326 field in the inventory) is not affected by truncation of the 7327 inventory to fit in ALLOCATION LENGTH; this enables a SCSI 7328 initiator to determine that the received inventory is incomplete 7329 by noticing that the LUN LIST LENGTH in the inventory is larger 7330 than the ALLOCATION LENGTH that was sent in the REPORT LUNS CDB. A 7331 common initiator behavior in this situation is to re-issue the 7332 REPORT LUNS command with a larger ALLOCATION LENGTH. 7334 11.4.6. Bidirectional Read Residual Count 7336 The Bidirectional Read Residual Count field MUST be valid in the 7337 case where either the u bit or the o bit is set. If neither bit is 7338 set, the Bidirectional Read Residual Count field is reserved. 7339 Targets may set the Bidirectional Read Residual Count and 7340 initiators may use it when the response code is "completed at 7341 target". If the o bit is set, the Bidirectional Read Residual 7342 Count indicates the number of bytes that were not transferred to 7343 the initiator because the initiator's Expected Bidirectional Read 7344 Transfer Length was not sufficient. If the u bit is set, the 7345 Bidirectional Read Residual Count indicates the number of bytes 7346 that were not transferred to the initiator out of the number of 7347 bytes expected to be transferred. 7349 11.4.7. Data Segment - Sense and Response Data Segment 7351 iSCSI targets MUST support and enable autosense. If Status is 7352 CHECK CONDITION (0x02), then the Data Segment MUST contain sense 7353 data for the failed command. 7355 For some iSCSI responses, the response data segment MAY contain 7356 some response related information, (e.g., for a target failure, it 7357 may contain a vendor specific detailed description of the 7358 failure). 7360 If the DataSegmentLength is not 0, the format of the Data Segment 7361 is as follows: 7363 Byte/ 0 | 1 | 2 | 3 | 7364 / | | | | 7365 |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 67| 7366 +---------------+---------------+---------------+--------------+ 7367 0|SenseLength | Sense Data | 7368 +---------------+---------------+---------------+--------------+ 7369 x/ Sense Data / 7370 +---------------+---------------+---------------+--------------+ 7371 y/ Response Data / 7372 / / 7373 +---------------+---------------+---------------+--------------+ 7375 11.4.7.1. SenseLength 7377 Length of Sense Data. 7379 11.4.7.2. Sense Data 7381 The Sense Data contains detailed information about a check 7382 condition and [SPC3] specifies the format and content of the Sense 7383 Data. 7385 Certain iSCSI conditions result in the command being terminated at 7386 the target (response Command Completed at Target) with a SCSI 7387 Check Condition Status as outlined in the next table: 7389 +--------------------------+----------+--------------------------+ 7390 | iSCSI Condition |Sense | Additional Sense Code & | 7391 | |Key | Qualifier | 7392 +--------------------------+----------+--------------------------+ 7393 | Unexpected unsolicited |Aborted | ASC = 0x0c ASCQ = 0x0c | 7394 | data |Command-0B| Write Error | 7395 +--------------------------+----------+--------------------------+ 7396 | Incorrect amount of data |Aborted | ASC = 0x0c ASCQ = 0x0d | 7397 | |Command-0B| Write Error | 7398 +--------------------------+----------+--------------------------+ 7399 | Protocol Service CRC |Aborted | ASC = 0x47 ASCQ = 0x05 | 7400 | error |Command-0B| CRC Error Detected | 7401 +--------------------------+----------+--------------------------+ 7402 | SNACK rejected |Aborted | ASC = 0x11 ASCQ = 0x13 | 7403 | |Command-0B| Read Error | 7404 +--------------------------+----------+--------------------------+ 7406 The target reports the "Incorrect amount of data" condition if 7407 during data output the total data length to output is greater than 7408 FirstBurstLength and the initiator sent unsolicited non-immediate 7409 data but the total amount of unsolicited data is different than 7410 FirstBurstLength. The target reports the same error when the 7411 amount of data sent as a reply to an R2T does not match the amount 7412 requested. 7414 11.4.8. ExpDataSN 7416 The number of Data-In (read) PDUs the target has sent for the 7417 command. 7419 This field MUST be 0 if the response code is not Command Completed 7420 at Target or the target sent no Data-In PDUs for the command. 7422 11.4.9. StatSN - Status Sequence Number 7424 StatSN is a Sequence Number that the target iSCSI layer generates 7425 per connection and that in turn, enables the initiator to 7426 acknowledge status reception. StatSN is incremented by 1 for every 7427 response/status sent on a connection except for responses sent as 7428 a result of a retry or SNACK. In the case of responses sent due to 7429 a retransmission request, the StatSN MUST be the same as the first 7430 time the PDU was sent unless the connection has since been 7431 restarted. 7432 11.4.10. ExpCmdSN - Next Expected CmdSN from this Initiator 7434 ExpCmdSN is a Sequence Number that the target iSCSI returns to the 7435 initiator to acknowledge command reception. It is used to update a 7436 local variable with the same name. An ExpCmdSN equal to MaxCmdSN+1 7437 indicates that the target cannot accept new commands. 7439 11.4.11. MaxCmdSN - Maximum CmdSN from this Initiator 7441 MaxCmdSN is a Sequence Number that the target iSCSI returns to the 7442 initiator to indicate the maximum CmdSN the initiator can send. It 7443 is used to update a local variable with the same name. If MaxCmdSN 7444 is equal to ExpCmdSN-1, this indicates to the initiator that the 7445 target cannot receive any additional commands. When MaxCmdSN 7446 changes at the target while the target has no pending PDUs to 7447 convey this information to the initiator, it MUST generate a NOP- 7448 IN to carry the new MaxCmdSN. 7450 11.5. Task Management Function Request 7452 Byte/ 0 | 1 | 2 | 3 | 7453 / | | | | 7454 |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 67| 7455 +---------------+---------------+---------------+--------------+ 7456 0|.|I| 0x02 |1| Function | Reserved | 7457 +---------------+---------------+---------------+--------------+ 7458 4|TotalAHSLength | DataSegmentLength | 7459 +---------------+---------------+---------------+--------------+ 7460 8| Logical Unit Number (LUN) or Reserved | 7461 + + 7462 12| | 7463 +---------------+---------------+---------------+--------------+ 7464 16| Initiator Task Tag | 7465 +---------------+---------------+---------------+--------------+ 7466 20| Referenced Task Tag or 0xffffffff | 7467 +---------------+---------------+---------------+--------------+ 7468 24| CmdSN | 7469 +---------------+---------------+---------------+--------------+ 7470 28| ExpStatSN | 7471 +---------------+---------------+---------------+--------------+ 7472 32| RefCmdSN or Reserved | 7473 +---------------+---------------+---------------+--------------+ 7474 36| ExpDataSN or Reserved | 7475 +---------------+---------------+---------------+--------------+ 7476 40/ Reserved / 7477 +/ / 7478 +---------------+---------------+---------------+--------------+ 7479 48| Header-Digest (Optional) | 7480 +---------------+---------------+---------------+--------------+ 7482 11.5.1. Function 7484 The Task Management functions provide an initiator with a way to 7485 explicitly control the execution of one or more Tasks (SCSI and 7486 iSCSI tasks). The Task Management function codes are listed below. 7487 For a more detailed description of SCSI task management, see 7488 [SAM2]. 7490 1 - ABORT TASK - aborts the task identified by the 7491 Referenced Task Tag field. 7493 2 - ABORT TASK SET - aborts all Tasks issued via this 7494 session on the logical unit. 7496 3 - CLEAR ACA - clears the Auto Contingent Allegiance 7497 condition. 7499 4 - CLEAR TASK SET - aborts all Tasks in the appropriate 7500 task set as defined by the TST field in the Control mode 7501 page (see [SPC3]). 7503 5 - LOGICAL UNIT RESET 7505 6 - TARGET WARM RESET 7507 7 - TARGET COLD RESET 7509 8 - TASK REASSIGN - reassigns connection allegiance for the 7510 task identified by the Initiator Task Tag field to this 7511 connection, thus resuming the iSCSI exchanges for the task. 7513 All other possible values for Function field are reserved. 7515 For all these functions, the Task Management function response 7516 MUST be returned as detailed in Section 11.6. All these functions 7517 apply to the referenced tasks regardless of whether they are 7518 proper SCSI tasks or tagged iSCSI operations. Task management 7519 requests must act on all the commands from the same session having 7520 a CmdSN lower than the task management CmdSN. LOGICAL UNIT RESET, 7521 TARGET WARM RESET and TARGET COLD RESET may affect commands from 7522 other sessions or commands from the same session regardless of 7523 their CmdSN value. 7525 If the task management request is marked for immediate delivery, 7526 it must be considered immediately for execution, but the 7527 operations involved (all or part of them) may be postponed to 7528 allow the target to receive all relevant tasks. According to 7529 [SAM2], for all the tasks covered by the Task Management response 7530 (i.e., with CmdSN lower than the task management command CmdSN) 7531 but except the Task Management response to a TASK REASSIGN, 7532 additional responses MUST NOT be delivered to the SCSI layer after 7533 the Task Management response. The iSCSI initiator MAY deliver to 7534 the SCSI layer all responses received before the Task Management 7535 response (i.e., it is a matter of implementation if the SCSI 7536 responses, received before the Task Management response but after 7537 the task management request was issued, are delivered to the SCSI 7538 layer by the iSCSI layer in the initiator). The iSCSI target MUST 7539 ensure that no responses for the tasks covered by a task 7540 management function are delivered to the iSCSI initiator after the 7541 Task Management response except for a task covered by a TASK 7542 REASSIGN. 7544 For ABORT TASK SET and CLEAR TASK SET, the issuing initiator MUST 7545 continue to respond to all valid target transfer tags (received 7546 via R2T, Text Response, NOP-In, or SCSI Data-in PDUs) related to 7547 the affected task set, even after issuing the task management 7548 request. The issuing initiator SHOULD however terminate (i.e., by 7549 setting the F-bit to 1) these response sequences as quickly as 7550 possible. The target on its part MUST wait for responses on all 7551 affected target transfer tags before acting on either of these two 7552 task management requests. In case all or part of the response 7553 sequence is not received (due to digest errors) for a valid TTT, 7554 the target MAY treat it as a case of within-command error recovery 7555 class (see Section 7.1.4.1) if it is supporting ErrorRecoveryLevel 7556 >= 1, or alternatively may drop the connection to complete the 7557 requested task set function. 7559 If an ABORT TASK is issued for a task created by an immediate 7560 command then RefCmdSN MUST be that of the Task Management request 7561 itself (i.e. CmdSN and RefCmdSN are equal); otherwise RefCmdSN 7562 MUST be set to the CmdSN of the task to be aborted (lower than 7563 CmdSN). 7565 If the connection is still active (it is not undergoing an 7566 implicit or explicit logout), ABORT TASK MUST be issued on the 7567 same connection to which the task to be aborted is allegiant at 7568 the time the Task Management Request is issued. If the connection 7569 is implicitly or explicitly logged out (i.e., no other request 7570 will be issued on the failing connection and no other response 7571 will be received on the failing connection), then an ABORT TASK 7572 function request may be issued on another connection. This Task 7573 Management request will then establish a new allegiance for the 7574 command to be aborted as well as abort it (i.e., the task to be 7575 aborted will not have to be retried or reassigned, and its status, 7576 if sent but not acknowledged, will be resent followed by the Task 7577 Management response). 7579 At the target an ABORT TASK function MUST NOT be executed on a 7580 Task Management request; such a request MUST result in Task 7581 Management response of "Function rejected". 7583 For the LOGICAL UNIT RESET function, the target MUST behave as 7584 dictated by the Logical Unit Reset function in [SAM2]. 7586 The implementation of the TARGET WARM RESET function and the 7587 TARGET COLD RESET function is OPTIONAL and when implemented, 7588 should act as described below. The TARGET WARM RESET is also 7589 subject to SCSI access controls on the requesting initiator as 7590 defined in [SPC3]. When authorization fails at the target, the 7591 appropriate response as described in Section 11.6.1 MUST be 7592 returned by the target. The TARGET COLD RESET function is not 7593 subject to SCSI access controls, but its execution privileges may 7594 be managed by iSCSI mechanisms such as login authentication. 7596 When executing the TARGET WARM RESET and TARGET COLD RESET 7597 functions, the target cancels all pending operations on all 7598 Logical Units known by the issuing initiator. Both functions are 7599 equivalent to the Target Reset function specified by [SAM2]. They 7600 can affect many other initiators logged in with the servicing SCSI 7601 target port. 7603 The target MUST treat the TARGET COLD RESET function additionally 7604 as a power on event, thus terminating all of its TCP connections 7605 to all initiators (all sessions are terminated). For this reason, 7606 the Service Response (defined by [SAM2]) for this SCSI task 7607 management function may not be reliably delivered to the issuing 7608 initiator port. 7610 For the TASK REASSIGN function, the target should reassign the 7611 connection allegiance to this new connection (and thus resume 7612 iSCSI exchanges for the task). TASK REASSIGN MUST ONLY be received 7613 by the target after the connection on which the command was 7614 previously executing has been successfully logged-out. The Task 7615 Management response MUST be issued before the reassignment becomes 7616 effective. 7618 For additional usage semantics see Section 7.2. 7620 At the target a TASK REASSIGN function request MUST NOT be 7621 executed to reassign the connection allegiance of a Task 7622 Management function request, an active text negotiation task, or a 7623 Logout task; such a request MUST result in Task Management 7624 response of "Function rejected". 7626 TASK REASSIGN MUST be issued as an immediate command. 7628 11.5.2. TotalAHSLength and DataSegmentLength 7630 For this PDU, TotalAHSLength and DataSegmentLength MUST be 0. 7632 11.5.3. LUN 7634 This field is required for functions that address a specific LU 7635 (ABORT TASK, CLEAR TASK SET, ABORT TASK SET, CLEAR ACA, LOGICAL 7636 UNIT RESET) and is reserved in all others. 7638 11.5.4. Referenced Task Tag 7640 The Initiator Task Tag of the task to be aborted for the ABORT 7641 TASK function or reassigned for the TASK REASSIGN function. For 7642 all the other functions this field MUST be set to the reserved 7643 value 0xffffffff. 7645 11.5.5. RefCmdSN 7647 If an ABORT TASK is issued for a task created by an immediate 7648 command then RefCmdSN MUST be that of the Task Management request 7649 itself (i.e. CmdSN and RefCmdSN are equal). 7651 For an ABORT TASK of a task created by non-immediate command 7652 RefCmdSN MUST be set to the CmdSN of the task identified by the 7653 Referenced Task Tag field. Targets must use this field as 7654 described in Section 11.6.1 when the task identified by the 7655 Referenced Task Tag field is not with the target. 7657 Otherwise, this field is reserved. 7659 11.5.6. ExpDataSN 7661 For recovery purposes, the iSCSI target and initiator maintain a 7662 data acknowledgement reference number - the first input DataSN 7663 number unacknowledged by the initiator. When issuing a new 7664 command, this number is set to 0. If the function is TASK 7665 REASSIGN, which establishes a new connection allegiance for a 7666 previously issued Read or Bidirectional command, ExpDataSN will 7667 contain an updated data acknowledgement reference number or the 7668 value 0; the latter indicating that the data acknowledgement 7669 reference number is unchanged. The initiator MUST discard any data 7670 PDUs from the previous execution that it did not acknowledge and 7671 the target MUST transmit all Data-in PDUs (if any) starting with 7672 the data acknowledgement reference number. The number of 7673 retransmitted PDUs may or may not be the same as the original 7674 transmission depending on if there was a change in 7675 MaxRecvDataSegmentLength in the reassignment. The target MAY also 7676 send no more Data-In PDUs if all data has been acknowledged. 7678 The value of ExpDataSN MUST be 0 or higher than the DataSN of the 7679 last acknowledged Data-In PDU, but not larger than DataSN+1 of the 7680 last Data-IN PDU sent by the target. Any other value MUST be 7681 ignored by the target. 7683 For other functions this field is reserved. 7685 11.6. Task Management Function Response 7686 Byte/ 0 | 1 | 2 | 3 | 7687 / | | | | 7688 |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 67| 7689 +---------------+---------------+---------------+--------------+ 7690 0|.|.| 0x22 |1| Reserved | Response | Reserved | 7691 +---------------+---------------+---------------+--------------+ 7692 4|TotalAHSLength | DataSegmentLength | 7693 +--------------------------------------------------------------+ 7694 8/ Reserved / 7695 / / 7696 +---------------+---------------+---------------+--------------+ 7697 16| Initiator Task Tag | 7698 +---------------+---------------+---------------+--------------+ 7699 20| Reserved | 7700 +---------------+---------------+---------------+--------------+ 7701 24| StatSN | 7702 +---------------+---------------+---------------+--------------+ 7703 28| ExpCmdSN | 7704 +---------------+---------------+---------------+--------------+ 7705 32| MaxCmdSN | 7706 +---------------+---------------+---------------+--------------+ 7707 36/ Reserved / 7708 +/ / 7709 +---------------+---------------+---------------+--------------+ 7710 48| Header-Digest (Optional) | 7711 +---------------+---------------+---------------+--------------+ 7713 For the functions ABORT TASK, ABORT TASK SET, CLEAR ACA, CLEAR 7714 TASK SET, LOGICAL UNIT RESET, TARGET COLD RESET, TARGET WARM RESET 7715 and TASK REASSIGN, the target performs the requested Task 7716 Management function and sends a Task Management response back to 7717 the initiator. For TASK REASSIGN, the new connection allegiance 7718 MUST ONLY become effective at the target after the target issues 7719 the Task Management Response. 7721 11.6.1. Response 7723 The target provides a Response, which may take on the following 7724 values: 7726 0 - Function complete. 7727 1 - Task does not exist. 7729 2 - LUN does not exist. 7730 3 - Task still allegiant. 7731 4 - Task allegiance reassignment not supported. 7732 5 - Task management function not supported. 7733 6 - Function authorization failed. 7734 255 - Function rejected. 7736 All other values are reserved. 7738 For a discussion on usage of response codes 3 and 4, see Section 7739 7.2.2. 7741 For the TARGET COLD RESET and TARGET WARM RESET functions, the 7742 target cancels all pending operations across all Logical Units 7743 known to the issuing initiator. For the TARGET COLD RESET 7744 function, the target MUST then close all of its TCP connections to 7745 all initiators (terminates all sessions). 7747 The mapping of the response code into a SCSI service response code 7748 value, if needed, is outside the scope of this document. However, 7749 in symbolic terms, Response values 0 and 1 map to the SCSI service 7750 response of FUNCTION COMPLETE. Response value 2 maps to SCSI 7751 service response of INCORRECT LOGICAL UNIT NUMBER. All other 7752 Response values map to the SCSI service response of FUNCTION 7753 REJECTED. If a Task Management function response PDU does not 7754 arrive before the session is terminated, the SCSI service response 7755 is SERVICE DELIVERY OR TARGET FAILURE. 7757 The response to ABORT TASK SET and CLEAR TASK SET MUST only be 7758 issued by the target after all of the commands affected have been 7759 received by the target, the corresponding task management 7760 functions have been executed by the SCSI target, and the delivery 7761 of all responses delivered until the task management function 7762 completion have been confirmed (acknowledged through ExpStatSN) by 7763 the initiator on all connections of this session. For the exact 7764 timeline of events, refer to Section 4.2.3.3 and Section 4.2.3.4. 7766 For the ABORT TASK function, 7767 a) If the Referenced Task Tag identifies a valid task leading 7768 to a successful termination, then targets must return the 7769 "Function complete" response. 7770 b) If the Referenced Task Tag does not identify an existing 7771 task, but if the CmdSN indicated by the RefCmdSN field in 7772 the Task Management function request is within the valid 7773 CmdSN window and less than the CmdSN of the Task Management 7774 function request itself, then targets must consider the 7775 CmdSN received and return the "Function complete" response. 7776 c) If the Referenced Task Tag does not identify an existing 7777 task and if the CmdSN indicated by the RefCmdSN field in 7778 the Task Management function request is outside the valid 7779 CmdSN window, then targets must return the "Task does not 7780 exist" response. 7782 For response semantics on function types that can potentially 7783 impact multiple active tasks on the target, see Section 4.2.3. 7785 11.6.2. TotalAHSLength and DataSegmentLength 7787 For this PDU TotalAHSLength and DataSegmentLength MUST be 0. 7789 11.7. SCSI Data-out & SCSI Data-in 7791 The SCSI Data-out PDU for WRITE operations has the following 7792 format: 7794 Byte/ 0 | 1 | 2 | 3 | 7795 / | | | | 7796 |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 67| 7797 +---------------+---------------+---------------+--------------+ 7798 0|.|.| 0x05 |F| Reserved | 7799 +---------------+---------------+---------------+--------------+ 7800 4|TotalAHSLength | DataSegmentLength | 7801 +---------------+---------------+---------------+--------------+ 7802 8| LUN or Reserved | 7803 + + 7804 12| | 7805 +---------------+---------------+---------------+--------------+ 7806 16| Initiator Task Tag | 7807 +---------------+---------------+---------------+--------------+ 7808 20| Target Transfer Tag or 0xffffffff | 7809 +---------------+---------------+---------------+--------------+ 7810 24| Reserved | 7811 +---------------+---------------+---------------+--------------+ 7812 28| ExpStatSN | 7813 +---------------+---------------+---------------+--------------+ 7814 32| Reserved | 7815 +---------------+---------------+---------------+--------------+ 7816 36| DataSN | 7817 +---------------+---------------+---------------+--------------+ 7818 40| Buffer Offset | 7819 +---------------+---------------+---------------+--------------+ 7820 44| Reserved | 7821 +---------------+---------------+---------------+--------------+ 7822 48| Header-Digest (Optional) | 7823 +---------------+---------------+---------------+--------------+ 7824 / DataSegment / 7825 +/ / 7826 +---------------+---------------+---------------+--------------+ 7827 | Data-Digest (Optional) | 7828 +---------------+---------------+---------------+--------------+ 7830 The SCSI Data-in PDU for READ operations has the following format: 7832 Byte/ 0 | 1 | 2 | 3 | 7833 / | | | | 7834 |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 67| 7835 +---------------+---------------+---------------+--------------+ 7836 0|.|.| 0x25 |F|A|0 0 0|O|U|S| Reserved |Status or Rsvd| 7837 +---------------+---------------+---------------+--------------+ 7838 4|TotalAHSLength | DataSegmentLength | 7839 +---------------+---------------+---------------+--------------+ 7840 8| LUN or Reserved | 7841 + + 7842 12| | 7843 +---------------+---------------+---------------+--------------+ 7844 16| Initiator Task Tag | 7845 +---------------+---------------+---------------+--------------+ 7846 20| Target Transfer Tag or 0xffffffff | 7847 +---------------+---------------+---------------+--------------+ 7848 24| StatSN or Reserved | 7849 +---------------+---------------+---------------+--------------+ 7850 28| ExpCmdSN | 7851 +---------------+---------------+---------------+--------------+ 7852 32| MaxCmdSN | 7853 +---------------+---------------+---------------+--------------+ 7854 36| DataSN | 7855 +---------------+---------------+---------------+--------------+ 7856 40| Buffer Offset | 7857 +---------------+---------------+---------------+--------------+ 7858 44| Residual Count | 7859 +---------------+---------------+---------------+--------------+ 7860 48| Header-Digest (Optional) | 7861 +---------------+---------------+---------------+--------------+ 7862 / DataSegment / 7863 +/ / 7864 +---------------+---------------+---------------+--------------+ 7865 | Data-Digest (Optional) | 7866 +---------------+---------------+---------------+--------------+ 7868 Status can accompany the last Data-in PDU if the command did not 7869 end with an exception (i.e., the status is "good status" - GOOD, 7870 CONDITION MET or INTERMEDIATE CONDITION MET). The presence of 7871 status (and of a residual count) is signaled though the S flag 7872 bit. Although targets MAY choose to send even non-exception 7873 status in separate responses, initiators MUST support non- 7874 exception status in Data-In PDUs. 7876 11.7.1. F (Final) Bit 7878 For outgoing data, this bit is 1 for the last PDU of unsolicited 7879 data or the last PDU of a sequence that answers an R2T. 7881 For incoming data, this bit is 1 for the last input (read) data 7882 PDU of a sequence. Input can be split into several sequences, 7883 each having its own F bit. Splitting the data stream into 7884 sequences does not affect DataSN counting on Data-In PDUs. It MAY 7885 be used as a "change direction" indication for Bidirectional 7886 operations that need such a change. 7888 DataSegmentLength MUST NOT exceed MaxRecvDataSegmentLength for the 7889 direction it is sent and the total of all the DataSegmentLength of 7890 all PDUs in a sequence MUST NOT exceed MaxBurstLength (or 7891 FirstBurstLength for unsolicited data). However the number of 7892 individual PDUs in a sequence (or in total) may be higher than the 7893 MaxBurstLength (or FirstBurstLength) to MaxRecvDataSegmentLength 7894 ratio (as PDUs may be limited in length by the sender 7895 capabilities). Using DataSegmentLength of 0 may increase beyond 7896 what is reasonable for the number of PDUs and should therefore be 7897 avoided. 7899 For Bidirectional operations, the F bit is 1 for both the end of 7900 the input sequences and the end of the output sequences. 7902 11.7.2. A (Acknowledge) bit 7904 For sessions with ErrorRecoveryLevel 1 or higher, the target sets 7905 this bit to 1 to indicate that it requests a positive 7906 acknowledgement from the initiator for the data received. The 7907 target should use the A bit moderately; it MAY only set the A bit 7908 to 1 once every MaxBurstLength bytes, or on the last Data-In PDU 7909 that concludes the entire requested read data transfer for the 7910 task from the target's perspective, and it MUST NOT do so more 7911 frequently. The target MUST NOT set to 1 the A bit for sessions 7912 with ErrorRecoveryLevel=0. The initiator MUST ignore the A bit set 7913 to 1 for sessions with ErrorRecoveryLevel=0. 7915 On receiving a Data-In PDU with the A bit set to 1 on a session 7916 with ErrorRecoveryLevel greater than 0, if there are no holes in 7917 the read data until that Data-In PDU, the initiator MUST issue a 7918 SNACK of type DataACK except when it is able to acknowledge the 7919 status for the task immediately via ExpStatSN on other outbound 7920 PDUs if the status for the task is also received. In the latter 7921 case (acknowledgement through ExpStatSN), sending a SNACK of type 7922 DataACK in response to the A bit is OPTIONAL, but if it is done, 7923 it must not be sent after the status acknowledgement through 7924 ExpStatSN. If the initiator has detected holes in the read data 7925 prior to that Data-In PDU, it MUST postpone issuing the SNACK of 7926 type DataACK until the holes are filled. An initiator also MUST 7927 NOT acknowledge the status for the task before those holes are 7928 filled. A status acknowledgement for a task that generated the 7929 Data-In PDUs is considered by the target as an implicit 7930 acknowledgement of the Data-In PDUs if such an acknowledgement was 7931 requested by the target. 7933 11.7.3. Flags (byte 1) 7935 The last SCSI Data packet sent from a target to an initiator for a 7936 SCSI command that completed successfully (with a status of GOOD, 7937 CONDITION MET, INTERMEDIATE or INTERMEDIATE CONDITION MET) may 7938 also optionally contain the Status for the data transfer. In this 7939 case, Sense Data cannot be sent together with the Command Status. 7940 If the command is completed with an error, then the response and 7941 sense data MUST be sent in a SCSI Response PDU (i.e., MUST NOT be 7942 sent in a SCSI Data packet). For Bidirectional commands, the 7943 status MUST be sent in a SCSI Response PDU. 7945 bit 2-4 - Reserved. 7947 bit 5-6 - used the same as in a SCSI Response. These bits are 7948 only valid when S is set to 1. For details see SNACK . 7950 bit 7 S (status)- set to indicate that the Command Status 7951 field contains status. If this bit is set to 1, the F bit 7952 MUST also be set to 1. 7954 The fields StatSN, Status, and Residual Count only have meaningful 7955 content if the S bit is set to 1 and their values are defined in 7956 SNACK . 7958 11.7.4. Target Transfer Tag and LUN 7960 On outgoing data, the Target Transfer Tag is provided to the 7961 target if the transfer is honoring an R2T. In this case, the 7962 Target Transfer Tag field is a replica of the Target Transfer Tag 7963 provided with the R2T. 7965 On incoming data, the Target Transfer Tag and LUN MUST be provided 7966 by the target if the A bit is set to 1; otherwise they are 7967 reserved. The Target Transfer Tag and LUN are copied by the 7968 initiator into the SNACK of type DataACK that it issues as a 7969 result of receiving a SCSI Data-in PDU with the A bit set to 1. 7971 The Target Transfer Tag values are not specified by this protocol 7972 except that the value 0xffffffff is reserved and means that the 7973 Target Transfer Tag is not supplied. If the Target Transfer Tag 7974 is provided, then the LUN field MUST hold a valid value and be 7975 consistent with whatever was specified with the command; 7976 otherwise, the LUN field is reserved. 7978 11.7.5. DataSN 7980 For input (read) or bidirectional Data-In PDUs, the DataSN is the 7981 input PDU number within the data transfer for the command 7982 identified by the Initiator Task Tag. 7984 R2T and Data-In PDUs, in the context of bidirectional commands, 7985 share the numbering sequence (see Section 4.2.2.4). 7987 For output (write) data PDUs, the DataSN is the Data-Out PDU 7988 number within the current output sequence. The current output 7989 sequence is either identified by the Initiator Task Tag (for 7990 unsolicited data) or is a data sequence generated for one R2T (for 7991 data solicited through R2T). 7993 11.7.6. Buffer Offset 7995 The Buffer Offset field contains the offset of this PDU payload 7996 data within the complete data transfer. The sum of the buffer 7997 offset and length should not exceed the expected transfer length 7998 for the command. 8000 The order of data PDUs within a sequence is determined by 8001 DataPDUInOrder. When set to Yes, it means that PDUs have to be in 8002 increasing Buffer Offset order and overlays are forbidden. 8004 The ordering between sequences is determined by 8005 DataSequenceInOrder. When set to Yes, it means that sequences have 8006 to be in increasing Buffer Offset order and overlays are 8007 forbidden. 8009 11.7.7. DataSegmentLength 8011 This is the data payload length of a SCSI Data-In or SCSI Data-Out 8012 PDU. The sending of 0 length data segments should be avoided, but 8013 initiators and targets MUST be able to properly receive 0 length 8014 data segments. 8016 The Data Segments of Data-in and Data-out PDUs SHOULD be filled to 8017 the integer number of 4 byte words (real payload) unless the F bit 8018 is set to 1. 8020 11.8. Ready To Transfer (R2T) 8022 Byte/ 0 | 1 | 2 | 3 | 8023 / | | | | 8024 |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 67| 8025 +---------------+---------------+---------------+--------------+ 8026 0|.|.| 0x31 |1| Reserved | 8027 +---------------+---------------+---------------+--------------+ 8028 4|TotalAHSLength | DataSegmentLength | 8029 +---------------+---------------+---------------+--------------+ 8030 8| LUN | 8031 + + 8032 12| | 8033 +---------------+---------------+---------------+--------------+ 8034 16| Initiator Task Tag | 8035 +---------------+---------------+---------------+--------------+ 8036 20| Target Transfer Tag | 8037 +---------------+---------------+---------------+--------------+ 8038 24| StatSN | 8039 +---------------+---------------+---------------+--------------+ 8040 28| ExpCmdSN | 8041 +---------------+---------------+---------------+--------------+ 8042 32| MaxCmdSN | 8043 +---------------+---------------+---------------+--------------+ 8044 36| R2TSN | 8045 +---------------+---------------+---------------+--------------+ 8046 40| Buffer Offset | 8047 +---------------+---------------+---------------+--------------+ 8048 44| Desired Data Transfer Length | 8049 +--------------------------------------------------------------+ 8050 48| Header-Digest (Optional) | 8051 +---------------+---------------+---------------+--------------+ 8053 When an initiator has submitted a SCSI Command with data that 8054 passes from the initiator to the target (WRITE), the target may 8055 specify which blocks of data it is ready to receive. The target 8056 may request that the data blocks be delivered in whichever order 8057 is convenient for the target at that particular instant. This 8058 information is passed from the target to the initiator in the 8059 Ready To Transfer (R2T) PDU. 8061 In order to allow write operations without an explicit initial 8062 R2T, the initiator and target MUST have negotiated the key 8063 InitialR2T to No during Login. 8065 An R2T MAY be answered with one or more SCSI Data-out PDUs with a 8066 matching Target Transfer Tag. If an R2T is answered with a single 8067 Data-out PDU, the Buffer Offset in the Data PDU MUST be the same 8068 as the one specified by the R2T, and the data length of the Data 8069 PDU MUST be the same as the Desired Data Transfer Length specified 8070 in the R2T. If the R2T is answered with a sequence of Data PDUs, 8071 the Buffer Offset and Length MUST be within the range of those 8072 specified by R2T, and the last PDU MUST have the F bit set to 1. 8073 If the last PDU (marked with the F bit) is received before the 8074 Desired Data Transfer Length is transferred, a target MAY choose 8075 to Reject that PDU with "Protocol error" reason code. 8076 DataPDUInOrder governs the Data-Out PDU ordering. If 8077 DataPDUInOrder is set to Yes, the Buffer Offsets and Lengths for 8078 consecutive PDUs MUST form a continuous non-overlapping range and 8079 the PDUs MUST be sent in increasing offset order. 8081 The target may send several R2T PDUs. It, therefore, can have a 8082 number of pending data transfers. The number of outstanding R2T 8083 PDUs are limited by the value of the negotiated key 8084 MaxOutstandingR2T. Within a task, outstanding R2Ts MUST be 8085 fulfilled by the initiator in the order in which they were 8086 received. 8088 R2T PDUs MAY also be used to recover Data Out PDUs. Such an R2T 8089 (Recovery-R2T) is generated by a target upon detecting the loss of 8090 one or more Data-Out PDUs due to: 8092 - Digest error 8094 - Sequence error 8096 - Sequence reception timeout 8098 A Recovery-R2T carries the next unused R2TSN, but requests part of 8099 or the entire data burst that an earlier R2T (with a lower R2TSN) 8100 had already requested. 8102 DataSequenceInOrder governs the buffer offset ordering in 8103 consecutive R2Ts. If DataSequenceInOrder is Yes, then consecutive 8104 R2Ts MUST refer to continuous non-overlapping ranges except for 8105 Recovery-R2Ts. 8107 11.8.1. TotalAHSLength and DataSegmentLength 8109 For this PDU TotalAHSLength and DataSegmentLength MUST be 0. 8111 11.8.2. R2TSN 8113 R2TSN is the R2T PDU input PDU number within the command 8114 identified by the Initiator Task Tag. 8116 For bidirectional commands R2T and Data-In PDUs share the input 8117 PDU numbering sequence (see Section 4.2.2.4). 8119 11.8.3. StatSN 8121 The StatSN field will contain the next StatSN. The StatSN for this 8122 connection is not advanced after this PDU is sent. 8124 11.8.4. Desired Data Transfer Length and Buffer Offset 8126 The target specifies how many bytes it wants the initiator to send 8127 because of this R2T PDU. The target may request the data from the 8128 initiator in several chunks, not necessarily in the original order 8129 of the data. The target, therefore, also specifies a Buffer Offset 8130 that indicates the point at which the data transfer should begin, 8131 relative to the beginning of the total data transfer. The Desired 8132 Data Transfer Length MUST NOT be 0 and MUST NOT exceed 8133 MaxBurstLength. 8135 11.8.5. Target Transfer Tag 8137 The target assigns its own tag to each R2T request that it sends 8138 to the initiator. This tag can be used by the target to easily 8139 identify the data it receives. The Target Transfer Tag and LUN are 8140 copied in the outgoing data PDUs and are only used by the target. 8141 There is no protocol rule about the Target Transfer Tag except 8142 that the value 0xffffffff is reserved and MUST NOT be sent by a 8143 target in an R2T. 8145 11.9. Asynchronous Message 8147 An Asynchronous Message may be sent from the target to the 8148 initiator without correspondence to a particular command. The 8149 target specifies the reason for the event and sense data. 8151 Byte/ 0 | 1 | 2 | 3 | 8152 / | | | | 8153 |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 67| 8154 +---------------+---------------+---------------+--------------+ 8155 0|.|.| 0x32 |1| Reserved | 8156 +---------------+---------------+---------------+--------------+ 8157 4|TotalAHSLength | DataSegmentLength | 8158 +---------------+---------------+---------------+--------------+ 8159 8| LUN or Reserved | 8160 + + 8161 12| | 8162 +---------------+---------------+---------------+--------------+ 8163 16| 0xffffffff | 8164 +---------------+---------------+---------------+--------------+ 8165 20| Reserved | 8166 +---------------+---------------+---------------+--------------+ 8167 24| StatSN | 8168 +---------------+---------------+---------------+--------------+ 8169 28| ExpCmdSN | 8170 +---------------+---------------+---------------+--------------+ 8171 32| MaxCmdSN | 8172 +---------------+---------------+---------------+--------------+ 8173 36| AsyncEvent | AsyncVCode | Parameter1 or Reserved | 8174 +---------------+---------------+---------------+--------------+ 8175 40| Parameter2 or Reserved | Parameter3 or Reserved | 8176 +---------------+---------------+---------------+--------------+ 8177 44| Reserved | 8178 +---------------+---------------+---------------+--------------+ 8179 48| Header-Digest (Optional) | 8180 +---------------+---------------+---------------+--------------+ 8181 / DataSegment - Sense Data and iSCSI Event Data / 8182 +/ / 8183 +---------------+---------------+---------------+--------------+ 8184 | Data-Digest (Optional) | 8185 +---------------+---------------+---------------+--------------+ 8187 Some Asynchronous Messages are strictly related to iSCSI while 8188 others are related to SCSI [SAM2]. 8190 StatSN counts this PDU as an acknowledgeable event (StatSN is 8191 advanced), which allows for initiator and target state 8192 synchronization. 8194 11.9.1. AsyncEvent 8196 The codes used for iSCSI Asynchronous Messages (events) are: 8198 0 (SCSI_ASYNC) - a SCSI Asynchronous Event is reported in the 8199 sense data. Sense Data that accompanies the report, in the 8200 data segment, identifies the condition. The sending of a 8201 SCSI Event (Asynchronous Event Reporting in SCSI 8202 terminology) is dependent on the target support for SCSI 8203 asynchronous event reporting (see [SAM2]) as indicated in 8204 the standard INQUIRY data (see [SPC3]). Its use may be 8205 enabled by parameters in the SCSI Control mode page (see 8206 [SPC3]). 8208 1 (REQUEST_LOGOUT) - target requests Logout. This Async 8209 Message MUST be sent on the same connection as the one 8210 requesting to be logged out. The initiator MUST honor this 8211 request by issuing a Logout as early as possible, but no 8212 later than Parameter3 seconds. Initiator MUST send a 8213 Logout with a reason code of "Close the connection" OR 8214 "Close the session" to close all the connections. Once this 8215 message is received, the initiator SHOULD NOT issue new 8216 iSCSI commands on the connection to be logged out. The 8217 target MAY reject any new I/O requests that it receives 8218 after this Message with the reason code "Waiting for 8219 Logout". If the initiator does not Logout in Parameter3 8220 seconds, the target should send an Async PDU with iSCSI 8221 event code "Dropped the connection" if possible, or simply 8222 terminate the transport connection. Parameter1 and 8223 Parameter2 are reserved. 8225 2 (CONNECTION_DROP) - target indicates it will drop the 8226 connection. 8228 The Parameter1 field indicates the CID of the connection 8229 going to be dropped. 8231 The Parameter2 field (Time2Wait) indicates, in seconds, the 8232 minimum time to wait before attempting to reconnect or 8233 reassign. 8235 The Parameter3 field (Time2Retain) indicates the maximum 8236 time allowed to reassign commands after the initial wait (in 8237 Parameter2). 8239 If the initiator does not attempt to reconnect and/or 8240 reassign the outstanding commands within the time specified 8241 by Parameter3, or if Parameter3 is 0, the target will 8242 terminate all outstanding commands on this connection. In 8243 this case, no other responses should be expected from the 8244 target for the outstanding commands on this connection. 8246 A value of 0 for Parameter2 indicates that reconnect can be 8247 attempted immediately. 8249 3 (SESSION_DROP) - target indicates it will drop all the 8250 connections of this session. 8252 Parameter1 field is reserved. 8254 The Parameter2 field (Time2Wait) indicates, in seconds, the 8255 minimum time to wait before attempting to reconnect. 8256 The Parameter3 field (Time2Retain) indicates the maximum 8257 time allowed to reassign commands after the initial wait (in 8258 Parameter2). 8260 If the initiator does not attempt to reconnect and/or 8261 reassign the outstanding commands within the time specified 8262 by Parameter3, or if Parameter3 is 0, the session is 8263 terminated. In this case, the target will terminate all 8264 outstanding commands in this session; no other responses 8265 should be expected from the target for the outstanding 8266 commands in this session. A value of 0 for Parameter2 8267 indicates that reconnect can be attempted immediately. 8269 4 (RENEGOTIATE) - target requests parameter negotiation on 8270 this connection. The initiator MUST honor this request by 8271 issuing a Text Request (that can be empty) on the same 8272 connection as early as possible, but no later than 8273 Parameter3 seconds, unless a Text Request is already pending 8274 on the connection, or by issuing a Logout Request. If the 8275 initiator does not issue a Text Request the target may 8276 reissue the Asynchronous Message requesting parameter 8277 negotiation. 8279 5 (FAST_ABORT) - all active tasks for LU with a matching LUN 8280 field in the Async Message PDU are being terminated. The 8281 receiving initiator iSCSI layer MUST respond to this Message 8282 by taking the following steps in order. 8284 - Stop Data-Out transfers on that connection for all active 8285 TTTs for the affected LUN quoted in the Async Message 8286 PDU. 8287 - Acknowledge the StatSN of the Async Message PDU via a NOP- 8288 Out PDU with ITT=0xffffffff (i.e., non-ping flavor), 8289 while copying the LUN field from the Async Message to 8290 NOP-Out. 8292 This value of AsyncEvent however MUST NOT be used on an 8293 iSCSI session unless the new TaskReporting text key defined 8294 in Section 13.23 was negotiated to FastAbort on the session. 8296 255 - vendor-specific iSCSI Event. The AsyncVCode details the 8297 vendor code, and data MAY accompany the report. 8299 All other event codes are reserved. 8301 11.9.2. AsyncVCode 8303 AsyncVCode is a vendor specific detail code that is only valid if 8304 the AsyncEvent field indicates a vendor specific event. Otherwise, 8305 it is reserved. 8307 11.9.3. LUN 8309 The LUN field MUST be valid if AsyncEvent is 0. Otherwise, this 8310 field is reserved. 8312 11.9.4. Sense Data and iSCSI Event Data 8314 For a SCSI event, this data accompanies the report in the data 8315 segment and identifies the condition. 8317 For an iSCSI event, additional vendor-unique data MAY accompany 8318 the Async event. Initiators MAY ignore the data when not 8319 understood while processing the rest of the PDU. 8321 If the DataSegmentLength is not 0, the format of the DataSegment 8322 is as follows: 8324 Byte/ 0 | 1 | 2 | 3 | 8325 / | | | | 8326 |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 67| 8327 +---------------+---------------+---------------+--------------+ 8328 0|SenseLength | Sense Data | 8329 +---------------+---------------+---------------+--------------+ 8330 x/ Sense Data / 8331 +---------------+---------------+---------------+--------------+ 8332 y/ iSCSI Event Data / 8333 / / 8334 +---------------+---------------+---------------+--------------+ 8335 z| 8337 11.9.4.1. SenseLength 8339 This is the length of Sense Data. When the Sense Data field is 8340 empty (e.g., the event is not a SCSI event) SenseLength is 0. 8342 11.10. Text Request 8344 The Text Request is provided to allow for the exchange of 8345 information and for future extensions. It permits the initiator to 8346 inform a target of its capabilities or to request some special 8347 operations. 8349 Byte/ 0 | 1 | 2 | 3 | 8350 / | | | | 8351 |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 67| 8352 +---------------+---------------+---------------+--------------+ 8353 0|.|I| 0x04 |F|C| Reserved | 8354 +---------------+---------------+---------------+--------------+ 8355 4|TotalAHSLength | DataSegmentLength | 8356 +---------------+---------------+---------------+--------------+ 8357 8| LUN or Reserved | 8358 + + 8359 12| | 8360 +---------------+---------------+---------------+--------------+ 8361 16| Initiator Task Tag | 8362 +---------------+---------------+---------------+--------------+ 8363 20| Target Transfer Tag or 0xffffffff | 8364 +---------------+---------------+---------------+--------------+ 8365 24| CmdSN | 8366 +---------------+---------------+---------------+--------------+ 8367 28| ExpStatSN | 8368 +---------------+---------------+---------------+--------------+ 8369 32/ Reserved / 8370 +/ / 8371 +---------------+---------------+---------------+--------------+ 8372 48| Header-Digest (Optional) | 8373 +---------------+---------------+---------------+--------------+ 8374 / DataSegment (Text) / 8375 +/ / 8376 +---------------+---------------+---------------+--------------+ 8377 | Data-Digest (Optional) | 8378 +---------------+---------------+---------------+--------------+ 8380 An initiator MUST NOT have more than one outstanding Text Request 8381 on a connection at any given time. 8383 On a connection failure, an initiator must either explicitly abort 8384 any active allegiant text negotiation task or must cause such a 8385 task to be implicitly terminated by the target. 8387 11.10.1. F (Final) Bit 8389 When set to 1, indicates that this is the last or only text 8390 request in a sequence of Text Requests; otherwise, it indicates 8391 that more Text Requests will follow. 8393 11.10.2. C (Continue) Bit 8395 When set to 1, indicates that the text (set of key=value pairs) in 8396 this Text Request is not complete (it will be continued on 8397 subsequent Text Requests); otherwise, it indicates that this Text 8398 Request ends a set of key=value pairs. A Text Request with the C 8399 bit set to 1 MUST have the F bit set to 0. 8401 11.10.3. Initiator Task Tag 8403 The initiator assigned identifier for this Text Request. If the 8404 command is sent as part of a sequence of text requests and 8405 responses, the Initiator Task Tag MUST be the same for all the 8406 requests within the sequence (similar to linked SCSI commands). 8407 The I bit for all requests in a sequence also MUST be the same. 8409 11.10.4. Target Transfer Tag 8411 When the Target Transfer Tag is set to the reserved value 8412 0xffffffff, it tells the target that this is a new request and the 8413 target resets any internal state associated with the Initiator 8414 Task Tag (resets the current negotiation state). 8416 The target sets the Target Transfer Tag in a text response to a 8417 value other than the reserved value 0xffffffff whenever it 8418 indicates that it has more data to send or more operations to 8419 perform that are associated with the specified Initiator Task Tag. 8420 It MUST do so whenever it sets the F bit to 0 in the response. By 8421 copying the Target Transfer Tag from the response to the next Text 8422 Request, the initiator tells the target to continue the operation 8423 for the specific Initiator Task Tag. The initiator MUST ignore the 8424 Target Transfer Tag in the Text Response when the F bit is set to 8425 1. 8427 This mechanism allows the initiator and target to transfer a large 8428 amount of textual data over a sequence of text-command/text- 8429 response exchanges, or to perform extended negotiation sequences. 8431 If the Target Transfer Tag is not 0xffffffff, the LUN field MUST 8432 be sent by the target in the Text Response. 8434 A target MAY reset its internal negotiation state if an exchange 8435 is stalled by the initiator for a long time or if it is running 8436 out of resources. 8438 Long text responses are handled as in the following example: 8440 I->T Text SendTargets=All (F=1,TTT=0xffffffff) 8442 T->I Text (F=0,TTT=0x12345678) 8444 I->T Text (F=1, TTT=0x12345678) 8446 T->I Text (F=0, TTT=0x12345678) 8448 I->T Text (F=1, TTT=0x12345678) 8450 ... 8452 T->I Text (F=1, TTT=0xffffffff) 8454 11.10.5. Text 8456 The data lengths of a text request MUST NOT exceed the iSCSI 8457 target MaxRecvDataSegmentLength (a per connection and per 8458 direction negotiated parameter). The text format is specified in 8459 Section 6.2. 8461 Section 12 and Section 13 list some basic Text key=value pairs, 8462 some of which can be used in Login Request/Response and some in 8463 Text Request/Response. 8465 A key=value pair can span Text request or response boundaries. A 8466 key=value pair can start in one PDU and continue on the next. In 8468 other words the end of a PDU does not necessarily signal the end 8469 of a key=value pair. 8471 The target responds by sending its response back to the initiator. 8472 The response text format is similar to the request text format. 8473 The text response MAY refer to key=value pairs presented in an 8474 earlier text request and the text in the request may refer to 8475 earlier responses. 8477 Section 6.2 details the rules for the Text Requests and Responses. 8479 Text operations are usually meant for parameter 8480 setting/negotiations, but can also be used to perform some long 8481 lasting operations. 8483 Text operations that take a long time should be placed in their 8484 own Text request. 8486 11.11. Text Response 8488 The Text Response PDU contains the target's responses to the 8489 initiator's Text request. The format of the Text field matches 8490 that of the Text request. 8492 Byte/ 0 | 1 | 2 | 3 | 8493 / | | | | 8494 |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 67| 8495 +---------------+---------------+---------------+--------------+ 8496 0|.|.| 0x24 |F|C| Reserved | 8497 +---------------+---------------+---------------+--------------+ 8498 4|TotalAHSLength | DataSegmentLength | 8499 +---------------+---------------+---------------+--------------+ 8500 8| LUN or Reserved | 8501 + + 8502 12| | 8503 +---------------+---------------+---------------+--------------+ 8504 16| Initiator Task Tag | 8505 +---------------+---------------+---------------+--------------+ 8506 20| Target Transfer Tag or 0xffffffff | 8507 +---------------+---------------+---------------+--------------+ 8508 24| StatSN | 8509 +---------------+---------------+---------------+--------------+ 8510 28| ExpCmdSN | 8511 +---------------+---------------+---------------+--------------+ 8512 32| MaxCmdSN | 8513 +---------------+---------------+---------------+--------------+ 8514 36/ Reserved / 8515 +/ / 8516 +---------------+---------------+---------------+--------------+ 8517 48| Header-Digest (Optional) | 8518 +---------------+---------------+---------------+--------------+ 8519 / DataSegment (Text) / 8520 +/ / 8521 +---------------+---------------+---------------+--------------+ 8522 | Data-Digest (Optional) | 8523 +---------------+---------------+---------------+--------------+ 8525 11.11.1. F (Final) Bit 8527 When set to 1, in response to a Text Request with the Final bit 8528 set to 1, the F bit indicates that the target has finished the 8529 whole operation. Otherwise, if set to 0 in response to a Text 8530 Request with the Final Bit set to 1, it indicates that the target 8531 has more work to do (invites a follow-on text request). A Text 8532 Response with the F bit set to 1 in response to a Text Request 8533 with the F bit set to 0 is a protocol error. 8535 A Text Response with the F bit set to 1 MUST NOT contain key=value 8536 pairs that may require additional answers from the initiator. 8538 A Text Response with the F bit set to 1 MUST have a Target 8539 Transfer Tag field set to the reserved value of 0xffffffff. 8541 A Text Response with the F bit set to 0 MUST have a Target 8542 Transfer Tag field set to a value other than the reserved 8543 0xffffffff. 8545 11.11.2. C (Continue) Bit 8547 When set to 1, indicates that the text (set of key=value pairs) in 8548 this Text Response is not complete (it will be continued on 8549 subsequent Text Responses); otherwise, it indicates that this Text 8550 Response ends a set of key=value pairs. A Text Response with the C 8551 bit set to 1 MUST have the F bit set to 0. 8553 11.11.3. Initiator Task Tag 8555 The Initiator Task Tag matches the tag used in the initial Text 8556 Request. 8558 11.11.4. Target Transfer Tag 8560 When a target has more work to do (e.g., cannot transfer all the 8561 remaining text data in a single Text Response or has to continue 8562 the negotiation) and has enough resources to proceed, it MUST set 8563 the Target Transfer Tag to a value other than the reserved value 8564 of 0xffffffff. Otherwise, the Target Transfer Tag MUST be set to 8565 0xffffffff. 8567 When the Target Transfer Tag is not 0xffffffff, the LUN field may 8568 be significant. 8570 The initiator MUST copy the Target Transfer Tag and LUN in its 8571 next request to indicate that it wants the rest of the data. 8573 When the target receives a Text Request with the Target Transfer 8574 Tag set to the reserved value of 0xffffffff, it resets its 8575 internal information (resets state) associated with the given 8576 Initiator Task Tag (restarts the negotiation). 8578 When a target cannot finish the operation in a single Text 8579 Response, and does not have enough resources to continue, it 8580 rejects the Text Request with the appropriate Reject code. 8582 A target may reset its internal state associated with an Initiator 8583 Task Tag (the current negotiation state), state expressed through 8584 the Target Transfer Tag if the initiator fails to continue the 8585 exchange for some time. The target may reject subsequent Text 8586 Requests with the Target Transfer Tag set to the "stale" value. 8588 11.11.5. StatSN 8590 The target StatSN variable is advanced by each Text Response sent. 8592 11.11.6. Text Response Data 8594 The data lengths of a text response MUST NOT exceed the iSCSI 8595 initiator MaxRecvDataSegmentLength (a per connection and per 8596 direction negotiated parameter). 8598 The text in the Text Response Data is governed by the same rules 8599 as the text in the Text Request Data (see Section 11.11.2). 8601 Although the initiator is the requesting party and controls the 8602 request-response initiation and termination, the target can offer 8603 key=value pairs of its own as part of a sequence and not only in 8604 response to the initiator. 8606 11.12. Login Request 8608 After establishing a TCP connection between an initiator and a 8609 target, the initiator MUST start a Login Phase to gain further 8610 access to the target's resources. 8612 The Login Phase (see Section 6.3) consists of a sequence of Login 8613 requests and responses that carry the same Initiator Task Tag. 8615 Login requests are always considered as immediate. 8617 Byte/ 0 | 1 | 2 | 3 | 8618 / | | | | 8619 |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 67| 8620 +---------------+---------------+---------------+--------------+ 8621 0|.|1| 0x03 |T|C|.|.|CSG|NSG| Version-max | Version-min | 8622 +---------------+---------------+---------------+--------------+ 8623 4|TotalAHSLength | DataSegmentLength | 8624 +---------------+---------------+---------------+--------------+ 8625 8| ISID | 8626 + +---------------+--------------+ 8627 12| | TSIH | 8628 +---------------+---------------+---------------+--------------+ 8629 16| Initiator Task Tag | 8630 +---------------+---------------+---------------+--------------+ 8631 20| CID | Reserved | 8632 +---------------+---------------+---------------+--------------+ 8633 24| CmdSN | 8634 +---------------+---------------+---------------+--------------+ 8635 28| ExpStatSN or Reserved | 8636 +---------------+---------------+---------------+--------------+ 8637 32| Reserved | 8638 +---------------+---------------+---------------+--------------+ 8639 36| Reserved | 8640 +---------------+---------------+---------------+--------------+ 8641 40/ Reserved / 8642 +/ / 8643 +---------------+---------------+---------------+--------------+ 8644 48/ DataSegment - Login Parameters in Text request Format / 8645 +/ / 8646 +---------------+---------------+---------------+--------------+ 8648 11.12.1. T (Transit) Bit 8650 If set to 1, indicates that the initiator is ready to transit to 8651 the next stage. 8653 If the T bit is set to 1 and NSG is FullFeaturePhase, then this 8654 also indicates that the initiator is ready for the Final Login 8655 Response (see Section 6.3). 8657 11.12.2. C (Continue) Bit 8659 When set to 1, this bit indicates that the text (set of key=value 8660 pairs) in this Login Request is not complete (it will be continued 8661 on subsequent Login Requests); otherwise, it indicates that this 8662 Login Request ends a set of key=value pairs. A Login Request with 8663 the C bit set to 1 MUST have the T bit set to 0. 8665 11.12.3. CSG and NSG 8667 Through these fields, Current Stage (CSG) and Next Stage (NSG), 8668 the Login negotiation requests and responses are associated with a 8669 specific stage in the session (SecurityNegotiation, 8670 LoginOperationalNegotiation, FullFeaturePhase) and may indicate 8671 the next stage to which they want to move (see Section 6.3). The 8672 next stage value is only valid when the T bit is 1; otherwise, it 8673 is reserved. 8675 The stage codes are: 8677 - 0 - SecurityNegotiation 8679 - 1 - LoginOperationalNegotiation 8681 - 3 - FullFeaturePhase 8683 All other codes are reserved. 8685 11.12.4. Version 8687 The version number of the current draft is 0x00. As such, all 8688 devices MUST carry version 0x00 for both Version-min and Version- 8689 max. 8691 11.12.4.1. Version-max 8693 Maximum Version number supported. 8695 All Login requests within the Login Phase MUST carry the same 8696 Version-max. 8698 The target MUST use the value presented with the first login 8699 request. 8701 11.12.4.2. Version-min 8703 All Login requests within the Login Phase MUST carry the same 8704 Version-min. The target MUST use the value presented with the 8705 first login request. 8707 11.12.5. ISID 8709 This is an initiator-defined component of the session identifier 8710 and is structured as follows (see Section 10.1.1 for details): 8712 Byte/ 0 | 1 | 2 | 3 | 8713 / | | | | 8714 |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 67| 8715 +---------------+---------------+---------------+--------------+ 8716 8| T | A | B | C | 8717 +---------------+---------------+---------------+--------------+ 8718 12| D | 8719 +---------------+---------------+ 8721 The T field identifies the format and usage of A, B, C, and D as 8722 indicated below: 8724 T 8726 00b OUI-Format 8728 A&B are a 22 bit OUI 8730 (the I/G & U/L bits are omitted) 8732 C&D 24 bit qualifier 8734 01b EN - Format (IANA Enterprise Number) 8736 A - Reserved 8738 B&C EN (IANA Enterprise Number) 8740 D - Qualifier 8742 10b "Random" 8744 A - Reserved 8746 B&C Random 8748 D - Qualifier 8750 11b A,B,C&D Reserved 8752 For the T field values 00b and 01b, a combination of A and B (for 8753 00b) or B and C (for 01b) identifies the vendor or organization 8754 whose component (software or hardware) generates this ISID. A 8755 vendor or organization with one or more OUIs, or one or more 8756 Enterprise Numbers, MUST use at least one of these numbers and 8757 select the appropriate value for the T field when its components 8758 generate ISIDs. An OUI or EN MUST be set in the corresponding 8759 fields in network byte order (byte big-endian). 8761 If the T field is 10b, B and C are set to a random 24-bit unsigned 8762 integer value in network byte order (byte big-endian). See 8763 [RFC3721] for how this affects the principle of "conservative 8764 reuse". 8766 The Qualifier field is a 16 or 24-bit unsigned integer value that 8767 provides a range of possible values for the ISID within the 8768 selected namespace. It may be set to any value within the 8769 constraints specified in the iSCSI protocol (see Section 4.4.3 and 8770 Section 10.1.1). 8772 The T field value of 11b is reserved. 8774 If the ISID is derived from something assigned to a hardware 8775 adapter or interface by a vendor, as a preset default value, it 8776 MUST be configurable to a value assigned according to the SCSI 8777 port behavior desired by the system in which it is installed (see 8778 Section 10.1.1 and Section 10.1.2). The resultant ISID MUST also 8779 be persistent over power cycles, reboot, card swap, etc. 8781 11.12.6. TSIH 8783 TSIH must be set in the first Login Request. The reserved value 0 8784 MUST be used on the first connection for a new session. Otherwise, 8785 the TSIH sent by the target at the conclusion of the successful 8786 login of the first connection for this session MUST be used. The 8787 TSIH identifies to the target the associated existing session for 8788 this new connection. 8790 All Login requests within a Login Phase MUST carry the same TSIH. 8792 The target MUST check the value presented with the first login 8793 request and act as specified in Section 5.3.1. 8795 11.12.7. Connection ID - CID 8797 A unique ID for this connection within the session. 8799 All Login requests within the Login Phase MUST carry the same CID. 8801 The target MUST use the value presented with the first login 8802 request. 8804 A Login request with a non-zero TSIH and a CID equal to that of an 8805 existing connection implies a logout of the connection followed by 8806 a Login (see Section 6.3.4). For the details of the implicit 8807 Logout Request, see Section 11.14. 8809 11.12.8. CmdSN 8811 CmdSN is either the initial command sequence number of a session 8812 (for the first Login request of a session - the "leading" login), 8813 or the command sequence number in the command stream if the login 8814 is for a new connection in an existing session. 8816 Examples: 8818 - Login on a leading connection - if the leading login carries 8819 the CmdSN 123, all other login requests in the same login 8820 phase carry the CmdSN 123 and the first non-immediate 8821 command in FullFeaturePhase also carries the CmdSN 123. 8823 - Login on other than a leading connection - if the current 8824 CmdSN at the time the first login on the connection is 8825 issued is 500, then that PDU carries CmdSN=500. Subsequent 8826 login requests that are needed to complete this login phase 8827 may carry a CmdSN higher than 500 if non-immediate requests 8828 that were issued on other connections in the same session 8829 advance CmdSN. 8831 If the login request is a leading login request, the target MUST 8832 use the value presented in CmdSN as the target value for ExpCmdSN. 8834 11.12.9. ExpStatSN 8836 For the first Login Request on a connection this is ExpStatSN for 8837 the old connection and this field is only valid if the Login 8838 request restarts a connection (see Section 6.3.4). 8840 For subsequent Login Requests it is used to acknowledge the Login 8841 Responses with their increasing StatSN values. 8843 11.12.10. Login Parameters 8845 The initiator MUST provide some basic parameters in order to 8846 enable the target to determine if the initiator may use the 8847 target's resources and the initial text parameters for the 8848 security exchange. 8850 All the rules specified in Section 11.10.5 for text requests also 8851 hold for login requests. Keys and their explanations are listed 8852 in Section 12 (security negotiation keys) and Section 13 8853 (operational parameter negotiation keys). All keys in Section 13, 8854 except for the X extension formats, MUST be supported by iSCSI 8855 initiators and targets. Keys in Section 12 only need to be 8856 supported when the function to which they refer is mandatory to 8857 implement. 8859 11.13. Login Response 8861 The Login Response indicates the progress and/or end of the Login 8862 Phase. 8864 Byte/ 0 | 1 | 2 | 3 | 8865 / | | | | 8866 |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 67| 8867 +---------------+---------------+---------------+--------------+ 8868 0|.|.| 0x23 |T|C|.|.|CSG|NSG| Version-max |Version-active| 8869 +---------------+---------------+---------------+--------------+ 8870 4|TotalAHSLength | DataSegmentLength | 8871 +---------------+---------------+---------------+--------------+ 8872 8| ISID | 8873 + +---------------+--------------+ 8874 12| | TSIH | 8875 +---------------+---------------+---------------+--------------+ 8876 16| Initiator Task Tag | 8877 +---------------+---------------+---------------+--------------+ 8878 20| Reserved | 8879 +---------------+---------------+---------------+--------------+ 8880 24| StatSN | 8881 +---------------+---------------+---------------+--------------+ 8882 28| ExpCmdSN | 8883 +---------------+---------------+---------------+--------------+ 8884 32| MaxCmdSN | 8885 +---------------+---------------+---------------+--------------+ 8886 36| Status-Class | Status-Detail | Reserved | 8887 +---------------+---------------+---------------+--------------+ 8888 40/ Reserved / 8889 +/ / 8890 +---------------+---------------+---------------+--------------+ 8891 48/ DataSegment - Login Parameters in Text request Format / 8892 +/ / 8893 +---------------+---------------+---------------+--------------+ 8895 11.13.1. Version-max 8897 This is the highest version number supported by the target. 8899 All Login responses within the Login Phase MUST carry the same 8900 Version-max. 8902 The initiator MUST use the value presented as a response to the 8903 first login request. 8905 11.13.2. Version-active 8907 Indicates the highest version supported by the target and 8908 initiator. If the target does not support a version within the 8909 range specified by the initiator, the target rejects the login and 8910 this field indicates the lowest version supported by the target. 8912 All Login responses within the Login Phase MUST carry the same 8913 Version-active. 8915 The initiator MUST use the value presented as a response to the 8916 first login request. 8918 11.13.3. TSIH 8920 The TSIH is the target assigned session identifying handle. Its 8921 internal format and content are not defined by this protocol 8922 except for the value 0 that is reserved. With the exception of the 8923 Login Final-Response in a new session, this field should be set to 8924 the TSIH provided by the initiator in the Login Request. For a 8925 new session, the target MUST generate a non-zero TSIH and ONLY 8926 return it in the Login Final-Response (see Section 6.3). 8928 11.13.4. StatSN 8930 For the first Login Response (the response to the first Login 8931 Request), this is the starting status Sequence Number for the 8932 connection. The next response of any kind, including the next 8933 login response, if any, in the same Login Phase, will carry this 8934 number + 1. This field is only valid if the Status-Class is 0. 8936 11.13.5. Status-Class and Status-Detail 8938 The Status returned in a Login Response indicates the execution 8939 status of the Login Phase. The status includes: 8941 Status-Class 8943 Status-Detail 8945 0 Status-Class indicates success. 8947 A non-zero Status-Class indicates an exception. In this case, 8948 Status-Class is sufficient for a simple initiator to use when 8949 handling exceptions, without having to look at the Status-Detail. 8950 The Status-Detail allows finer-grained exception handling for more 8951 sophisticated initiators and for better information for logging. 8953 The status classes are as follows: 8955 0 - Success - indicates that the iSCSI target successfully 8956 received, understood, and accepted the request. The 8957 numbering fields (StatSN, ExpCmdSN, MaxCmdSN) are only valid 8958 if Status-Class is 0. 8960 1 - Redirection - indicates that the initiator must take 8961 further action to complete the request. This is usually due 8962 to the target moving to a different address. All of the 8963 redirection status class responses MUST return one or more 8964 text key parameters of the type "TargetAddress", which 8965 indicates the target's new address. A redirection response 8966 MAY be issued by a target prior or after completing a 8967 security negotiation if a security negotiation is required. 8968 A redirection SHOULD be accepted by an initiator even 8969 without having the target complete a security negotiation if 8970 any security negotiation is required, and MUST be accepted 8971 by the initiator after the completion of the security 8972 negotiation if any security negotiation is required. 8974 2 - Initiator Error (not a format error) - indicates that the 8975 initiator most likely caused the error. This MAY be due to a 8976 request for a resource for which the initiator does not have 8977 permission. The request should not be tried again. 8979 3 - Target Error - indicates that the target sees no errors in 8980 the initiator's login request, but is currently incapable of 8981 fulfilling the request. The initiator may re-try the same 8982 login request later. 8984 The table below shows all of the currently allocated status codes. 8985 The codes are in hexadecimal; the first byte is the status class 8986 and the second byte is the status detail. 8988 ----------------------------------------------------------------- 8989 Status | Code | Description 8990 |(hex) | 8991 ----------------------------------------------------------------- 8992 Success | 0000 | Login is proceeding OK (*1). 8993 ----------------------------------------------------------------- 8994 Target moved | 0101 | The requested iSCSI Target Name (ITN) 8995 temporarily | | has temporarily moved 8996 | | to the address provided. 8997 ----------------------------------------------------------------- 8998 Target moved | 0102 | The requested ITN has permanently moved 8999 permanently | | to the address provided. 9000 ----------------------------------------------------------------- 9001 Initiator | 0200 | Miscellaneous iSCSI initiator 9002 error | | errors. 9003 ---------------------------------------------------------------- 9004 Authentication| 0201 | The initiator could not be 9005 failure | | successfully authenticated or target 9006 | | authentication is not supported. 9007 ----------------------------------------------------------------- 9008 Authorization | 0202 | The initiator is not allowed access 9009 failure | | to the given target. 9010 ----------------------------------------------------------------- 9011 Not found | 0203 | The requested ITN does not 9012 | | exist at this address. 9013 ----------------------------------------------------------------- 9014 Target removed| 0204 | The requested ITN has been removed and 9015 | | no forwarding address is provided. 9016 ----------------------------------------------------------------- 9017 Unsupported | 0205 | The requested iSCSI version range is 9018 version | | not supported by the target. 9019 ----------------------------------------------------------------- 9020 Too many | 0206 | Too many connections on this SSID. 9021 connections | | 9022 ----------------------------------------------------------------- 9023 Missing | 0207 | Missing parameters (e.g., iSCSI 9024 parameter | | Initiator and/or Target Name). 9025 ----------------------------------------------------------------- 9026 Can't include | 0208 | Target does not support session 9027 in session | | spanning to this connection (address). 9028 ----------------------------------------------------------------- 9029 Session type | 0209 | Target does not support this type of 9030 not supported | | of session or not from this Initiator. 9031 ----------------------------------------------------------------- 9032 Session does | 020a | Attempt to add a connection 9033 not exist | | to a non-existent session. 9034 ----------------------------------------------------------------- 9035 Invalid during| 020b | Invalid Request type during Login. 9036 login | | 9037 ----------------------------------------------------------------- 9038 Target error | 0300 | Target hardware or software error. 9039 ----------------------------------------------------------------- 9040 Service | 0301 | The iSCSI service or target is not 9041 unavailable | | currently operational. 9042 ----------------------------------------------------------------- 9043 Out of | 0302 | The target has insufficient session, 9044 resources | | connection, or other resources. 9045 ----------------------------------------------------------------- 9047 (*1)If the response T bit is 1 in both the request and the 9048 matching response, and the NSG is FullFeaturePhase in both the 9049 request and the matching response, the Login Phase is finished and 9050 the initiator may proceed to issue SCSI commands. 9052 If the Status Class is not 0, the initiator and target MUST close 9053 the TCP connection. 9055 If the target wishes to reject the login request for more than one 9056 reason, it should return the primary reason for the rejection. 9058 11.13.6. T (Transit) bit 9060 The T bit is set to 1 as an indicator of the end of the stage. If 9061 the T bit is set to 1 and NSG is FullFeaturePhase, then this is 9062 also the Final Login Response (see Section 6.3). A T bit of 0 9063 indicates a "partial" response, which means "more negotiation 9064 needed". 9066 A login response with a T bit set to 1 MUST NOT contain key=value 9067 pairs that may require additional answers from the initiator 9068 within the same stage. 9070 If the status class is 0, the T bit MUST NOT be set to 1 if the T 9071 bit in the request was set to 0. 9073 11.13.7. C (Continue) Bit 9075 When set to 1, indicates that the text (set of key=value pairs) in 9076 this Login Response is not complete (it will be continued on 9077 subsequent Login Responses); otherwise, it indicates that this 9078 Login Response ends a set of key=value pairs. A Login Response 9079 with the C bit set to 1 MUST have the T bit set to 0. 9081 11.13.8. Login Parameters 9083 The target MUST provide some basic parameters in order to enable 9084 the initiator to determine if it is connected to the correct port 9085 and the initial text parameters for the security exchange. 9087 All the rules specified in Section 11.11.6 for text responses also 9088 hold for login responses. Keys and their explanations are listed 9089 in Section 12(security negotiation keys) and Section 13 9090 (operational parameter negotiation keys). All keys in Section 13, 9091 except for the X extension formats, MUST be supported by iSCSI 9092 initiators and targets. Keys in Section 12, only need to be 9093 supported when the function to which they refer is mandatory to 9094 implement. 9096 11.14. Logout Request 9098 The Logout request is used to perform a controlled closing of a 9099 connection. 9101 An initiator MAY use a logout request to remove a connection from 9102 a session or to close an entire session. 9104 After sending the Logout request PDU, an initiator MUST NOT send 9105 any new iSCSI requests on the closing connection. If the Logout 9106 request is intended to close the session, new iSCSI requests MUST 9107 NOT be sent on any of the connections participating in the 9108 session. 9110 When receiving a Logout request with the reason code of "close the 9111 connection" or "close the session", the target MUST terminate all 9112 pending commands, whether acknowledged via ExpCmdSN or not, on 9113 that connection or session respectively. 9115 When receiving a Logout request with the reason code "remove 9116 connection for recovery", the target MUST discard all requests not 9117 yet acknowledged via ExpCmdSN that were issued on the specified 9118 connection, and suspend all data/status/R2T transfers on behalf of 9119 pending commands on the specified connection. 9121 The target then issues the Logout response and half-closes the TCP 9122 connection (sends FIN). After receiving the Logout response and 9123 attempting to receive the FIN (if still possible), the initiator 9124 MUST completely close the logging-out connection. For the 9125 terminated commands, no additional responses should be expected. 9127 A Logout for a CID may be performed on a different transport 9128 connection when the TCP connection for the CID has already been 9129 terminated. In such a case, only a logical "closing" of the iSCSI 9130 connection for the CID is implied with a Logout. 9132 All commands that were not terminated or not completed (with 9133 status) and acknowledged when the connection is closed completely 9134 can be reassigned to a new connection if the target supports 9135 connection recovery. 9137 If an initiator intends to start recovery for a failing 9138 connection, it MUST use the Logout request to "clean-up" the 9139 target end of a failing connection and enable recovery to start, 9140 or the Login request with a non-zero TSIH and the same CID on a 9141 new connection for the same effect. In sessions with a single 9142 connection, the connection can be closed and then a new connection 9143 reopened. A connection reinstatement login can be used for 9144 recovery (see Section 6.3.4). 9146 A successful completion of a logout request with the reason code 9147 of "close the connection" or "remove the connection for recovery" 9148 results at the target in the discarding of unacknowledged commands 9149 received on the connection being logged out. These are commands 9150 that have arrived on the connection being logged out, but have not 9151 been delivered to SCSI because one or more commands with a smaller 9152 CmdSN has not been received by iSCSI. See Section 4.2.2.1. The 9153 resulting holes in the command sequence numbers will have to be 9154 handled by appropriate recovery (see Section 7) unless the session 9155 is also closed. 9157 The entire logout discussion in this Section is also applicable 9158 for an implicit Logout realized by way of a connection 9159 reinstatement or session reinstatement. When a Login Request 9160 performs an implicit Logout, the implicit Logout is performed as 9161 if having the reason codes specified below: 9163 Reason code Type of implicit Logout 9165 ------------------------------------------- 9167 0 session reinstatement 9169 1 connection reinstatement when the operational 9170 ErrorRecoveryLevel < 2 9172 2 connection reinstatement when the operational 9173 ErrorRecoveryLevel = 2 9175 Byte/ 0 | 1 | 2 | 3 | 9176 / | | | | 9177 |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 67| 9178 +---------------+---------------+---------------+--------------+ 9179 0|.|I| 0x06 |1| Reason Code | Reserved | 9180 +---------------+---------------+---------------+--------------+ 9181 4|TotalAHSLength | DataSegmentLength | 9182 +--------------------------------------------------------------+ 9183 8/ Reserved / 9184 +/ / 9185 +---------------+---------------+---------------+--------------+ 9186 16| Initiator Task Tag | 9187 +---------------+---------------+---------------+--------------+ 9188 20| CID or Reserved | Reserved | 9189 +---------------+---------------+---------------+--------------+ 9190 24| CmdSN | 9191 +---------------+---------------+---------------+--------------+ 9192 28| ExpStatSN | 9193 +---------------+---------------+---------------+--------------+ 9194 32/ Reserved / 9195 +/ / 9196 +---------------+---------------+---------------+--------------+ 9197 48| Header-Digest (Optional) | 9198 +---------------+---------------+---------------+--------------+ 9200 11.14.1. Reason Code 9202 Reason Code indicates the reason for Logout as follows: 9204 0 - close the session. All commands associated with the 9205 session (if any) are terminated. 9207 1 - close the connection. All commands associated with 9208 connection (if any) are terminated. 9210 2 - remove the connection for recovery. Connection is closed 9211 and all commands associated with it, if any, are to be 9212 prepared for a new allegiance. 9214 All other values are reserved. 9216 11.14.2. TotalAHSLength and DataSegmentLength 9218 For this PDU TotalAHSLength and DataSegmentLength MUST be 0. 9220 11.14.3. CID 9222 This is the connection ID of the connection to be closed 9223 (including closing the TCP stream). This field is only valid if 9224 the reason code is not "close the session". 9226 11.14.4. ExpStatSN 9228 This is the last ExpStatSN value for the connection to be closed. 9230 11.14.5. Implicit termination of tasks 9232 A target implicitly terminates the active tasks due to the iSCSI 9233 protocol in the following cases: 9235 a) When a connection is implicitly or explicitly logged out 9236 with the reason code of "Close the connection" and there 9237 are active tasks allegiant to that connection. 9239 b) When a connection fails and eventually the connection state 9240 times out (state transition M1 in Section 8.2.2) and there 9241 are active tasks allegiant to that connection. 9243 c) When a successful recovery Logout is performed while there 9244 are active tasks allegiant to that connection, and those 9245 tasks eventually time out after the Time2Wait and 9246 Time2Retain periods without allegiance reassignment. 9248 d) When a connection is implicitly or explicitly logged out 9249 with the reason code of "Close the session" and there are 9250 active tasks in that session. 9252 If the tasks terminated in any of the above cases are SCSI tasks, 9253 they must be internally terminated as if with CHECK CONDITION 9254 status. This status is only meaningful for appropriately handling 9256 the internal SCSI state and SCSI side effects with respect to 9257 ordering because this status is never communicated back as a 9258 terminating status to the initiator. However additional actions 9259 may have to be taken at SCSI level depending on the SCSI context 9260 as defined by the SCSI standards (e.g., queued commands and ACA, 9261 UA for the next command on the I_T nexus in cases a), b), and c), 9262 after the tasks are terminated, the target MUST report a Unit 9263 Attention condition on the next command processed on any 9264 connection for each affected I_T_L nexus with the status of CHECK 9265 CONDITION, and the ASC/ASCQ value of 47h/7Fh - "SOME COMMANDS 9266 CLEARED BY ISCSI PROTOCOL EVENT" - etc. - see [SPC3]). 9268 11.15. Logout Response 9270 The logout response is used by the target to indicate if the 9271 cleanup operation for the connection(s) has completed. 9273 After Logout, the TCP connection referred by the CID MUST be 9274 closed at both ends (or all connections must be closed if the 9275 logout reason was session close). 9277 Byte/ 0 | 1 | 2 | 3 | 9278 / | | | | 9279 |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 67| 9280 +---------------+---------------+---------------+--------------+ 9281 0|.|.| 0x26 |1| Reserved | Response | Reserved | 9282 +---------------+---------------+---------------+--------------+ 9283 4|TotalAHSLength | DataSegmentLength | 9284 +--------------------------------------------------------------+ 9285 8/ Reserved / 9286 +/ / 9287 +---------------+---------------+---------------+--------------+ 9288 16| Initiator Task Tag | 9289 +---------------+---------------+---------------+--------------+ 9290 20| Reserved | 9291 +---------------+---------------+---------------+--------------+ 9292 24| StatSN | 9293 +---------------+---------------+---------------+--------------+ 9294 28| ExpCmdSN | 9295 +---------------+---------------+---------------+--------------+ 9296 32| MaxCmdSN | 9297 +---------------+---------------+---------------+--------------+ 9298 36| Reserved | 9299 +--------------------------------------------------------------+ 9300 40| Time2Wait | Time2Retain | 9301 +---------------+---------------+---------------+--------------+ 9302 44| Reserved | 9303 +---------------+---------------+---------------+--------------+ 9304 48| Header-Digest (Optional) | 9305 +---------------+---------------+---------------+--------------+ 9307 11.15.1. Response 9309 Logout response: 9311 0 - connection or session closed successfully. 9313 1 - CID not found. 9315 2 - connection recovery is not supported. If Logout reason 9316 code was recovery and target does not support it as 9317 indicated by the ErrorRecoveryLevel. 9318 3 - cleanup failed for various reasons. 9320 11.15.2. TotalAHSLength and DataSegmentLength 9322 For this PDU TotalAHSLength and DataSegmentLength MUST be 0. 9324 11.15.3. Time2Wait 9326 If the Logout response code is 0 and if the operational 9327 ErrorRecoveryLevel is 2, this is the minimum amount of time, in 9328 seconds, to wait before attempting task reassignment. If the 9329 Logout response code is 0 and if the operational 9330 ErrorRecoveryLevel is less than 2, this field is to be ignored. 9332 This field is invalid if the Logout response code is 1. 9334 If the Logout response code is 2 or 3, this field specifies the 9335 minimum time to wait before attempting a new implicit or explicit 9336 logout. 9338 If Time2Wait is 0, the reassignment or a new Logout may be 9339 attempted immediately. 9341 11.15.4. Time2Retain 9343 If the Logout response code is 0 and if the operational 9344 ErrorRecoveryLevel is 2, this is the maximum amount of time, in 9345 seconds, after the initial wait (Time2Wait), the target waits for 9346 the allegiance reassignment for any active task after which the 9347 task state is discarded. If the Logout response code is 0 and if 9348 the operational ErrorRecoveryLevel is less than 2, this field is 9349 to be ignored. 9351 This field is invalid if the Logout response code is 1. 9353 If the Logout response code is 2 or 3, this field specifies the 9354 maximum amount of time, in seconds, after the initial wait 9355 (Time2Wait), the target waits for a new implicit or explicit 9356 logout. 9358 If it is the last connection of a session, the whole session state 9359 is discarded after Time2Retain. 9361 If Time2Retain is 0, the target has already discarded the 9362 connection (and possibly the session) state along with the task 9363 states. No reassignment or Logout is required in this case. 9365 11.16. SNACK Request 9367 Byte/ 0 | 1 | 2 | 3 | 9368 / | | | | 9369 |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 67| 9370 +---------------+---------------+---------------+--------------+ 9371 0|.|.| 0x10 |1|.|.|.| Type | Reserved | 9372 +---------------+---------------+---------------+--------------+ 9373 4|TotalAHSLength | DataSegmentLength | 9374 +---------------+---------------+---------------+--------------+ 9375 8| LUN or Reserved | 9376 + + 9377 12| | 9378 +---------------+---------------+---------------+--------------+ 9379 16| Initiator Task Tag or 0xffffffff | 9380 +---------------+---------------+---------------+--------------+ 9381 20| Target Transfer Tag or SNACK Tag or 0xffffffff | 9382 +---------------+---------------+---------------+--------------+ 9383 24| Reserved | 9384 +---------------+---------------+---------------+--------------+ 9385 28| ExpStatSN | 9386 +---------------+---------------+---------------+--------------+ 9387 32/ Reserved / 9388 +/ / 9389 +---------------+---------------+---------------+--------------+ 9390 40| BegRun | 9391 +--------------------------------------------------------------+ 9392 44| RunLength | 9393 +--------------------------------------------------------------+ 9394 48| Header-Digest (Optional) | 9395 +---------------+---------------+---------------+--------------+ 9397 If the implementation supports ErrorRecoveryLevel greater than 9398 zero, it MUST support all SNACK types. 9400 The SNACK is used by the initiator to request the retransmission 9401 of numbered-responses, data, or R2T PDUs from the target. The 9402 SNACK request indicates the numbered-responses or data "runs" 9403 whose retransmission is requested by the target, where the run 9404 starts with the first StatSN, DataSN, or R2TSN whose 9405 retransmission is requested and indicates the number of Status, 9406 Data, or R2T PDUs requested including the first. 0 has special 9407 meaning when used as a starting number and length: 9409 - When used in RunLength, it means all PDUs starting with the 9410 initial. 9412 - When used in both BegRun and RunLength, it means all 9413 unacknowledged PDUs. 9415 The numbered-response(s) or R2T(s), requested by a SNACK, MUST be 9416 delivered as exact replicas of the ones that the target 9417 transmitted originally except for the fields ExpCmdSN, MaxCmdSN, 9418 and ExpDataSN, which MUST carry the current values. 9419 R2T(s)requested by SNACK MUST also carry the current value of 9420 StatSN. 9422 The numbered Data-In PDUs, requested by a Data SNACK MUST be 9423 delivered as exact replicas of the ones that the target 9424 transmitted originally except for the fields ExpCmdSN and 9425 MaxCmdSN, which MUST carry the current values and except for 9426 resegmentation (see Section 11.16.3). 9428 Any SNACK that requests a numbered-response, Data, or R2T that was 9429 not sent by the target or was already acknowledged by the 9430 initiator, MUST be rejected with a reason code of "Protocol 9431 error". 9433 11.16.1. Type 9435 This field encodes the SNACK function as follows: 9437 0-Data/R2T SNACK - requesting retransmission of one or more 9438 Data-In or R2T PDUs. 9440 1-Status SNACK - requesting retransmission of one or more 9441 numbered responses. 9443 2-DataACK - positively acknowledges Data-In PDUs. 9445 3-R-Data SNACK - requesting retransmission of Data-In PDUs 9446 with possible resegmentation and status tagging. 9448 All other values are reserved. 9450 Data/R2T SNACK, Status SNACK, or R-Data SNACK for a command MUST 9451 precede status acknowledgement for the given command. 9453 11.16.2. Data Acknowledgement 9455 If an initiator operates at ErrorRecoveryLevel 1 or higher, it 9456 MUST issue a SNACK of type DataACK after receiving a Data-In PDU 9457 with the A bit set to 1. However, if the initiator has detected 9458 holes in the input sequence, it MUST postpone issuing the SNACK of 9459 type DataACK until the holes are filled. An initiator MAY ignore 9460 the A bit if it deems that the bit is being set aggressively by 9461 the target (i.e., before the MaxBurstLength limit is 9462 reached). 9464 The DataACK is used to free resources at the target and not to 9465 request or imply data retransmission. 9467 An initiator MUST NOT request retransmission for any data it had 9468 already acknowledged. 9470 11.16.3. Resegmentation 9472 If the initiator MaxRecvDataSegmentLength changed between the 9473 original transmission and the time the initiator requests 9474 retransmission, the initiator MUST issue a R-Data SNACK (see 9475 Section 11.16.1). With R-Data SNACK, the initiator indicates that 9476 it discards all the unacknowledged data and expects the target to 9477 resend it. It also expects resegmentation. In this case, the 9478 retransmitted Data-In PDUs MAY be different from the ones 9479 originally sent in order to reflect changes in 9480 MaxRecvDataSegmentLength. Their DataSN starts with the BegRun of 9481 the last DataACK received by the target if any was received; 9482 otherwise it starts with 0 and is increased by 1 for each resent 9483 Data-In PDU. 9485 A target that has received a R-Data SNACK MUST return a SCSI 9486 Response that contains a copy of the SNACK Tag field from the R- 9487 Data SNACK in the SCSI Response SNACK Tag field as its last or 9488 only Response. For example, if it has already sent a response 9489 containing another value in the SNACK Tag field or had the status 9490 included in the last Data-In PDU, it must send a new SCSI Response 9491 PDU. If a target sends more than one SCSI Response PDU due to this 9492 rule, all SCSI responses must carry the same StatSN (see Section 9493 11.4.4). If an initiator attempts to recover a lost SCSI Response 9494 (with a Status-SNACK, see Section 11.16.1) when more than one 9495 response has been sent, the target will send the SCSI Response 9496 with the latest content known to the target, including the last 9497 SNACK Tag for the command. 9499 For considerations in allegiance reassignment of a task to a 9500 connection with a different MaxRecvDataSegmentLength, refer to 9501 Section 7.2.2. 9503 11.16.4. Initiator Task Tag 9505 For Status SNACK and DataACK, the Initiator Task Tag MUST be set 9506 to the reserved value 0xffffffff. In all other cases, the 9507 Initiator Task Tag field MUST be set to the Initiator Task Tag of 9508 the referenced command. 9510 11.16.5. Target Transfer Tag or SNACK Tag 9512 For an R-Data SNACK, this field MUST contain a value that is 9513 different from 0 or 0xffffffff and is unique for the task 9514 (identified by the Initiator Task Tag). This value MUST be copied 9515 by the iSCSI target in the last or only SCSI Response PDU it 9516 issues for the command. 9518 For DataACK, the Target Transfer Tag MUST contain a copy of the 9519 Target Transfer Tag and LUN provided with the SCSI Data-In PDU 9520 with the A bit set to 1. 9522 In all other cases, the Target Transfer Tag field MUST be set to 9523 the reserved value of 0xffffffff. 9525 11.16.6. BegRun 9527 The DataSN, R2TSN, or StatSN of the first PDU whose retransmission 9528 is requested (Data/R2T and Status SNACK), or the next expected 9529 DataSN (DataACK SNACK). 9531 BegRun 0 when used in conjunction with RunLength 0 means resend 9532 all unacknowledged Data-In, R2T or Response PDUs. 9534 BegRun MUST be 0 for a R-Data SNACK. 9536 11.16.7. RunLength 9538 The number of PDUs whose retransmission is requested. 9540 RunLength 0 signals that all Data-In, R2T, or Response PDUs 9541 carrying the numbers equal to or greater than BegRun have to be 9542 resent. 9544 The RunLength MUST also be 0 for a DataACK SNACK in addition to R- 9545 Data SNACK. 9547 11.17. Reject 9549 Byte/ 0 | 1 | 2 | 3 | 9550 / | | | | 9551 |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 67| 9552 +---------------+---------------+---------------+--------------+ 9553 0|.|.| 0x3f |1| Reserved | Reason | Reserved | 9554 +---------------+---------------+---------------+--------------+ 9555 4|TotalAHSLength | DataSegmentLength | 9556 +---------------+---------------+---------------+--------------+ 9557 8/ Reserved / 9558 +/ / 9559 +---------------+---------------+---------------+--------------+ 9560 16| 0xffffffff | 9561 +---------------+---------------+---------------+--------------+ 9562 20| Reserved | 9563 +---------------+---------------+---------------+--------------+ 9564 24| StatSN | 9565 +---------------+---------------+---------------+--------------+ 9566 28| ExpCmdSN | 9567 +---------------+---------------+---------------+--------------+ 9568 32| MaxCmdSN | 9569 +---------------+---------------+---------------+--------------+ 9570 36| DataSN/R2TSN or Reserved | 9571 +---------------+---------------+---------------+--------------+ 9572 40| Reserved | 9573 +---------------+---------------+---------------+--------------+ 9574 44| Reserved | 9575 +---------------+---------------+---------------+--------------+ 9576 48| Header-Digest (Optional) | 9577 +---------------+---------------+---------------+--------------+ 9578 xx/ Complete Header of Bad PDU / 9579 +/ / 9580 +---------------+---------------+---------------+--------------+ 9581 yy/Vendor specific data (if any) / 9582 / / 9583 +---------------+---------------+---------------+--------------+ 9584 zz| Data-Digest (Optional) | 9585 +---------------+---------------+---------------+--------------+ 9587 Reject is used to indicate an iSCSI error condition (protocol, 9588 unsupported option, etc.). 9590 11.17.1. Reason 9592 The reject Reason is coded as follows: 9594 +------+----------------------------------------+----------------+ 9595 | Code | Explanation |Can the original| 9596 | (hex)| |PDU be re-sent? | 9597 +------+----------------------------------------+----------------+ 9598 | 0x01 | Reserved | no | 9599 | | | | 9600 | 0x02 | Data (payload) Digest Error | yes (Note 1) | 9601 | | | | 9602 | 0x03 | SNACK Reject | yes | 9603 | | | | 9604 | 0x04 | Protocol Error (e.g., SNACK request for| no | 9605 | | a status that was already acknowledged)| | 9606 | | | | 9607 | 0x05 | Command not supported | no | 9608 | | | | 9609 | 0x06 | Immediate Command Reject - too many | yes | 9610 | | immediate commands | | 9611 | | | | 9612 | 0x07 | Task in progress | no | 9613 | | | | 9614 | 0x08 | Invalid Data ACK | no | 9615 | | | | 9616 | 0x09 | Invalid PDU field | no (Note 2) | 9617 | | | | 9618 | 0x0a | Long Operation Reject - Can't generate | yes | 9619 | | Target Transfer Tag - out of resources | | 9620 | | | | 9621 | 0x0c | Waiting for Logout | no | 9622 +------+----------------------------------------+----------------+ 9624 Note 1: For iSCSI, Data-Out PDU retransmission is only done if the 9625 target requests retransmission with a recovery R2T. However, if 9626 this is the data digest error on immediate data, the initiator may 9627 choose to retransmit the whole PDU including the immediate data. 9629 Note 2: A target should use this reason code for all invalid 9630 values of PDU fields that are meant to describe a task, a 9631 response, or a data transfer. Some examples are invalid TTT/ITT, 9632 buffer offset, LUN qualifying a TTT, and an invalid sequence 9633 number in a SNACK. 9635 Note 3: Reason code 0x0b ("Negotiation reset") defined in 9636 [RFC3720] is deprecated and MUST NOT be used by implementations. 9637 An implementation receiving reason code 0x0b MUST treat it as a 9638 negotiation failure that terminates the Login Phase and the TCP 9639 connection, as specified in Section 7.12. 9641 All other values for Reason are reserved. 9643 In all the cases in which a pre-instantiated SCSI task is 9644 terminated because of the reject, the target MUST issue a proper 9645 SCSI command response with CHECK CONDITION as described in Section 9646 11.4.3. In these cases in which a status for the SCSI task was 9647 already sent before the reject, no additional status is required. 9648 If the error is detected while data from the initiator is still 9649 expected (i.e., the command PDU did not contain all the data and 9650 the target has not received a Data-out PDU with the Final bit set 9651 to 1 for the unsolicited data, if any, and all outstanding R2Ts, 9652 if any), the target MUST wait until it receives the last expected 9653 Data-out PDUs with the F bit set to 1 before sending the Response 9654 PDU. 9656 For additional usage semantics of Reject PDU, see Section 7.3. 9658 11.17.2. DataSN/R2TSN 9660 This field is only valid if the rejected PDU is a Data/R2T SNACK 9661 and the Reject reason code is "Protocol error" (see Section 9662 11.16). The DataSN/R2TSN is the next Data/R2T sequence number 9663 that the target would send for the task, if any. 9665 11.17.3. StatSN, ExpCmdSN and MaxCmdSN 9667 These fields carry their usual values and are not related to the 9668 rejected command. StatSN is advanced after a Reject. 9670 11.17.4. Complete Header of Bad PDU 9672 The target returns the header (not including digest) of the PDU in 9673 error as the data of the response. 9675 11.18. NOP-Out 9677 Byte/ 0 | 1 | 2 | 3 | 9678 / | | | | 9679 |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 67| 9680 +---------------+---------------+---------------+--------------+ 9681 0|.|I| 0x00 |1| Reserved | 9682 +---------------+---------------+---------------+--------------+ 9683 4|TotalAHSLength | DataSegmentLength | 9684 +---------------+---------------+---------------+--------------+ 9685 8| LUN or Reserved | 9686 + + 9687 12| | 9688 +---------------+---------------+---------------+--------------+ 9689 16| Initiator Task Tag or 0xffffffff | 9690 +---------------+---------------+---------------+--------------+ 9691 20| Target Transfer Tag or 0xffffffff | 9692 +---------------+---------------+---------------+--------------+ 9693 24| CmdSN | 9694 +---------------+---------------+---------------+--------------+ 9695 28| ExpStatSN | 9696 +---------------+---------------+---------------+--------------+ 9697 32/ Reserved / 9698 +/ / 9699 +---------------+---------------+---------------+--------------+ 9700 48| Header-Digest (Optional) | 9701 +---------------+---------------+---------------+--------------+ 9702 / DataSegment - Ping Data (optional) / 9703 +/ / 9704 +---------------+---------------+---------------+--------------+ 9705 | Data-Digest (Optional) | 9706 +---------------+---------------+---------------+--------------+ 9708 A NOP-Out may be used by an initiator as a "ping request" to 9709 verify that a connection/session is still active and all its 9710 components are operational. The NOP-In response is the "ping 9711 echo". 9713 A NOP-Out is also sent by an initiator in response to a NOP-In. 9715 A NOP-Out may also be used to confirm a changed ExpStatSN if 9716 another PDU will not be available for a long time. 9718 Upon receipt of a NOP-In with the Target Transfer Tag set to a 9719 valid value (not the reserved 0xffffffff), the initiator MUST 9720 respond with a NOP-Out. In this case, the NOP-Out Target Transfer 9721 Tag MUST contain a copy of the NOP-In Target Transfer Tag. The 9722 initiator SHOULD NOT send a NOP-Out in response to any other 9723 received NOP-In in order to avoid lengthy sequences of NOP-In and 9724 NOP-Out PDUs sent in response to each other. 9726 11.18.1. Initiator Task Tag 9728 The NOP-Out MUST have the Initiator Task Tag set to a valid value 9729 only if a response in the form of NOP-In is requested (i.e., the 9730 NOP-Out is used as a ping request). Otherwise, the Initiator Task 9731 Tag MUST be set to 0xffffffff. 9733 When a target receives the NOP-Out with a valid Initiator Task 9734 Tag, it MUST respond with a Nop-In Response (see Section 6). 9736 If the Initiator Task Tag contains 0xffffffff, the I bit MUST be 9737 set to 1 and the CmdSN is not advanced after this PDU is sent. 9739 11.18.2. Target Transfer Tag 9741 A target assigned identifier for the operation. 9743 The NOP-Out MUST only have the Target Transfer Tag set if it is 9744 issued in response to a NOP-In with a valid Target Transfer Tag. 9745 In this case, it copies the Target Transfer Tag from the NOP-In 9746 PDU. Otherwise, the Target Transfer Tag MUST be set to 0xffffffff. 9748 When the Target Transfer Tag is set to a value other than 9749 0xffffffff, the LUN field MUST also be copied from the NOP-In. 9751 11.18.3. Ping Data 9753 Ping data is reflected in the NOP-In Response. The length of the 9754 reflected data is limited to MaxRecvDataSegmentLength. The length 9755 of ping data is indicated by the DataSegmentLength. 0 is a valid 9756 value for the DataSegmentLength and indicates the absence of ping 9757 data. 9759 11.19. NOP-In 9761 Byte/ 0 | 1 | 2 | 3 | 9762 / | | | | 9763 |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 67| 9764 +---------------+---------------+---------------+--------------+ 9765 0|.|.| 0x20 |1| Reserved | 9766 +---------------+---------------+---------------+--------------+ 9767 4|TotalAHSLength | DataSegmentLength | 9768 +---------------+---------------+---------------+--------------+ 9769 8| LUN or Reserved | 9770 + + 9771 12| | 9772 +---------------+---------------+---------------+--------------+ 9773 16| Initiator Task Tag or 0xffffffff | 9774 +---------------+---------------+---------------+--------------+ 9775 20| Target Transfer Tag or 0xffffffff | 9776 +---------------+---------------+---------------+--------------+ 9777 24| StatSN | 9778 +---------------+---------------+---------------+--------------+ 9779 28| ExpCmdSN | 9780 +---------------+---------------+---------------+--------------+ 9781 32| MaxCmdSN | 9782 +---------------+---------------+---------------+--------------+ 9783 36/ Reserved / 9784 +/ / 9785 +---------------+---------------+---------------+--------------+ 9786 48| Header-Digest (Optional) | 9787 +---------------+---------------+---------------+--------------+ 9788 / DataSegment - Return Ping Data / 9789 +/ / 9790 +---------------+---------------+---------------+--------------+ 9791 | Data-Digest (Optional) | 9792 +---------------+---------------+---------------+--------------+ 9794 NOP-In is either sent by a target as a response to a NOP-Out, as a 9795 "ping" to an initiator, or as a means to carry a changed ExpCmdSN 9796 and/or MaxCmdSN if another PDU will not be available for a long 9797 time (as determined by the target). 9799 When a target receives the NOP-Out with a valid Initiator Task Tag 9800 (not the reserved value 0xffffffff), it MUST respond with a NOP-In 9801 with the same Initiator Task Tag that was provided in the NOP-Out 9802 request. It MUST also duplicate up to the first 9803 MaxRecvDataSegmentLength bytes of the initiator provided Ping 9804 Data. For such a response, the Target Transfer Tag MUST be 9805 0xffffffff. The target SHOULD NOT send a NOP-In in response to any 9806 other received NOP-Out in order to avoid lengthy sequences of NOP- 9807 In and NOP-Out PDUs sent in response to each other. 9809 Otherwise, when a target sends a NOP-In that is not a response to 9810 a Nop-Out received from the initiator, the Initiator Task Tag MUST 9811 be set to 0xffffffff and the Data Segment MUST NOT contain any 9812 data (DataSegmentLength MUST be 0). 9814 11.19.1. Target Transfer Tag 9816 If the target is responding to a NOP-Out, this is set to the 9817 reserved value 0xffffffff. 9819 If the target is sending a NOP-In as a Ping (intending to receive 9820 a corresponding NOP-Out), this field is set to a valid value (not 9821 the reserved 0xffffffff). 9823 If the target is initiating a NOP-In without wanting to receive a 9824 corresponding NOP-Out, this field MUST hold the reserved value of 9825 0xffffffff. 9827 11.19.2. StatSN 9829 The StatSN field will always contain the next StatSN. However, 9830 when the Initiator Task Tag is set to 0xffffffff StatSN for the 9831 connection is not advanced after this PDU is sent. 9833 11.19.3. LUN 9835 A LUN MUST be set to a correct value when the Target Transfer Tag 9836 is valid (not the reserved value 0xffffffff). 9838 12. iSCSI Security Text Keys and Authentication Methods 9840 Only the following keys are used during the SecurityNegotiation 9841 stage of the Login Phase: 9843 SessionType 9845 InitiatorName 9847 TargetName 9849 TargetAddress 9851 InitiatorAlias 9853 TargetAlias 9855 TargetPortalGroupTag 9857 AuthMethod and the keys used by the authentication methods 9858 specified under Section 12.1 along with all of their 9859 associated keys as well as Vendor-Specific Authentication 9860 Methods. 9862 Other keys MUST NOT be used. 9864 SessionType, InitiatorName, TargetName, InitiatorAlias, 9865 TargetAlias, and TargetPortalGroupTag are described in Section 13 9866 as they can be used also in the OperationalNegotiation stage. 9868 All security keys have connection-wide applicability. 9870 12.1. AuthMethod 9872 Use: During Login - Security Negotiation 9873 Senders: Initiator and Target 9874 Scope: connection 9876 AuthMethod = 9878 The main item of security negotiation is the authentication method 9879 (AuthMethod). 9881 The authentication methods that can be used (appear in the list- 9882 of-values) are either those listed in the following table or are 9883 vendor-unique methods: 9885 +------------------------------------------------------------+ 9886 | Name | Description | 9887 +------------------------------------------------------------+ 9888 | KRB5 | Kerberos V5 - defined in [RFC4120] | 9889 +------------------------------------------------------------+ 9890 | SRP | Secure Remote Password | 9891 | | defined in [RFC2945] | 9892 +------------------------------------------------------------+ 9893 | CHAP | Challenge Handshake Authentication Protocol| 9894 | | defined in [RFC1994] | 9895 +------------------------------------------------------------+ 9896 | None | No authentication | 9897 +------------------------------------------------------------+ 9899 The AuthMethod selection is followed by an "authentication 9900 exchange" specific to the authentication method selected. 9902 The authentication method proposal may be made by either the 9903 initiator or the target. However the initiator MUST make the first 9904 step specific to the selected authentication method as soon as it 9905 is selected. It follows that if the target makes the 9906 authentication method proposal the initiator sends the first 9907 key(s) of the exchange together with its authentication method 9908 selection. 9910 The authentication exchange authenticates the initiator to the 9911 target, and optionally, the target to the initiator. 9912 Authentication is OPTIONAL to use but MUST be supported by the 9913 target and initiator. 9915 The initiator and target MUST implement CHAP. All other 9916 authentication methods are OPTIONAL. 9918 Private or public extension algorithms MAY also be negotiated for 9919 authentication methods. Whenever a private or public extension 9920 algorithm is part of the default offer (the offer made in absence 9921 of explicit administrative action) the implementer MUST ensure 9922 that CHAP is listed as an alternative in the default offer and 9923 "None" is not part of the default offer. 9925 Extension authentication methods MUST be named using one of the 9926 following two formats: 9928 i) Z-reversed.vendor.dns_name.do_something= 9929 ii) New public key with no name prefix constraints 9931 Authentication methods named using the Z- format are used as 9932 private extensions. New public keys must be registered with IANA 9933 using IETF Review process ([RFC5226]). New public extensions for 9934 authentication methods MUST NOT use the Z# name prefix. 9936 For all of the public or private extension authentication methods, 9937 the method specific keys MUST conform to the format specified in 9938 Section 6.1 for standard-label. 9940 To identify the vendor for private extension authentication 9941 methods, we suggest you use the reversed DNS-name as a prefix to 9942 the proper digest names. 9944 The part of digest-name following Z- MUST conform to the format 9945 for standard-label specified in Section 6.1. 9947 Support for public or private extension authentication methods is 9948 OPTIONAL. 9950 The following subsections define the specific exchanges for each 9951 of the standardized authentication methods. As mentioned earlier 9952 the first step is always done by the initiator. 9954 12.1.1. Kerberos 9956 For KRB5 (Kerberos V5) [RFC4120] and [RFC1964], the initiator MUST 9957 use: 9959 KRB_AP_REQ= 9961 where KRB_AP_REQ is the client message as defined in [RFC4120]. 9963 The default principal name assumed by an iSCSI initiator or target 9964 (prior to any administrative configuration action) MUST be the 9965 iSCSI Initiator Name or iSCSI Target Name respectively, prefixed 9966 by the string "iscsi/". 9968 If the initiator authentication fails, the target MUST respond 9969 with a Login reject with "Authentication Failure" status. 9970 Otherwise, if the initiator has selected the mutual authentication 9971 option (by setting MUTUAL-REQUIRED in the ap-options field of the 9972 KRB_AP_REQ), the target MUST reply with: 9974 KRB_AP_REP= 9976 where KRB_AP_REP is the server's response message as defined in 9977 [RFC4120]. 9979 If mutual authentication was selected and target authentication 9980 fails, the initiator MUST close the connection. 9982 KRB_AP_REQ and KRB_AP_REP are binary-values and their binary 9983 length (not the length of the character string that represents 9984 them in encoded form) MUST NOT exceed 65536 bytes. 9986 12.1.2. Secure Remote Password (SRP) 9988 For SRP [RFC2945], the initiator MUST use: 9990 SRP_U= TargetAuth=Yes /* or TargetAuth=No */ 9992 The target MUST answer with a Login reject with the "Authorization 9993 Failure" status or reply with: 9995 SRP_GROUP= SRP_s= 9997 Where G1,G2... are proposed groups, in order of preference. 9999 The initiator MUST either close the connection or continue with: 10001 SRP_A= SRP_GROUP= 10002 Where G is one of G1,G2... that were proposed by the target. 10004 The target MUST answer with a Login reject with the 10005 "Authentication Failure" status or reply with: 10007 SRP_B= 10009 The initiator MUST close the connection or continue with: 10011 SRP_M= 10013 If the initiator authentication fails, the target MUST answer with 10014 a Login reject with "Authentication Failure" status. Otherwise, if 10015 the initiator sent TargetAuth=Yes in the first message (requiring 10016 target authentication), the target MUST reply with: 10018 SRP_HM= 10020 If the target authentication fails, the initiator MUST close the 10021 connection. 10023 Where U, s, A, B, M, and H(A | M | K) are defined in [RFC2945] 10024 (using the SHA1 hash function, such as SRP-SHA1) and G,Gn (Gn 10025 stands for G1,G2...) are identifiers of SRP groups specified in 10026 [RFC3723]. G, Gn, and U are text strings, s,A,B,M, and H(A | M | 10027 K) are binary-values. The length of s,A,B,M and H(A | M | K) in 10028 binary form (not the length of the character string that 10029 represents them in encoded form) MUST NOT exceed 1024 bytes. 10031 See Appendix B for the related login example. 10033 For the SRP_GROUP, all the groups specified in [RFC3723] up to 10034 1536 bits (i.e., SRP-768, SRP-1024, SRP-1280, SRP-1536) must be 10035 supported by initiators and targets. To guarantee 10036 interoperability, targets MUST always offer "SRP-1536" as one of 10037 the proposed groups. 10039 12.1.3. Challenge Handshake Authentication Protocol (CHAP) 10041 For CHAP [RFC1994], the initiator MUST use: 10043 CHAP_A= 10045 Where A1,A2... are proposed algorithms, in order of preference. 10047 The target MUST answer with a Login reject with the 10048 "Authentication Failure" status or reply with: 10050 CHAP_A= CHAP_I= CHAP_C= 10052 Where A is one of A1,A2... that were proposed by the initiator. 10054 The initiator MUST continue with: 10056 CHAP_N= CHAP_R= 10058 or, if it requires target authentication, with: 10060 CHAP_N= CHAP_R= CHAP_I= CHAP_C= 10062 If the initiator authentication fails, the target MUST answer with 10063 a Login reject with "Authentication Failure" status. Otherwise, if 10064 the initiator required target authentication, the target MUST 10065 either answer with a Login reject with "Authentication Failure" or 10066 reply with: 10068 CHAP_N= CHAP_R= 10070 If target authentication fails, the initiator MUST close the 10071 connection. 10073 Where N, (A,A1,A2), I, C, and R are (correspondingly) the Name, 10074 Algorithm, Identifier, Challenge, and Response as defined in 10075 [RFC1994], N is a text string, A,A1,A2, and I are numbers, and C 10076 and R are binary-values and their binary length (not the length of 10077 the character string that represents them in encoded form) MUST 10078 NOT exceed 1024 bytes. 10080 See Appendix B for the related login example. 10082 For the Algorithm, as stated in [RFC1994], one value is required 10083 to be implemented: 10085 5 (CHAP with MD5) 10087 To guarantee interoperability, initiators MUST always offer it as 10088 one of the proposed algorithms. 10090 13. Login/Text Operational Text Keys 10092 Some session specific parameters MUST only be carried on the 10093 leading connection and cannot be changed after the leading 10094 connection login (e.g., MaxConnections, the maximum number of 10095 connections). This holds for a single connection session with 10096 regard to connection restart. The keys that fall into this 10097 category have the use: LO (Leading Only). 10099 Keys that can only be used during login have the use: IO 10100 (initialize only), while those that can be used in both the Login 10101 Phase and Full Feature Phase have the use: ALL. 10103 Keys that can only be used during Full Feature Phase use FFPO 10104 (Full Feature Phase only). 10106 Keys marked as Any-Stage may also appear in the 10107 SecurityNegotiation stage while all other keys described in this 10108 Section are operational keys. 10110 Keys that do not require an answer are marked as Declarative. 10112 Key scope is indicated as session-wide (SW) or connection-only 10113 (CO). 10115 Result function, wherever mentioned, states the function that can 10116 be applied to check the validity of the responder selection. 10117 Minimum means that the selected value cannot exceed the offered 10118 value. Maximum means that the selected value cannot be lower than 10119 the offered value. AND means that the selected value must be a 10120 possible result of a Boolean "and" function with an arbitrary 10121 Boolean value (e.g., if the offered value is No the selected value 10122 must be No). OR means that the selected value must be a possible 10123 result of a Boolean "or" function with an arbitrary Boolean value 10124 (e.g., if the offered value is Yes the selected value must be 10125 Yes). 10127 13.1. HeaderDigest and DataDigest 10129 Use: IO 10130 Senders: Initiator and Target 10131 Scope: CO 10132 HeaderDigest = 10133 DataDigest = 10135 Default is None for both HeaderDigest and DataDigest. 10137 Digests enable the checking of end-to-end, non-cryptographic data 10138 integrity beyond the integrity checks provided by the link layers 10139 and the covering of the whole communication path including all 10140 elements that may change the network level PDUs such as routers, 10141 switches, and proxies. 10143 The following table lists cyclic integrity checksums that can be 10144 negotiated for the digests and that MUST be implemented by every 10145 iSCSI initiator and target. These digest options only have error 10146 detection significance. 10148 +---------------------------------------------+ 10149 | Name | Description | Generator | 10150 +---------------------------------------------+ 10151 | CRC32C | 32 bit CRC |0x11edc6f41| 10152 +---------------------------------------------+ 10153 | None | no digest | 10154 +---------------------------------------------+ 10156 The generator polynomial for this digest is given in hex-notation 10157 (e.g., 0x3b stands for 0011 1011 and the polynomial is 10158 x**5+X**4+x**3+x+1). 10160 When the Initiator and Target agree on a digest, this digest MUST 10161 be used for every PDU in Full Feature Phase. 10163 Padding bytes, when present in a segment covered by a CRC, SHOULD 10164 be set to 0 and are included in the CRC. 10166 The CRC MUST be calculated by a method that produces the same 10167 results as the following process: 10169 - The PDU bits are considered as the coefficients of a 10170 polynomial M(x) of degree n-1; bit 7 of the lowest numbered 10171 byte is considered the most significant bit (x^n-1), 10173 followed by bit 6 of the lowest numbered byte through bit 0 10174 of the highest numbered byte (x^0). 10176 - The most significant 32 bits are complemented. 10178 - The polynomial is multiplied by x^32 then divided by G(x). 10179 The generator polynomial produces a remainder R(x) of degree 10180 <= 31. 10182 - The coefficients of R(x) are considered a 32 bit sequence. 10184 - The bit sequence is complemented and the result is the CRC. 10186 - The CRC bits are mapped into the digest word. The x^31 10187 coefficient in bit 7 of the lowest numbered byte of the 10188 digest continuing through to the byte up to the x^24 10189 coefficient in bit 0 of the lowest numbered byte, continuing 10190 with the x^23 coefficient in bit 7 of next byte through x^0 10191 in bit 0 of the highest numbered byte. 10193 - Computing the CRC over any segment (data or header) extended 10194 to include the CRC built using the generator 0x11edc6f41 10195 will always get the value 0x1c2d19ed as its final remainder 10196 (R(x)). This value is given here in its polynomial form 10197 (i.e., not mapped as the digest word). 10199 For a discussion about selection criteria for the CRC, see 10200 [RFC3385]. For a detailed analysis of the iSCSI polynomial, see 10201 [Castagnoli93]. 10203 Private or public extension algorithms MAY also be negotiated for 10204 digests. Whenever a private or public digest extension algorithm 10205 is part of the default offer (the offer made in absence of 10206 explicit administrative action) the implementer MUST ensure that 10207 CRC32C is listed as an alternative in the default offer and "None" 10208 is not part of the default offer. 10210 Extension digest algorithms MUST be named using one of the 10211 following two formats: 10213 i) Y-reversed.vendor.dns_name.do_something= 10214 ii) New public key with no name prefix constraints 10216 Digests named using the Y- format are used for private purposes 10217 (unregistered). New public keys must be registered with IANA using 10218 IETF Review process ([RFC5226]). New public extensions for digests 10219 MUST NOT use the Y# name prefix. 10221 For private extension digests, to identify the vendor, we suggest 10222 you use the reversed DNS-name as a prefix to the proper digest 10223 names. 10225 The part of digest-name following Y- MUST conform to the format 10226 for standard-label specified in Section 6.1. 10228 Support for public or private extension digests is OPTIONAL. 10230 13.2. MaxConnections 10232 Use: LO 10233 Senders: Initiator and Target 10234 Scope: SW 10235 Irrelevant when: SessionType=Discovery 10237 MaxConnections= 10239 Default is 1. 10240 Result function is Minimum. 10242 Initiator and target negotiate the maximum number of connections 10243 requested/acceptable. 10245 13.3. SendTargets 10247 Use: FFPO 10248 Senders: Initiator 10249 Scope: SW 10251 For a complete description, see Appendix C. 10253 13.4. TargetName 10255 Use: IO by initiator, FFPO by target - only as response to a 10256 SendTargets, Declarative, Any-Stage 10257 Senders: Initiator and Target 10258 Scope: SW 10260 TargetName= 10262 Examples: 10264 TargetName=iqn.1993-11.com.disk-vendor:diskarrays.sn.45678 10266 TargetName=eui.020000023B040506 10268 TargetName=naa.62004567BA64678D0123456789ABCDEF 10270 The initiator of the TCP connection MUST provide this key to the 10271 remote endpoint in the first login request if the initiator is not 10272 establishing a discovery session. The iSCSI Target Name specifies 10273 the worldwide unique name of the target. 10275 The TargetName key may also be returned by the "SendTargets" text 10276 request (which is its only use when issued by a target). 10278 TargetName MUST NOT be redeclared within the login phase. 10280 13.5. InitiatorName 10282 Use: IO, Declarative, Any-Stage 10283 Senders: Initiator 10284 Scope: SW 10286 InitiatorName= 10288 Examples: 10290 InitiatorName=iqn.1992-04.com.os-vendor.plan9:cdrom.12345 10292 InitiatorName=iqn.2001-02.com.ssp.users:customer235.host90 10294 InitiatorName=naa.52004567BA64678D 10296 The initiator of the TCP connection MUST provide this key to the 10297 remote endpoint at the first Login of the Login Phase for every 10298 connection. The InitiatorName key enables the initiator to 10299 identify itself to the remote endpoint. 10301 InitiatorName MUST NOT be redeclared within the login phase. 10303 13.6. TargetAlias 10305 Use: ALL, Declarative, Any-Stage 10306 Senders: Target 10307 Scope: SW 10309 TargetAlias= 10311 Examples: 10313 TargetAlias=Bob-s Disk 10315 TargetAlias=Database Server 1 Log Disk 10317 TargetAlias=Web Server 3 Disk 20 10319 If a target has been configured with a human-readable name or 10320 description, this name SHOULD be communicated to the initiator 10321 during a Login Response PDU if SessionType=Normal (see 13.21). 10322 This string is not used as an identifier, nor is it meant to be 10323 used for authentication or authorization decisions. It can be 10324 displayed by the initiator's user interface in a list of targets 10325 to which it is connected. 10327 13.7. InitiatorAlias 10329 Use: ALL, Declarative, Any-Stage 10330 Senders: Initiator 10331 Scope: SW 10333 InitiatorAlias= 10335 Examples: 10337 InitiatorAlias=Web Server 4 10339 InitiatorAlias=spyalley.nsa.gov 10341 InitiatorAlias=Exchange Server 10343 If an initiator has been configured with a human-readable name or 10344 description, it SHOULD be communicated to the target during a 10345 Login Request PDU. If not, the host name can be used instead. This 10346 string is not used as an identifier, nor is meant to be used for 10347 authentication or authorization decisions. It can be displayed by 10348 the target's user interface in a list of initiators to which it is 10349 connected. 10351 13.8. TargetAddress 10353 Use: ALL, Declarative, Any-Stage 10354 Senders: Target 10355 Scope: SW 10357 TargetAddress=domainname[:port][,portal-group-tag] 10359 The domainname can be specified as either a DNS host name, a 10360 dotted-decimal IPv4 address, or a bracketed IPv6 address as 10361 specified in [RFC3986]. 10363 If the TCP port is not specified, it is assumed to be the IANA- 10364 assigned default port for iSCSI (see Section 14). 10366 If the TargetAddress is returned as the result of a redirect 10367 status in a login response, the comma and portal group tag MUST be 10368 omitted. 10370 If the TargetAddress is returned within a SendTargets response, 10371 the portal group tag MUST be included. 10373 Examples: 10375 TargetAddress=10.0.0.1:5003,1 10377 TargetAddress=[1080:0:0:0:8:800:200C:417A],65 10378 TargetAddress=[1080::8:800:200C:417A]:5003,1 10380 TargetAddress=computingcenter.example.com,23 10382 Use of the portal-group-tag is described in Appendix C. The 10383 formats for the port and portal-group-tag are the same as the one 10384 specified in TargetPortalGroupTag. 10386 13.9. TargetPortalGroupTag 10388 Use: IO by target, Declarative, Any-Stage 10389 Senders: Target 10390 Scope: SW 10392 TargetPortalGroupTag=<16-bit-binary-value> 10394 Examples: 10395 TargetPortalGroupTag=1 10397 The target portal group tag is a 16-bit binary-value that uniquely 10398 identifies a portal group within an iSCSI target node. This key 10399 carries the value of the tag of the portal group that is servicing 10400 the Login request. The iSCSI target returns this key to the 10401 initiator in the Login Response PDU to the first Login Request PDU 10402 that has the C bit set to 0 when TargetName is given by the 10403 initiator. 10405 [SAM2] notes in its informative text that TPGT value should be 10406 non-zero, note that it is incorrect. A zero value is allowed as a 10407 legal value for TPGT. This discrepancy currently stands corrected 10408 in [SAM4]. 10410 For the complete usage expectations of this key see Section 6.3. 10412 13.10. InitialR2T 10414 Use: LO 10415 Senders: Initiator and Target 10416 Scope: SW 10417 Irrelevant when: SessionType=Discovery 10419 InitialR2T= 10421 Examples: 10423 I->InitialR2T=No 10425 T->InitialR2T=No 10427 Default is Yes. 10428 Result function is OR. 10430 The InitialR2T key is used to turn off the default use of R2T for 10431 unidirectional and the output part of bidirectional commands, thus 10432 allowing an initiator to start sending data to a target as if it 10433 has received an initial R2T with Buffer Offset=Immediate Data 10434 Length and Desired Data Transfer Length=(min(FirstBurstLength, 10435 Expected Data Transfer Length) - Received Immediate Data Length). 10437 The default action is that R2T is required, unless both the 10438 initiator and the target send this key-pair attribute specifying 10439 InitialR2T=No. Only the first outgoing data burst (immediate data 10440 and/or separate PDUs) can be sent unsolicited (i.e., not requiring 10441 an explicit R2T). 10443 13.11. ImmediateData 10445 Use: LO 10446 Senders: Initiator and Target 10447 Scope: SW 10448 Irrelevant when: SessionType=Discovery 10450 ImmediateData= 10452 Default is Yes. 10453 Result function is AND. 10455 The initiator and target negotiate support for immediate data. To 10456 turn immediate data off, the initiator or target must state its 10457 desire to do so. ImmediateData can be turned on if both the 10458 initiator and target have ImmediateData=Yes. 10460 If ImmediateData is set to Yes and InitialR2T is set to Yes 10461 (default), then only immediate data are accepted in the first 10462 burst. 10464 If ImmediateData is set to No and InitialR2T is set to Yes, then 10465 the initiator MUST NOT send unsolicited data and the target MUST 10466 reject unsolicited data with the corresponding response code. 10468 If ImmediateData is set to No and InitialR2T is set to No, then 10469 the initiator MUST NOT send unsolicited immediate data, but MAY 10470 send one unsolicited burst of Data-OUT PDUs. 10472 If ImmediateData is set to Yes and InitialR2T is set to No, then 10473 the initiator MAY send unsolicited immediate data and/or one 10474 unsolicited burst of Data-OUT PDUs. 10476 The following table is a summary of unsolicited data options: 10478 +----------+-------------+------------------+--------------+ 10479 |InitialR2T|ImmediateData| Unsolicited |Immediate Data| 10480 | | | Data Out PDUs | | 10481 +----------+-------------+------------------+--------------+ 10482 | No | No | Yes | No | 10483 +----------+-------------+------------------+--------------+ 10484 | No | Yes | Yes | Yes | 10485 +----------+-------------+------------------+--------------+ 10486 | Yes | No | No | No | 10487 +----------+-------------+------------------+--------------+ 10488 | Yes | Yes | No | Yes | 10489 +----------+-------------+------------------+--------------+ 10491 13.12. MaxRecvDataSegmentLength 10493 Use: ALL, Declarative 10494 Senders: Initiator and Target 10495 Scope: CO 10497 MaxRecvDataSegmentLength= 10499 Default is 8192 bytes. 10501 The initiator or target declares the maximum data segment length 10502 in bytes it can receive in an iSCSI PDU. 10504 The transmitter (initiator or target) is required to send PDUs 10505 with a data segment that does not exceed MaxRecvDataSegmentLength 10506 of the receiver. 10508 A target receiver is additionally limited by MaxBurstLength for 10509 solicited data and FirstBurstLength for unsolicited data. An 10510 initiator MUST NOT send solicited PDUs exceeding MaxBurstLength 10511 nor unsolicited PDUs exceeding FirstBurstLength (or 10512 FirstBurstLength-Immediate Data Length if immediate data were 10513 sent). 10515 13.13. MaxBurstLength 10517 Use: LO 10518 Senders: Initiator and Target 10519 Scope: SW 10520 Irrelevant when: SessionType=Discovery 10522 MaxBurstLength= 10524 Default is 262144 (256 Kbytes). 10525 Result function is Minimum. 10527 The initiator and target negotiate maximum SCSI data payload in 10528 bytes in a Data-In or a solicited Data-Out iSCSI sequence. A 10529 sequence consists of one or more consecutive Data-In or Data-Out 10530 PDUs that end with a Data-In or Data-Out PDU with the F bit set to 10531 one. 10533 13.14. FirstBurstLength 10535 Use: LO 10536 Senders: Initiator and Target 10537 Scope: SW 10538 Irrelevant when: SessionType=Discovery 10539 Irrelevant when: ( InitialR2T=Yes and ImmediateData=No ) 10541 FirstBurstLength= 10542 Default is 65536 (64 Kbytes). 10543 Result function is Minimum. 10545 The initiator and target negotiate the maximum amount in bytes of 10546 unsolicited data an iSCSI initiator may send to the target during 10547 the execution of a single SCSI command. This covers the immediate 10548 data (if any) and the sequence of unsolicited Data-Out PDUs (if 10549 any) that follow the command. 10551 FirstBurstLength MUST NOT exceed MaxBurstLength. 10553 13.15. DefaultTime2Wait 10555 Use: LO 10556 Senders: Initiator and Target 10557 Scope: SW 10559 DefaultTime2Wait= 10561 Default is 2. 10562 Result function is Maximum. 10564 The initiator and target negotiate the minimum time, in seconds, 10565 to wait before attempting an explicit/implicit logout or an active 10566 task reassignment after an unexpected connection termination or a 10567 connection reset. 10569 A value of 0 indicates that logout or active task reassignment can 10570 be attempted immediately. 10572 13.16. DefaultTime2Retain 10574 Use: LO 10575 Senders: Initiator and Target 10576 Scope: SW 10578 DefaultTime2Retain= 10580 Default is 20. 10581 Result function is Minimum. 10583 The initiator and target negotiate the maximum time, in seconds 10584 after an initial wait (Time2Wait), before which an active task 10585 reassignment is still possible after an unexpected connection 10586 termination or a connection reset. 10588 This value is also the session state timeout if the connection in 10589 question is the last LOGGED_IN connection in the session. 10591 A value of 0 indicates that connection/task state is immediately 10592 discarded by the target. 10594 13.17. MaxOutstandingR2T 10596 Use: LO 10597 Senders: Initiator and Target 10598 Scope: SW 10600 MaxOutstandingR2T= 10601 Irrelevant when: SessionType=Discovery 10603 Default is 1. 10604 Result function is Minimum. 10606 Initiator and target negotiate the maximum number of outstanding 10607 R2Ts per task, excluding any implied initial R2T that might be 10608 part of that task. An R2T is considered outstanding until the last 10609 data PDU (with the F bit set to 1) is transferred, or a sequence 10610 reception timeout (Section 7.1.4.1) is encountered for that data 10611 sequence. 10613 13.18. DataPDUInOrder 10615 Use: LO 10616 Senders: Initiator and Target 10617 Scope: SW 10618 Irrelevant when: SessionType=Discovery 10620 DataPDUInOrder= 10622 Default is Yes. 10623 Result function is OR. 10625 No is used by iSCSI to indicate that the data PDUs within 10626 sequences can be in any order. Yes is used to indicate that data 10627 PDUs within sequences have to be at continuously increasing 10628 addresses and overlays are forbidden. 10630 13.19. DataSequenceInOrder 10632 Use: LO 10633 Senders: Initiator and Target 10634 Scope: SW 10635 Irrelevant when: SessionType=Discovery 10637 DataSequenceInOrder= 10639 Default is Yes. 10640 Result function is OR. 10642 A Data Sequence is a sequence of Data-In or Data-Out PDUs that end 10643 with a Data-In or Data-Out PDU with the F bit set to one. A Data- 10644 out sequence is sent either unsolicited or in response to an R2T. 10645 Sequences cover an offset-range. 10647 If DataSequenceInOrder is set to No, Data PDU sequences may be 10648 transferred in any order. 10650 If DataSequenceInOrder is set to Yes, Data Sequences MUST be 10651 transferred using continuously non-decreasing sequence offsets 10652 (R2T buffer offset for writes, or the smallest SCSI Data-In buffer 10653 offset within a read data sequence). 10655 If DataSequenceInOrder is set to Yes, a target may retry at most 10656 the last R2T, and an initiator may at most request retransmission 10657 for the last read data sequence. For this reason, if 10658 ErrorRecoveryLevel is not 0 and DataSequenceInOrder is set to Yes 10659 then MaxOustandingR2T MUST be set to 1. 10661 13.20. ErrorRecoveryLevel 10663 Use: LO 10664 Senders: Initiator and Target 10665 Scope: SW 10666 ErrorRecoveryLevel= 10668 Default is 0. 10669 Result function is Minimum. 10671 The initiator and target negotiate the recovery level supported. 10673 Recovery levels represent a combination of recovery capabilities. 10674 Each recovery level includes all the capabilities of the lower 10675 recovery levels and adds some new ones to them. 10677 In the description of recovery mechanisms, certain recovery 10678 classes are specified. Section 7.1.5 describes the mapping between 10679 the classes and the levels. 10681 13.21. SessionType 10683 Use: LO, Declarative, Any-Stage 10684 Senders: Initiator 10685 Scope: SW 10687 SessionType= 10689 Default is Normal. 10691 The Initiator indicates the type of session it wants to create. 10692 The target can either accept it or reject it. 10694 A Discovery session indicates to the Target that the only purpose 10695 of this Session is discovery. The only requests a target accepts 10696 in this type of session are a text request with a SendTargets key 10697 and a logout request with reason "close the session". 10699 The Discovery session implies MaxConnections = 1 and overrides 10700 both the default and an explicit setting. As Section 7.4.1 10701 states, ErrorRecoveryLevel MUST be 0 (zero) for Discovery 10702 sessions. 10704 Depending on the type of the session, a target may decide on 10705 resources to allocate and the security to enforce, etc. for thion. 10706 If the SessionType key is thus going to be offered as "Discovery", 10708 it SHOULD be offered in the initial Login request by the 10709 initiator. 10711 13.22. The Private Extension Key Format 10713 Use: ALL 10714 Senders: Initiator and Target 10715 Scope: specific key dependent 10717 X-reversed.vendor.dns_name.do_something= 10719 Keys with this format are used for private extension purposes. 10720 These keys always start with X- if unregistered with IANA 10721 (private). New public keys (if registered with IANA via an IETF 10722 Review, [RFC5226]) no longer have an X# name prefix requirement, 10723 implementers may propose any intuitive unique name. 10725 For unregistered keys, to identify the vendor, we suggest you use 10726 the reversed DNS-name as a prefix to the key-proper. 10728 The part of key-name following X- MUST conform to the format for 10729 key-name specified in Section 6.1. 10731 Vendor specific keys MUST ONLY be used in normal sessions. 10733 Support for public or private extension keys is OPTIONAL. 10735 13.23. TaskReporting 10737 Use: LO 10738 Senders: Initiator and Target 10739 Scope: SW 10740 Irrelevant when: SessionType=Discovery 10741 TaskReporting= 10743 Default is RFC3720. 10744 Result function is AND. 10746 This key is used to negotiate the task completion reporting 10747 semantics from the SCSI target. The following table describes the 10748 semantics that an iSCSI target MUST support for respective 10749 negotiated key values. Whenever this key is negotiated, at least 10750 the RFC3720 and ResponseFence values MUST be offered as options by 10751 the negotiation originator. 10752 +--------------+------------------------------------------+ 10753 | Name | Description | 10754 +--------------+------------------------------------------+ 10755 | RFC3720 | RFC 3720-compliant semantics. Response | 10756 | | fencing is not guaranteed and fast | 10757 | | completion of multi-task aborting is not | 10758 | | supported | 10759 +--------------+------------------------------------------+ 10760 | ResponseFence| Response Fence (Section 4.2.2.3.3) | 10761 | | semantics MUST be supported in reporting | 10762 | | task completions | 10763 +--------------+------------------------------------------+ 10764 | FastAbort | Updated fast multi-task abort semantics | 10765 | | defined in Section 4.2.3.4 MUST be | 10766 | | supported. Support for Response Fence is | 10767 | | implied -- i.e., (Section 4.2.2.3.3) | 10768 | | semantics MUST be supported as well | 10769 +--------------+------------------------------------------+ 10770 When TaskReporting is not negotiated to FastAbort, the standard 10771 multi-task abort semantics in Section 4.2.3.3 MUST be used. 10773 13.24. iSCSIProtocolLevel Negotiation 10775 The iSCSIProtocolLevel associated with this document is "1". As a 10776 responder or an originator in a negotiation of this key, an iSCSI 10777 implementation compliant to this document alone, without any 10778 future protocol extensions, MUST use this value as defined by the 10779 [iSCSI-SAM] document. 10781 13.25. Obsoleted Keys 10783 This document obsoletes the following keys defined in [RFC3720]: 10784 IFMarker, OFMarker, OFMarkInt, IFMarkInt. However, iSCSI 10785 implementations compliant to this document may still receive these 10786 obsoleted keys - i.e. in a responder role - in a text negotiation. 10788 When IFMarker or OFMarker key is received, a compliant iSCSI 10789 implementation SHOULD respond with the constant "Reject" value. 10790 The implementation MAY alternatively respond with a "No" value. 10792 However, the implementation MUST NOT respond with a 10793 "NotUnderstood" value for either of these keys. 10795 When IFMarkInt or OFMarkInt key is received, a compliant iSCSI 10796 implementation MUST respond with the constant "Reject" value. 10797 The implementation MUST NOT respond with a "NotUnderstood" value 10798 for either of these keys. 10800 13.26. X#NodeArchitecture 10802 13.26.1. Definition 10804 Use: LO, Declarative 10805 Senders: Initiator and Target 10806 Scope: SW 10808 X#NodeArchitecture= 10810 Default is none. 10812 Examples: 10813 X#NodeArchitecture=ExampleOS/v1234,ExampleInc_SW_Initiator/1.05a 10814 X#NodeArchitecture=ExampleInc_HW_Initiator/4010,Firmware/2.0.0.5 10815 X#NodeArchitecture=ExampleInc_SW_Initiator/2.1,CPU_Arch/i686 10817 This document does not define the structure or content of the list 10818 of values. 10820 The initiator or target declares the details of its iSCSI node 10821 architecture to the remote endpoint. These details may include, 10822 but are not limited to, iSCSI vendor software, firmware, or 10823 hardware versions, the OS version, or hardware architecture. This 10824 key may be declared on a Discovery session or a Normal session. 10826 The length of the key value (total length of the list-of-values) 10827 MUST NOT be greater than 255 bytes. 10829 X#NodeArchitecture MUST NOT be redeclared during the login phase. 10831 13.26.2. Implementation Requirements 10833 Functional behavior of the iSCSI node (this includes the iSCSI 10834 protocol logic -- the SCSI, iSCSI, and TCP/IP protocols) MUST NOT 10835 depend on the presence, absence, or content of the 10836 X#NodeArchitecture key. The key MUST NOT be used by iSCSI nodes 10837 for interoperability, or exclusion of other nodes. To ensure 10838 proper use, key values SHOULD be set by the node itself, and there 10839 SHOULD NOT be provisions for the key values to contain user- 10840 defined text. 10842 Nodes implementing this key MUST choose one of the following 10843 implementation options: 10845 - only transmit the key, 10847 - only log the key values received from other nodes, or 10849 - both transmit and log the key values. 10851 Each node choosing to implement transmission of the key values 10852 MUST be prepared to handle the response of iSCSI Nodes that do not 10853 understand the key. 10855 Nodes that implement transmission and/or logging of the key values 10856 may also implement administrative mechanisms that disable and/or 10857 change the logging and key transmission detail (see Section 9.4). 10858 Thus, a valid behavior for this key may be that a node is 10859 completely silent (the node does not transmit any key value, and 10860 simply discards any key values it receives without issuing a 10861 NotUnderstood response). 10863 14. Rationale for revised IANA Considerations 10865 This document makes rather significant changes in this area, and 10866 this Section outlines the reasons behind the changes. As 10867 previously specified in [RFC3720], iSCSI had used text string 10868 prefixes, such as X- and X#, to distinguish extended login/text 10869 keys, digest algorithms and authentication methods from their 10870 standardized counterparts. Based on experience with other 10871 protocols, [RFC6648] however strongly recommends against this 10872 practice, in large part because extensions that use such prefixes 10873 may become standard over time at which point it can be infeasible 10874 to change their text string names due to widespread usage under 10875 the existing text string name. 10877 iSCSI's experience with public extensions supports the 10878 recommendations in [RFC6648], as the only extension item ever 10879 registered with IANA, the X#NodeArchitecture key, was specified as 10880 a standard key in a standards-track RFC [RFC 4850], and hence did 10881 not require the X# prefix. In addition, that key is the only 10882 public iSCSI extension that has been registered with IANA since 10883 RFC 3720 was originally published, so there has been effectively 10884 no use of the X#, Y# and Z# public extension formats. 10886 Therefore, this document makes the following changes to the IANA 10887 registration procedures for iSCSI: 10889 (1) The separate registries for X#, Y# and Z# public 10890 extensions are removed. The single entry in the registry for 10891 X# login/text keys(X#NodeArchitecture) is transferred to the 10892 main login/text key registry. IANA has never created the 10893 latter two registries because there have been no 10894 registration requests for them. These public extension 10895 formats (X#, Y#, Z#) MUST NOT be used with the exception of 10896 the existing X#NodeArchitecture key. 10898 (2) The Registration Procedures for the main login/text key, 10899 digest algorithm and authentication method IANA registries 10900 are changed to IETF Review [RFC5226] for possible future 10901 extensions to iSCSI. This change includes a deliberate 10902 decision to remove the possibility of specifying an IANA- 10903 registered iSCSI extension in an RFC published via an RFC 10905 Editor independent submission, as the level of review in 10906 that process is insufficient for iSCSI extensions. 10908 (3) The restriction against registering items using the 10909 private extension formats (X-, Y-, Z-) in the main IANA 10910 registries is removed. Extensions using these formats MAY be 10911 registered under the IETF Review registration procedures, 10912 but each format is restricted to the type of extension for 10913 which it is specified in this RFC and MUST NOT be used for 10914 other types. For example, the X- extension format for 10915 extension login/text keys MUST NOT be used for digest 10916 algorithms or authentication methods. 10918 15. IANA Considerations 10920 The well-known TCP port number for iSCSI connections assigned by 10921 IANA is 3260 and this is the default iSCSI port. Implementations 10922 needing a system TCP port number may use port 860, the port 10923 assigned by IANA as the iSCSI system port; however in order to use 10924 port 860, it MUST be explicitly specified - implementations MUST 10925 NOT default to use of port 860, as 3260 is the only allowed 10926 default. 10928 IANA is requested to update all references to RFC 3720, RFC 4850 10929 and RFC 5048 to instead reference this RFC in all of the iSCSI 10930 registries that are part of the "Internet Small Computer System 10931 Interface (iSCSI) Parameters" set of registries. This change 10932 reflects the fact that those three RFCs are obsoleted by this RFC. 10933 References to other RFCs that are not being obsoleted (e.g., RFC 10934 3723, RFC 5046) should not be changed. 10936 IANA is requested to perform the following actions on the iSCSI 10937 Login/Text Keys registry: 10939 - Change the registration procedure to IETF Review from 10940 Standard Required. 10942 - Change the RFC 5048 reference for the registry to reference 10943 this RFC. 10945 - Add the X#NodeArchitecture Key from the iSCSI extended key 10946 registry and change its reference to this RFC. 10948 - Change all references of RFC 3720 and RFC 5048 to reference 10949 this RFC. 10951 IANA is requested to change the Registration Procedures for the 10952 iSCSI authentication methods and iSCSI digests registries to IETF 10953 Review from RFC Required. 10955 IANA is requested to remove the iSCSI extended key registry, as 10956 its one entry is to be added to the iSCSI login/text keys 10957 registry. 10959 IANA is requested to mark obsolete the values 4 and 5, for SPKM1 10960 and SPKM2 respectively, in the iSCSI authentication methods 10961 subregistry of the Internet Small Computer System Interface 10962 (iSCSI) Parameters registries. 10964 All the other IANA considerations stated in [RFC3720] and 10965 [RFC5048] remain unchanged. 10967 This document obsoletes the SPKM1 and SPKM2 key values for the 10968 AuthMethod text key. Consequently, the SPKM_ text key prefix MUST 10969 be treated as obsolete and be not reused. 10971 IANA is requested to add the following entry to the "iSCSI 10972 Protocol Level" registry created by Section 9 of [iSCSI-SAM]: 10974 Assigned value: 1 10975 RFC Reference: [RFCyyyy] 10977 RFC Editor: Please replace yyyy in the above reference with the 10978 RFC number assigned to this document and remove this note. 10980 Expert Review of this assignment has been performed by David Black 10981 in his role as the T10 Liaison to IETF. The value 1 is part of 10982 the initial contents of this registry; for that reason, IANA is 10983 instructed to assign the value 1 as indicated above and apply the 10984 sequential assignment policy for this registry (as specified in 10985 [iSCSI-SAM]) to future assignments, starting with the value 3. 10987 References 10989 Normative References 10991 [EUI] "Guidelines for 64-bit Global Identifier (EUI-64)", 10992 http://standards.ieee.org/regauth/oui/tutorials/EUI64.html 10994 [FC-FS3] INCITS 470-2011, Fibre Channel - Framing and 10995 Signaling - 3 (FC-FS-3). 10997 [iSCSI-SAM] Knight, F., Chadalapaka, M., "Internet Small 10998 Computer Systems Interface (iSCSI) SCSI Architecture 10999 Features Update", draft-ietf-storm-iscsi-sam-06.txt (work in 11000 progress), July 2012 11002 [OUI] "IEEE OUI and Company_Id Assignments", 11003 http://standards.ieee.org/regauth/oui 11005 [RFC1122] R.Braden, "Requirements for Internet Hosts -- 11006 Communication Layers", October 1989. 11008 [RFC1964] J. Linn, "The Kerberos Version 5 GSS-API Mechanism", 11009 June 1996. 11011 [RFC1982] Elz, R., Bush, R., "Serial Number Arithmetic", 11012 August 1996. 11014 [RFC1994] W. Simpson, "PPP Challenge Handshake Authentication 11015 Protocol (CHAP)", August 1996. 11017 [RFC2119] Bradner, S. "Key Words for use in RFCs to Indicate 11018 Requirement Levels", BCP 14, March 1997. 11020 [RFC2404] C. Madson, R. Glenn, "The Use of HMAC-SHA-1-96 11021 within ESP and AH", November 1998. 11023 [RFC2451] R. Pereira, R. Adams "The ESP CBC-Mode Cipher 11024 Algorithms". 11026 [RFC2945] Wu, T., "The SRP Authentication and Key Exchange 11027 System", September 2000. 11029 [RFC3454] Hoffman, P. and M. Blanchet, "Preparation of 11030 Internationalized Strings ("stringprep")", RFC 3454, 11031 December 2002. 11033 [RFC3566] Frankel, S. and H. Herbert, "The AES-XCBC-MAC-96 11034 Algorithm and Its Use With IPsec", RFC 3566, September 2003. 11036 [RFC3629] Yergeau, F., "UTF-8, a Transformation Format of ISO 11037 10646", RFC 3629, November 2003 11039 [RFC3686] Housley, R., "Using Advanced Encryption Standard 11040 (AES) Counter Mode with IPsec Encapsulating Security Payload 11041 (ESP)", RFC 3686, January 2004. 11043 [RFC3722] Bakke, M., "String Profile for Internet Small 11044 Computer Systems Interface (iSCSI) Names", RFC 3722, March 11045 2004. 11047 [RFC3723] Aboba, B., Tseng, J., Walker, J., Rangan, V. and F. 11048 Travostino, "Securing Block Storage Protocols over IP", RFC 11049 3723, March 2004. 11051 [RFC3986] T. Berners-Lee, R. Fielding, L. Masinter "Uniform 11052 Resource Identifier (URI): Generic Syntax", January 2005. 11054 [RFC4106] J. Viega, D. McGrew, "The Use of Galois/Counter Mode 11055 (GCM) in IPsec Encapsulating Security Payload (ESP)", RFC 11056 4106, June 2005. 11058 [RFC4120] Neuman, C., Yu, T., Hartman, S., Raeburn, K, "The 11059 Kerberos Network Authentication Service (V5)", RFC 4120, 11060 July 2005. 11062 [RFC4171] J. Tseng, K. Gibbons, F. Travostino, C. Du Laney, J. 11063 Souza, "Internet Storage Name Service (iSNS)", September 11064 2005. 11066 [RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing 11067 Architecture", February 2006. 11069 [RFC4301] S. Kent, K.Seo, "Security Architecture for the 11070 Internet Protocol", December 2005. 11072 [RFC4303] Kent, S., "IP Encapsulating Security Payload (ESP)", 11073 RFC 4303, December 2005 11075 [RFC4543] D. McGrew, J. Viega, "The Use of Galois Message 11076 Authentication Code (GMAC) in IPsec ESP and AH", RFC 4543, 11077 May 2006 11079 [RFC4648] S. Josefsson, "The Base16, Base32, and Base64 Data 11080 Encodings", RFC 4648, October 2006 11082 [RFC5226] H. Alvestrand, T. Narten, "Guidelines for Writing an 11083 IANA Considerations Section in RFCs", RFC 5226, May 2008 11085 [RFC5996] C. Kaufman, P. Hoffman, Y. Nir, P. Eronen, "Internet 11086 Key Exchange Protocol Version 2 (IKEv2) ", RFC 5996, 11087 September 2010. 11089 [SAM2] T10/1157-D, SCSI Architecture Model - 2 (SAM-2). 11091 [SAM4] T10/1683-D, SCSI Architecture Model - 4 (SAM-4). 11093 [SPC2] T10/1236-D, SCSI Primary Commands-2. 11095 [SPC3] T10/1416-D, SCSI Primary Commands-3. 11097 [UML] ISO/IEC 19501, Unified Modeling Language 11098 Specification Version 1.4.2. 11100 [UNICODE] Unicode Standard Annex #15, "Unicode Normalization 11101 Forms", http://www.unicode.org/unicode/reports/tr15 11103 Informative References 11105 [FC-SP-2] T11/1835-D, Fibre Channel Security Protocols- 2 (FC- 11106 SP-2). 11108 [RFC1737] K. Sollins, L. Masinter "Functional Requirements for 11109 Uniform Resource Names". 11111 [RFC5433] T. Clancy, H. Tschofenig "Extensible Authentication 11112 Protocol - Generalized Pre-Shared Key (EAP-GPSK) Method", 11113 RFC 5433, February 2009. 11115 [IB] InfiniBand{tm} Architecture Specification, Vol. 1, 11116 Rel.1.0.a, InfiniBand Trade 11117 Association(http://www.infinibandta.org). 11119 [Castagnoli93] G. Castagnoli, S. Braeuer and M. Herrman 11120 "Optimization of Cyclic Redundancy-Check Codes with 24 and 11121 32 Parity Bits", IEEE Transact. on Communications, Vol. 41, 11122 No. 6, June 1993. 11124 [CRC] ISO 3309, High-Level Data Link Control (CRC 32). 11126 [RFC2401] S. Kent, R. Atkinson, "Security Architecture for the 11127 Internet Protocol ", November 1998. 11129 [RFC2406] S. Kent, R. Atkinson, "IP Encapsulating Security 11130 Payload (ESP)", November 1998. 11132 [RFC2407] D. Piper, "The Internet IP Security Domain of 11133 Interpretation for ISAKMP", November 1998. 11135 [RFC2409] D. Harkins, D. Carrel, "The Internet Key Exchange 11136 (IKE)", November 1998. 11138 [RFC2608] E. Guttman, C. Perkins, J. Veizades, M. Day, 11139 "Service Location Protocol, Version 2", June 1999. 11141 [RFC2865] C. Rigney, S. Willens, A. Rubens, W. Simpson, 11142 "Remote Authentication Dial In User Service (RADIUS)", June 11143 2000. 11145 [RFC3385] Sheinwald, D., Staran, J., Thaler, P. and V. 11146 Cavanna, "Internet Protocol Small Computer System Interface 11147 (iSCSI) Cyclic Redundancy Check (CRC)/Checksum 11148 Considerations", RFC 3385, September 2002. 11150 [RFC3720] Satran, J., Meth, K., Sapuntzakis, C., Chadalapaka, 11151 M., and E. Zeidner, "Internet Small Computer Systems 11152 Interface (iSCSI)", RFC 3720, April 2004. 11154 [RFC3721] Bakke, M., Hafner, J., Hufferd, J., Voruganti, K. 11155 and M. Krueger, "Internet Small Computer Systems Interface 11156 (iSCSI) Naming and Discovery", RFC 3721, March 2004 11158 [RFC3783] M. Chadalapaka, R. Elliott, "Small Computer Systems 11159 Interface (SCSI) Command Ordering Considerations with 11160 iSCSI", RFC 3783, May 2004. 11162 [RFC4297] Romanow, A., Mogul, J., Talpey, T., and S. Bailey, 11163 "Remote Direct Memory Access (RDMA) over IP Problem 11164 Statement", RFC 4297, October 2004 11166 [RFC4850] Wysochanski, D., "Declarative Public Extension Key 11167 for Internet Small Computer Systems Interface (iSCSI) Node 11168 Architecture", RFC 4850, April 2007. 11170 [RFC5046] Ko, M., Chadalapaka, M., Hufferd, J., Elzur, U., 11171 Shah, H., and P. Thaler, "Internet Small Computer System 11172 Interface (iSCSI) Extensions for Remote Direct Memory Access 11173 (RDMA)", RFC 5046, October 2007 11175 [RFC5048] Chadalapaka, M., "Internet Small Computer Systems 11176 Interface (iSCSI) Corrections and Clarifications", RFC 5048, 11177 October 2007. 11179 [RFC6648] P. Saint-Andre, D. Crocker, M. Nottingham, 11180 "Deprecating the X- Prefix and Similar Constructs in 11181 Application Protocols", RFC 6648, June 2012 11183 [SAS] T10/2125-D, Serial Attached SCSI - 2.1 (SAS-2.1); 11184 T10/2124-D, SAS Protocol Layer (SPL); T10/2124-M, SAS 11185 Protocol Layer (SPL) Amendment #1 (SPL AM1). 11187 [SBC2] NCITS.405-205, SCSI Block Commands - 2 (SBC-2). 11189 [SPC4] T10/1731-D, SCSI Primary Commands-4. 11191 Appendix A. Examples 11193 Read Operation Example 11195 +------------------+-----------------------+---------------------+ 11196 |Initiator Function| PDU Type | Target Function | 11197 +------------------+-----------------------+---------------------+ 11198 | Command request |SCSI Command (READ)>>> | | 11199 | (read) | | | 11200 +------------------+-----------------------+---------------------+ 11201 | | |Prepare Data Transfer| 11202 +------------------+-----------------------+---------------------+ 11203 | Receive Data | <<< SCSI Data-in | Send Data | 11204 +------------------+-----------------------+---------------------+ 11205 | Receive Data | <<< SCSI Data-in | Send Data | 11206 +------------------+-----------------------+---------------------+ 11207 | Receive Data | <<< SCSI Data-in | Send Data | 11208 +------------------+-----------------------+---------------------+ 11209 | | <<< SCSI Response |Send Status and Sense| 11210 +------------------+-----------------------+---------------------+ 11211 | Command Complete | | | 11212 +------------------+-----------------------+---------------------+ 11214 Write Operation Example 11216 +------------------+-----------------------+---------------------+ 11217 |Initiator Function| PDU Type | Target Function | 11218 +------------------+-----------------------+---------------------+ 11219 | Command request |SCSI Command (WRITE)>>>| Receive command | 11220 | (write) | | and queue it | 11221 +------------------+-----------------------+---------------------+ 11222 | | | Process old commands| 11223 +------------------+-----------------------+---------------------+ 11224 | | | Ready to process | 11225 | | <<< R2T | WRITE command | 11226 +------------------+-----------------------+---------------------+ 11227 | Send Data | SCSI Data-out >>> | Receive Data | 11228 +------------------+-----------------------+---------------------+ 11229 | | <<< R2T | Ready for data | 11230 +------------------+-----------------------+---------------------+ 11231 | | <<< R2T | Ready for data | 11232 +------------------+-----------------------+---------------------+ 11233 | Send Data | SCSI Data-out >>> | Receive Data | 11234 +------------------+-----------------------+---------------------+ 11235 | Send Data | SCSI Data-out >>> | Receive Data | 11236 +------------------+-----------------------+---------------------+ 11237 | | <<< SCSI Response |Send Status and Sense| 11238 +------------------+-----------------------+---------------------+ 11239 | Command Complete | | | 11240 +------------------+-----------------------+---------------------+ 11242 R2TSN/DataSN Use Examples 11244 Output (write) data DataSN/R2TSN Example 11245 +------------------+-----------------------+---------------------+ 11246 |Initiator Function| PDU Type & Content | Target Function | 11247 +------------------+-----------------------+---------------------+ 11248 | Command request |SCSI Command (WRITE)>>>| Receive command | 11249 | (write) | | and queue it | 11250 +------------------+-----------------------+---------------------+ 11251 | | | Process old commands| 11252 +------------------+-----------------------+---------------------+ 11253 | | <<< R2T | Ready for data | 11254 | | R2TSN = 0 | | 11255 +------------------+-----------------------+---------------------+ 11256 | | <<< R2T | Ready for more data | 11257 | | R2TSN = 1 | | 11258 +------------------+-----------------------+---------------------+ 11259 | Send Data | SCSI Data-out >>> | Receive Data | 11260 | for R2TSN 0 | DataSN = 0, F=0 | | 11261 +------------------+-----------------------+---------------------+ 11262 | Send Data | SCSI Data-out >>> | Receive Data | 11263 | for R2TSN 0 | DataSN = 1, F=1 | | 11264 +------------------+-----------------------+---------------------+ 11265 | Send Data | SCSI Data >>> | Receive Data | 11266 | for R2TSN 1 | DataSN = 0, F=1 | | 11267 +------------------+-----------------------+---------------------+ 11268 | | <<< SCSI Response |Send Status and Sense| 11269 | | ExpDataSN = 0 | | 11270 +------------------+-----------------------+---------------------+ 11271 | Command Complete | | | 11272 +------------------+-----------------------+---------------------+ 11274 Input (read) data DataSN Example 11276 +------------------+-----------------------+---------------------+ 11277 |Initiator Function| PDU Type | Target Function | 11278 +------------------+-----------------------+---------------------+ 11279 | Command request |SCSI Command (READ)>>> | | 11280 | (read) | | | 11281 +------------------+-----------------------+---------------------+ 11282 | | |Prepare Data Transfer| 11283 +------------------+-----------------------+---------------------+ 11284 | Receive Data | <<< SCSI Data-in | Send Data | 11285 | | DataSN = 0, F=0 | | 11286 +------------------+-----------------------+---------------------+ 11287 | Receive Data | <<< SCSI Data-in | Send Data | 11288 | | DataSN = 1, F=0 | | 11289 +------------------+-----------------------+---------------------+ 11290 | Receive Data | <<< SCSI Data-in | Send Data | 11291 | | DataSN = 2, F=1 | | 11292 +------------------+-----------------------+---------------------+ 11293 | | <<< SCSI Response |Send Status and Sense| 11294 | | ExpDataSN = 3 | | 11295 +------------------+-----------------------+---------------------+ 11296 | Command Complete | | | 11297 +------------------+-----------------------+---------------------+ 11299 Bidirectional DataSN Example 11301 +------------------+-----------------------+---------------------+ 11302 |Initiator Function| PDU Type | Target Function | 11303 +------------------+-----------------------+---------------------+ 11304 | Command request |SCSI Command >>> | | 11305 | (Read-Write) | Read-Write | | 11306 +------------------+-----------------------+---------------------+ 11307 | | | Process old commands| 11308 +------------------+-----------------------+---------------------+ 11309 | | <<< R2T | Ready to process | 11310 | | R2TSN = 0 | WRITE command | 11311 +------------------+-----------------------+---------------------+ 11312 | * Receive Data | <<< SCSI Data-in | Send Data | 11313 | | DataSN = 0, F=0 | | 11314 +------------------+-----------------------+---------------------+ 11315 | * Receive Data | <<< SCSI Data-in | Send Data | 11316 | | DataSN = 1, F=1 | | 11317 +------------------+-----------------------+---------------------+ 11318 | * Send Data | SCSI Data-out >>> | Receive Data | 11319 | for R2TSN 0 | DataSN = 0, F=1 | | 11320 +------------------+-----------------------+---------------------+ 11321 | | <<< SCSI Response |Send Status and Sense| 11322 | | ExpDataSN = 2 | | 11323 +------------------+-----------------------+---------------------+ 11324 | Command Complete | | | 11325 +------------------+-----------------------+---------------------+ 11327 *) Send data and Receive Data may be transferred simultaneously as 11328 in an atomic Read-Old-Write-New or sequentially as in an atomic 11329 Read-Update-Write (in the latter case the R2T may follow the 11330 received data). 11332 Unsolicited and immediate output (write) data with DataSN Example 11333 +------------------+-----------------------+---------------------+ 11334 |Initiator Function| PDU Type & Content | Target Function | 11335 +------------------+-----------------------+---------------------+ 11336 | Command request |SCSI Command (WRITE)>>>| Receive command | 11337 | (write) |F=0 | and data | 11338 |+ immediate data | | and queue it | 11339 +------------------+-----------------------+---------------------+ 11340 | Send Unsolicited | SCSI Write Data >>> | Receive more Data | 11341 | Data | DataSN = 0, F=1 | | 11342 +------------------+-----------------------+---------------------+ 11343 | | | Process old commands| 11344 +------------------+-----------------------+---------------------+ 11345 | | <<< R2T | Ready for more data | 11346 | | R2TSN = 0 | | 11347 +------------------+-----------------------+---------------------+ 11348 | Send Data | SCSI Write Data >>> | Receive Data | 11349 | for R2TSN 0 | DataSN = 0, F=1 | | 11350 +------------------+-----------------------+---------------------+ 11351 | | <<< SCSI Response |Send Status and Sense| 11352 | | | | 11353 +------------------+-----------------------+---------------------+ 11354 | Command Complete | | | 11355 +------------------+-----------------------+---------------------+ 11357 CRC Examples 11359 N.B. all Values are Hexadecimal 11361 32 bytes of zeroes: 11363 Byte: 0 1 2 3 11365 0: 00 00 00 00 11366 ... 11367 28: 00 00 00 00 11369 CRC: aa 36 91 8a 11371 32 bytes of ones: 11373 Byte: 0 1 2 3 11374 0: ff ff ff ff 11375 ... 11376 28: ff ff ff ff 11378 CRC: 43 ab a8 62 11380 32 bytes of incrementing 00..1f: 11382 Byte: 0 1 2 3 11384 0: 00 01 02 03 11385 ... 11386 28: 1c 1d 1e 1f 11388 CRC: 4e 79 dd 46 11390 32 bytes of decrementing 1f..00: 11392 Byte: 0 1 2 3 11394 0: 1f 1e 1d 1c 11395 ... 11396 28: 03 02 01 00 11398 CRC: 5c db 3f 11 11400 An iSCSI - SCSI Read (10) Command PDU 11402 Byte: 0 1 2 3 11404 0: 01 c0 00 00 11405 4: 00 00 00 00 11406 8: 00 00 00 00 11407 12: 00 00 00 00 11408 16: 14 00 00 00 11409 20: 00 00 04 00 11410 24: 00 00 00 14 11411 28: 00 00 00 18 11412 32: 28 00 00 00 11413 36: 00 00 00 00 11414 40: 02 00 00 00 11415 44: 00 00 00 00 11417 CRC: 56 3a 96 d9 11419 Appendix B. Login Phase Examples 11421 In the first example, the initiator and target authenticate each 11422 other via Kerberos: 11424 I-> Login (CSG,NSG=0,1 T=1) 11425 InitiatorName=iqn.1999-07.com.os:hostid.77 11426 TargetName=iqn.1999-07.com.example:diskarray.sn.88 11427 AuthMethod=KRB5,SRP,None 11429 T-> Login (CSG,NSG=0,0 T=0) 11430 AuthMethod=KRB5 11432 I-> Login (CSG,NSG=0,1 T=1) 11433 KRB_AP_REQ= 11435 (krb_ap_req contains the Kerberos V5 ticket and authenticator with 11436 MUTUAL-REQUIRED set in the ap-options field) 11438 If the authentication is successful, the target proceeds with: 11440 T-> Login (CSG,NSG=0,1 T=1) 11441 KRB_AP_REP= 11443 (krb_ap_rep is the Kerberos V5 mutual authentication reply) 11445 If the authentication is successful, the initiator may proceed 11446 with: 11448 I-> Login (CSG,NSG=1,0 T=0) FirstBurstLength=8192 11449 T-> Login (CSG,NSG=1,0 T=0) FirstBurstLength=4096 11450 MaxBurstLength=8192 11451 I-> Login (CSG,NSG=1,0 T=0) MaxBurstLength=8192 11452 ... more iSCSI Operational Parameters 11454 T-> Login (CSG,NSG=1,0 T=0) 11455 ... more iSCSI Operational Parameters 11457 And at the end: 11459 I-> Login (CSG,NSG=1,3 T=1) 11460 optional iSCSI parameters 11462 T-> Login (CSG,NSG=1,3 T=1) "login accept" 11464 If the initiator's authentication by the target is not successful, 11465 the target responds with: 11467 T-> Login "login reject" 11469 instead of the Login KRB_AP_REP message, and terminates the 11470 connection. 11472 If the target's authentication by the initiator is not successful, 11473 the initiator terminates the connection (without responding to the 11474 Login KRB_AP_REP message). 11476 In the next example only the initiator is authenticated by the 11477 target via Kerberos: 11479 I-> Login (CSG,NSG=0,1 T=1) 11480 InitiatorName=iqn.1999-07.com.os:hostid.77 11481 TargetName=iqn.1999-07.com.example:diskarray.sn.88 11482 AuthMethod=SRP,KRB5,None 11484 T-> Login-PR (CSG,NSG=0,0 T=0) 11485 AuthMethod=KRB5 11487 I-> Login (CSG,NSG=0,1 T=1) 11488 KRB_AP_REQ=krb_ap_req 11490 (MUTUAL-REQUIRED not set in the ap-options field of krb_ap_req) 11492 If the authentication is successful, the target proceeds with: 11494 T-> Login (CSG,NSG=0,1 T=1) 11496 I-> Login (CSG,NSG=1,0 T=0) 11497 ... iSCSI parameters 11499 T-> Login (CSG,NSG=1,0 T=0) 11500 ... iSCSI parameters 11502 . . . 11504 T-> Login (CSG,NSG=1,3 T=1)"login accept" 11506 In the next example, the initiator and target authenticate each 11507 other via SRP: 11509 I-> Login (CSG,NSG=0,1 T=1) 11510 InitiatorName=iqn.1999-07.com.os:hostid.77 11511 TargetName=iqn.1999-07.com.example:diskarray.sn.88 11512 AuthMethod=KRB5,SRP,None 11514 T-> Login-PR (CSG,NSG=0,0 T=0) 11515 AuthMethod=SRP 11517 I-> Login (CSG,NSG=0,0 T=0) 11518 SRP_U= 11519 TargetAuth=Yes 11521 T-> Login (CSG,NSG=0,0 T=0) 11522 SRP_N= 11523 SRP_g= 11524 SRP_s= 11526 I-> Login (CSG,NSG=0,0 T=0) 11527 SRP_A= 11529 T-> Login (CSG,NSG=0,0 T=0) 11530 SRP_B= 11532 I-> Login (CSG,NSG=0,1 T=1) 11533 SRP_M= 11535 If the initiator authentication is successful, the target 11536 proceeds: 11538 T-> Login (CSG,NSG=0,1 T=1) 11539 SRP_HM= 11541 Where N, g, s, A, B, M, and H(A | M | K) are defined in 11542 [RFC2945]. 11544 If the target authentication is not successful, the initiator 11545 terminates the connection; otherwise, it proceeds. 11547 I-> Login (CSG,NSG=1,0 T=0) 11548 ... iSCSI parameters 11550 T-> Login (CSG,NSG=1,0 T=0) 11551 ... iSCSI parameters 11553 And at the end: 11555 I-> Login (CSG,NSG=1,3 T=1) 11556 optional iSCSI parameters 11558 T-> Login (CSG,NSG=1,3 T=1) "login accept" 11560 If the initiator authentication is not successful, the target 11561 responds with: 11563 T-> Login "login reject" 11565 Instead of the T-> Login SRP_HM= message and 11566 terminates the connection. 11568 In the next example, only the initiator is authenticated by the 11569 target via SRP: 11571 I-> Login (CSG,NSG=0,1 T=1) 11572 InitiatorName=iqn.1999-07.com.os:hostid.77 11573 TargetName=iqn.1999-07.com.example:diskarray.sn.88 11574 AuthMethod=KRB5,SRP,None 11576 T-> Login-PR (CSG,NSG=0,0 T=0) 11577 AuthMethod=SRP 11579 I-> Login (CSG,NSG=0,0 T=0) 11580 SRP_U= 11581 TargetAuth=No 11583 T-> Login (CSG,NSG=0,0 T=0) 11584 SRP_N= 11585 SRP_g= 11586 SRP_s= 11588 I-> Login (CSG,NSG=0,0 T=0) 11589 SRP_A= 11591 T-> Login (CSG,NSG=0,0 T=0) 11592 SRP_B= 11594 I-> Login (CSG,NSG=0,1 T=1) 11595 SRP_M= 11597 If the initiator authentication is successful, the target 11598 proceeds: 11600 T-> Login (CSG,NSG=0,1 T=1) 11602 I-> Login (CSG,NSG=1,0 T=0) 11604 ... iSCSI parameters 11606 T-> Login (CSG,NSG=1,0 T=0) 11608 ... iSCSI parameters 11610 And at the end: 11612 I-> Login (CSG,NSG=1,3 T=1) 11614 optional iSCSI parameters 11616 T-> Login (CSG,NSG=1,3 T=1) "login accept" 11618 In the next example the initiator and target authenticate each 11619 other via CHAP: 11621 I-> Login (CSG,NSG=0,0 T=0) 11623 InitiatorName=iqn.1999-07.com.os:hostid.77 11625 TargetName=iqn.1999-07.com.example:diskarray.sn.88 11627 AuthMethod=KRB5,CHAP,None 11629 T-> Login-PR (CSG,NSG=0,0 T=0) 11631 AuthMethod=CHAP 11633 I-> Login (CSG,NSG=0,0 T=0) 11635 CHAP_A= 11637 T-> Login (CSG,NSG=0,0 T=0) 11638 CHAP_A= 11639 CHAP_I= 11640 CHAP_C= 11642 I-> Login (CSG,NSG=0,1 T=1) 11643 CHAP_N= 11645 CHAP_R= 11647 CHAP_I= 11649 CHAP_C= 11651 If the initiator authentication is successful, the target 11652 proceeds: 11654 T-> Login (CSG,NSG=0,1 T=1) 11656 CHAP_N= 11658 CHAP_R= 11660 If the target authentication is not successful, the initiator 11661 aborts the connection; otherwise, it proceeds. 11663 I-> Login (CSG,NSG=1,0 T=0) 11665 ... iSCSI parameters 11667 T-> Login (CSG,NSG=1,0 T=0) 11669 ... iSCSI parameters 11671 And at the end: 11673 I-> Login (CSG,NSG=1,3 T=1) 11675 optional iSCSI parameters 11677 T-> Login (CSG,NSG=1,3 T=1) "login accept" 11679 If the initiator authentication is not successful, the target 11680 responds with: 11682 T-> Login "login reject" 11684 Instead of the Login CHAP_R= "proceed and change 11685 stage" message and terminates the connection. 11687 In the next example, only the initiator is authenticated by the 11688 target via CHAP: 11690 I-> Login (CSG,NSG=0,1 T=0) 11692 InitiatorName=iqn.1999-07.com.os:hostid.77 11694 TargetName=iqn.1999-07.com.example:diskarray.sn.88 11696 AuthMethod=KRB5,CHAP,None 11698 T-> Login-PR (CSG,NSG=0,0 T=0) 11700 AuthMethod=CHAP 11702 I-> Login (CSG,NSG=0,0 T=0) 11704 CHAP_A= 11706 T-> Login (CSG,NSG=0,0 T=0) 11707 CHAP_A= 11708 CHAP_I= 11709 CHAP_C= 11711 I-> Login (CSG,NSG=0,1 T=1) 11713 CHAP_N= 11715 CHAP_R= 11717 If the initiator authentication is successful, the target 11718 proceeds: 11720 T-> Login (CSG,NSG=0,1 T=1) 11722 I-> Login (CSG,NSG=1,0 T=0) 11724 ... iSCSI parameters 11726 T-> Login (CSG,NSG=1,0 T=0) 11728 ... iSCSI parameters 11730 And at the end: 11732 I-> Login (CSG,NSG=1,3 T=1) 11734 optional iSCSI parameters 11736 T-> Login (CSG,NSG=1,3 T=1) "login accept" 11738 In the next example, the initiator does not offer any security 11739 parameters. It therefore may offer iSCSI parameters on the Login 11740 PDU with the T bit set to 1, and the target may respond with a 11741 final Login Response PDU immediately: 11743 I-> Login (CSG,NSG=1,3 T=1) 11745 InitiatorName=iqn.1999-07.com.os:hostid.77 11747 TargetName=iqn.1999-07.com.example:diskarray.sn.88 11749 ... iSCSI parameters 11751 T-> Login (CSG,NSG=1,3 T=1) "login accept" 11753 ... ISCSI parameters 11755 In the next example, the initiator does offer security 11756 parameters on the Login PDU, but the target does not choose 11757 any (i.e., chooses the "None" values): 11759 I-> Login (CSG,NSG=0,1 T=1) 11761 InitiatorName=iqn.1999-07.com.os:hostid.77 11763 TargetName=iqn.1999-07.com.example:diskarray.sn.88 11765 AuthMethod=KRB5,SRP,None 11767 T-> Login-PR (CSG,NSG=0,1 T=1) 11769 AuthMethod=None 11771 I-> Login (CSG,NSG=1,0 T=0) 11773 ... iSCSI parameters 11775 T-> Login (CSG,NSG=1,0 T=0) 11777 ... iSCSI parameters 11779 And at the end: 11781 I-> Login (CSG,NSG=1,3 T=1) 11783 optional iSCSI parameters 11785 T-> Login (CSG,NSG=1,3 T=1) "login accept" 11787 Appendix C. SendTargets Operation 11789 The text in this Appendix is a normative part of this document. 11791 To reduce the amount of configuration required on an initiator, 11792 iSCSI provides the SendTargets text request. The initiator uses 11793 the SendTargets request to get a list of targets to which it may 11794 have access, as well as the list of addresses (IP address and TCP 11795 port) on which these targets may be accessed. 11797 To make use of SendTargets, an initiator must first establish one 11798 of two types of sessions. If the initiator establishes 11799 the session using the key "SessionType=Discovery", the session is 11800 a discovery session, and a target name does not need to be 11801 specified. Otherwise, the session is a normal, operational 11802 session. The SendTargets command MUST only be sent during the 11803 Full Feature Phase of a normal or discovery session. 11805 A system that contains targets MUST support discovery sessions on 11806 each of its iSCSI IP address-port pairs, and MUST support the 11807 SendTargets command on the discovery session. In a discovery 11808 session, a target MUST return all path information (IP address- 11809 port pairs and portal group tags) for the targets on the target 11810 network entity which the requesting initiator is authorized to 11811 access. 11813 A target MUST support the SendTargets command on operational 11814 sessions; these will only return path information about the target 11815 to which the session is connected, and do not need to return 11816 information about other target names that may be defined in the 11817 responding system. 11819 An initiator MAY make use of the SendTargets as it sees fit. 11821 A SendTargets command consists of a single Text request PDU. 11822 This PDU contains exactly one text key and value. The text key 11823 MUST be SendTargets. The expected response depends upon the 11824 value, as well as whether the session is a discovery or 11825 operational session. 11827 The value must be one of: 11829 All 11831 The initiator is requesting that information on all relevant 11832 targets known to the implementation be returned. This value 11833 MUST be supported on a discovery session, and MUST NOT be 11834 supported on an operational session. 11836 11838 If an iSCSI target name is specified, the session should 11839 respond with addresses for only the named target, if 11840 possible. This value MUST be supported on discovery 11842 sessions. A discovery session MUST be capable of returning 11843 addresses for those targets that would have been returned 11844 had value=All been designated. 11846 11848 The session should only respond with addresses for the target 11849 to which the session is logged in. This MUST be supported 11850 on operational sessions, and MUST NOT return targets other 11851 than the one to which the session is logged in. 11853 The response to this command is a text response that contains a 11854 list of zero or more targets and, optionally, their addresses. 11855 Each target is returned as a target record. A target record 11856 begins with the TargetName text key, followed by a list of 11857 TargetAddress text keys, and bounded by the end of the text 11858 response or the next TargetName key, which begins a new record. 11859 No text keys other than TargetName and TargetAddress are permitted 11860 within a SendTargets response. 11862 For the format of the TargetName, see Section 13.4. 11864 A discovery session MAY respond to a SendTargets request with its 11865 complete list of targets, or with a list of targets that is based 11866 on the name of the initiator logged in to the session. 11868 A SendTargets response MUST NOT contain target names if there are 11869 no targets for the requesting initiator to access. 11871 Each target record returned includes zero or more TargetAddress 11872 fields. 11874 Each target record starts with one text key of the form: 11876 TargetName= 11878 Followed by zero or more address keys of the form: 11880 TargetAddress=[:], 11883 The hostname-or-ipaddress contains a domain name, IPv4 address, or 11884 IPv6 address ([RFC4291]), as specified for the TargetAddress key. 11886 A hostname-or-ipaddress duplicated in TargetAddress responses for 11887 a given node (the port is absent or equal) would probably indicate 11888 that multiple address families are in use at once (IPv6 and IPv4). 11890 Each TargetAddress belongs to a portal group, identified by its 11891 numeric portal group tag (as in Section 13.9). The iSCSI target 11892 name, together with this tag, constitutes the SCSI port 11893 identifier; the tag only needs to be unique within a given 11894 target's name list of addresses. 11896 Multiple-connection sessions can span iSCSI addresses that belong 11897 to the same portal group. 11899 Multiple-connection sessions cannot span iSCSI addresses that 11900 belong to different portal groups. 11902 If a SendTargets response reports an iSCSI address for a target, 11903 it SHOULD also report all other addresses in its portal group in 11904 the same response. 11906 A SendTargets text response can be longer than a single Text 11907 Response PDU, and makes use of the long text responses as 11908 specified. 11910 After obtaining a list of targets from the discovery target 11911 session, 11912 an iSCSI initiator may initiate new sessions to log in to the 11913 discovered targets for full operation. The initiator MAY keep the 11914 discovery session open, and MAY send subsequent SendTargets 11915 commands to discover new targets. 11917 Examples: 11919 This example is the SendTargets response from a single target that 11920 has no other interface ports. 11922 Initiator sends text request that contains: 11924 SendTargets=All 11926 Target sends a text response that contains: 11928 TargetName=iqn.1993-11.com.example:diskarray.sn.8675309 11930 All the target had to return in the simple case was the target 11931 name. It is assumed by the initiator that the IP address and TCP 11932 port for this target are the same as used on the current 11933 connection to the default iSCSI target. 11935 The next example has two internal iSCSI targets, each accessible 11936 via two different ports with different IP addresses. The 11937 following is the text response: 11939 TargetName=iqn.1993-11.com.example:diskarray.sn.8675309 11941 TargetAddress=10.1.0.45:3000,1 11943 TargetAddress=10.1.1.45:3000,2 11945 TargetName=iqn.1993-11.com.example:diskarray.sn.1234567 11947 TargetAddress=10.1.0.45:3000,1 11949 TargetAddress=10.1.1.45:3000,2 11951 Both targets share both addresses; the multiple addresses are 11952 likely used to provide multi-path support. The initiator may 11953 connect to either target name on either address. Each of the 11954 addresses has its own portal group tag; they do not support 11955 spanning multiple-connection sessions with each other. Keep in 11956 mind that the portal group tags for the two named targets are 11957 independent of one another; portal group "1" on the first target 11958 is not necessarily the same as portal group "1" on the second 11959 target. 11961 In the above example, a DNS host name or an IPv6 address could 11962 have been returned instead of an IPv4 address. 11964 The next text response shows a target that supports spanning 11965 sessions across multiple addresses, and further illustrates the 11966 use of the portal group tags: 11968 TargetName=iqn.1993-11.com.example:diskarray.sn.8675309 11970 TargetAddress=10.1.0.45:3000,1 11972 TargetAddress=10.1.1.46:3000,1 11974 TargetAddress=10.1.0.47:3000,2 11976 TargetAddress=10.1.1.48:3000,2 11978 TargetAddress=10.1.1.49:3000,3 11980 In this example, any of the target addresses can be used to reach 11981 the same target. A single-connection session can be established 11982 to any of these TCP addresses. A multiple-connection session 11983 could span addresses .45 and .46 or .47 and .48, but cannot span 11984 any other combination. A TargetAddress with its own tag (.49) 11985 cannot be combined with any other address within the same session. 11987 This SendTargets response does not indicate whether .49 supports 11988 multiple connections per session; it is communicated via the 11989 MaxConnections text key upon login to the target. 11991 Appendix D. Algorithmic Presentation of Error Recovery Classes 11993 This Appendix illustrates the error recovery classes using a 11994 pseudo-programming-language. The procedure names are chosen to be 11995 obvious to most implementers. Each of the recovery classes 11996 described has initiator procedures as well as target procedures. 11997 These algorithms focus on outlining the mechanics of error 11998 recovery classes, and do not exhaustively describe all other 11999 aspects/cases. Examples of this approach are: 12001 - Handling for only certain Opcode types is shown. 12003 - Only certain reason codes (e.g., Recovery in Logout command) 12004 are outlined. 12006 - Resultant cases, such as recovery of Synchronization on a 12007 header digest error are considered out-of-scope in these 12008 algorithms. In this particular example, a header digest 12009 error may lead to connection recovery if some type of sync 12010 and steering layer is not implemented. 12012 These algorithms strive to convey the iSCSI error recovery 12013 concepts in the simplest terms, and are not designed to be 12014 optimal. 12016 D.1. General Data Structure and Procedure Description 12018 This Section defines the procedures and data structures that are 12019 commonly used by all the error recovery algorithms. The structures 12020 may not be the exhaustive representations of what is required for 12021 a typical implementation. 12023 Data structure definitions - 12024 struct TransferContext { 12025 int TargetTransferTag; 12026 int ExpectedDataSN; 12027 }; 12029 struct TCB { /* task control block */ 12030 Boolean SoFarInOrder; 12031 int ExpectedDataSN; /* used for both R2Ts, and Data */ 12032 int MissingDataSNList[MaxMissingDPDU]; 12033 Boolean FbitReceived; 12034 Boolean StatusXferd; 12035 Boolean CurrentlyAllegiant; 12036 int ActiveR2Ts; 12037 int Response; 12038 char *Reason; 12039 struct TransferContext 12040 TransferContextList[MaxOutStandingR2T]; 12041 int InitiatorTaskTag; 12042 int CmdSN; 12043 int SNACK_Tag; 12044 }; 12046 struct Connection { 12047 struct Session SessionReference; 12048 Boolean SoFarInOrder; 12049 int CID; 12050 int State; 12051 int CurrentTimeout; 12052 int ExpectedStatSN; 12053 int MissingStatSNList[MaxMissingSPDU]; 12054 Boolean PerformConnectionCleanup; 12055 }; 12057 struct Session { 12058 int NumConnections; 12059 int CmdSN; 12060 int Maxconnections; 12061 int ErrorRecoveryLevel; 12062 struct iSCSIEndpoint OtherEndInfo; 12063 struct Connection ConnectionList[MaxSupportedConns]; 12064 }; 12066 Procedure descriptions - 12067 Receive-a-In-PDU(transport connection, inbound PDU); 12068 check-basic-validity(inbound PDU); 12069 Start-Timer(timeout handler, argument, timeout value); 12070 Build-And-Send-Reject(transport connection, bad PDU, reason 12071 code); 12073 D.2. Within-command Error Recovery Algorithms 12075 D.2.1. Procedure Descriptions 12077 Recover-Data-if-Possible(last required DataSN, task control 12078 block); 12079 Build-And-Send-DSnack(task control block); 12080 Build-And-Send-RDSnack(task control block); 12081 Build-And-Send-Abort(task control block); 12082 SCSI-Task-Completion(task control block); 12083 Build-And-Send-A-Data-Burst(transport connection, data- 12084 descriptor, 12085 task control 12086 block); 12087 Build-And-Send-R2T(transport connection, data-descriptor, 12088 task control 12089 block); 12090 Build-And-Send-Status(transport connection, task control block); 12091 Transfer-Context-Timeout-Handler(transfer context); 12093 Notes: 12095 - One procedure used in this Section: Handle-Status-SNACK- 12096 request is defined in Within-connection recovery algorithms. 12098 - The Response processing pseudo-code, shown in the target 12099 algorithms, applies to all solicited PDUs that carry StatSN 12100 - SCSI Response, Text Response etc. 12102 D.2.2. Initiator Algorithms 12104 Recover-Data-if-Possible(LastRequiredDataSN, TCB) 12105 { 12106 if (operational ErrorRecoveryLevel > 0) { 12107 if (# of missing PDUs is trackable) { 12108 Note the missing DataSNs in TCB. 12109 if (the task spanned a change in 12110 MaxRecvDataSegmentLength) { 12111 if (TCB.StatusXferd is TRUE) 12112 drop the status PDU; 12113 Build-And-Send-RDSnack(TCB); 12114 } else { 12115 Build-And-Send-DSnack(TCB); 12116 } 12118 } else { 12119 TCB.Reason = "Protocol service CRC error"; 12120 } 12121 } else { 12122 TCB.Reason = "Protocol service CRC error"; 12123 } 12124 if (TCB.Reason == "Protocol service CRC error") { 12125 Clear the missing PDU list in the TCB. 12126 if (TCB.StatusXferd is not TRUE) 12127 Build-And-Send-Abort(TCB); 12128 } 12129 } 12131 Receive-a-In-PDU(Connection, CurrentPDU) 12132 { 12133 check-basic-validity(CurrentPDU); 12134 if (Header-Digest-Bad) discard, return; 12135 Retrieve TCB for CurrentPDU.InitiatorTaskTag. 12136 if ((CurrentPDU.type == Data) 12137 or (CurrentPDU.type = R2T)) { 12138 if (Data-Digest-Bad for Data) { 12139 send-data-SNACK = TRUE; 12140 LastRequiredDataSN = CurrentPDU.DataSN; 12141 } else { 12142 if (TCB.SoFarInOrder = TRUE) { 12143 if (current DataSN is expected) { 12144 Increment TCB.ExpectedDataSN. 12145 } else { 12146 TCB.SoFarInOrder = FALSE; 12147 send-data-SNACK = TRUE; 12148 } 12149 } else { 12150 if (current DataSN was considered 12151 missing) { 12152 remove current DataSN from missing 12153 PDU list. 12154 } else if (current DataSN is higher than 12155 expected) { 12156 send-data-SNACK = TRUE; 12157 } else { 12158 discard, return; 12159 } 12160 Adjust TCB.ExpectedDataSN if 12161 appropriate. 12162 } 12163 LastRequiredDataSN = CurrentPDU.DataSN - 1; 12164 } 12165 if (send-data-SNACK is TRUE and 12166 task is not already considered failed) { 12167 Recover-Data-if-Possible(LastRequiredDataSN, TCB); 12168 } 12169 if (missing data PDU list is empty) { 12170 TCB.SoFarInOrder = TRUE; 12171 } 12172 if (CurrentPDU.type == R2T) { 12173 Increment ActiveR2Ts for this task. 12174 Create a data-descriptor for the data burst. 12175 Build-And-Send-A-Data-Burst(Connection, data- 12176 descriptor, 12177 TCB); 12178 } 12179 } else if (CurrentPDU.type == Response) { 12180 if (Data-Digest-Bad) { 12181 send-status-SNACK = TRUE; 12182 } else { 12183 TCB.StatusXferd = TRUE; 12184 Store the status information in TCB. 12185 if (ExpDataSN does not match) { 12186 TCB.SoFarInOrder = FALSE; 12187 Recover-Data-if-Possible(current DataSN, TCB); 12188 } 12189 if (missing data PDU list is empty) { 12190 TCB.SoFarInOrder = TRUE; 12191 } 12192 } 12193 } else { /* REST UNRELATED TO WITHIN-COMMAND-RECOVERY, NOT 12194 SHOWN */ 12195 } 12196 if ((TCB.SoFarInOrder == TRUE) and 12197 (TCB.StatusXferd == TRUE)) { 12199 SCSI-Task-Completion(TCB); 12200 } 12201 } 12203 D.2.3. Target Algorithms 12205 Receive-a-In-PDU(Connection, CurrentPDU) 12206 { 12207 check-basic-validity(CurrentPDU); 12208 if (Header-Digest-Bad) discard, return; 12209 Retrieve TCB for CurrentPDU.InitiatorTaskTag. 12210 if (CurrentPDU.type == Data) { 12211 Retrieve TContext from CurrentPDU.TargetTransferTag; 12212 if (Data-Digest-Bad) { 12213 Build-And-Send-Reject(Connection, CurrentPDU, 12214 Payload-Digest-Error); 12215 Note the missing data PDUs in MissingDataRange[]. 12216 send-recovery-R2T = TRUE; 12217 } else { 12218 if (current DataSN is not expected) { 12219 Note the missing data PDUs in MissingDataRange[]. 12220 send-recovery-R2T = TRUE; 12221 } 12222 if (CurrentPDU.Fbit == TRUE) { 12223 if (current PDU is solicited) { 12224 Decrement TCB.ActiveR2Ts. 12225 } 12226 if ((current PDU is unsolicited and 12227 data received is less than I/O length and 12228 data received is less than 12229 FirstBurstLength) 12230 or (current PDU is solicited and the length of 12231 this burst is less than expected)) { 12232 send-recovery-R2T = TRUE; 12233 Note the missing data in MissingDataRange[]. 12234 } 12235 } 12236 } 12237 Increment TContext.ExpectedDataSN. 12238 if (send-recovery-R2T is TRUE and 12239 task is not already considered failed) { 12240 if (operational ErrorRecoveryLevel > 0) { 12241 Increment TCB.ActiveR2Ts. 12242 Create a data-descriptor for the data burst 12243 from MissingDataRange. 12244 Build-And-Send-R2T(Connection, data-descriptor, 12245 TCB); 12246 } else { 12247 if (current PDU is the last unsolicited) 12248 TCB.Reason = "Not enough unsolicited data"; 12249 else 12250 TCB.Reason = "Protocol service CRC error"; 12251 } 12252 } 12253 if (TCB.ActiveR2Ts == 0) { 12254 Build-And-Send-Status(Connection, TCB); 12255 } 12256 } else if (CurrentPDU.type == SNACK) { 12257 snack-failure = FALSE; 12258 if (operational ErrorRecoveryLevel > 0) { 12259 if (CurrentPDU.type == Data/R2T) { 12260 if (the request is satisfiable) { 12261 if (request for Data) { 12262 Create a data-descriptor for the data burst 12263 from BegRun and RunLength. 12264 Build-And-Send-A-Data-Burst(Connection, 12265 data-descriptor, TCB); 12266 } else { /* R2T */ 12267 Create a data-descriptor for the data burst 12268 from BegRun and RunLength. 12269 Build-And-Send-R2T(Connection, data- 12270 descriptor, 12271 TCB); 12272 } 12273 } else { 12274 snack-failure = TRUE; 12275 } 12276 } else if (CurrentPDU.type == status) { 12277 Handle-Status-SNACK-request(Connection, 12278 CurrentPDU); 12279 } else if (CurrentPDU.type == DataACK) { 12280 Consider all data upto CurrentPDU.BegRun as 12281 acknowledged. 12282 Free up the retransmission resources for that data. 12283 } else if (CurrentPDU.type == R-Data SNACK) { 12284 Create a data descriptor for a data burst 12285 covering 12286 all unacknowledged data. 12287 Build-And-Send-A-Data-Burst(Connection, 12288 data-descriptor, TCB); 12289 TCB.SNACK_Tag = CurrentPDU.SNACK_Tag; 12290 if (there's no more data to send) { 12291 Build-And-Send-Status(Connection, TCB); 12292 } 12293 } 12294 } else { /* operational ErrorRecoveryLevel = 0 */ 12295 snack-failure = TRUE; 12296 } 12297 if (snack-failure == TRUE) { 12298 Build-And-Send-Reject(Connection, CurrentPDU, 12299 SNACK-Reject); 12300 if (TCB.StatusXferd != TRUE) { 12301 TCB.Reason = "SNACK Rejected"; 12302 Build-And-Send-Status(Connection, TCB); 12303 } 12304 } 12306 } else { /* REST UNRELATED TO WITHIN-COMMAND-RECOVERY, NOT 12307 SHOWN */ 12308 } 12309 } 12311 Transfer-Context-Timeout-Handler(TContext) 12312 { 12313 Retrieve TCB and Connection from TContext. 12314 Decrement TCB.ActiveR2Ts. 12315 if (operational ErrorRecoveryLevel > 0 and 12316 task is not already considered failed) { 12317 Note the missing data PDUs in MissingDataRange[]. 12318 Create a data-descriptor for the data burst 12319 from MissingDataRange[]. 12320 Build-And-Send-R2T(Connection, data-descriptor, TCB); 12322 } else { 12323 TCB.Reason = "Protocol service CRC error"; 12324 if (TCB.ActiveR2Ts = 0) { 12325 Build-And-Send-Status(Connection, TCB); 12326 } 12327 } 12328 } 12330 D.3. Within-connection Recovery Algorithms 12332 D.3.1. Procedure Descriptions 12334 Procedure descriptions: 12335 Recover-Status-if-Possible(transport connection, 12336 currently received PDU); 12337 Evaluate-a-StatSN(transport connection, currently received PDU); 12338 Retransmit-Command-if-Possible(transport connection, CmdSN); 12339 Build-And-Send-SSnack(transport connection); 12340 Build-And-Send-Command(transport connection, task control 12341 block); 12342 Command-Acknowledge-Timeout-Handler(task control block); 12343 Status-Expect-Timeout-Handler(transport connection); 12344 Build-And-Send-Nop-Out(transport connection); 12345 Handle-Status-SNACK-request(transport connection, status SNACK 12346 PDU); 12347 Retransmit-Status-Burst(status SNACK, task control block); 12348 Is-Acknowledged(beginning StatSN, run length); 12350 Implementation-specific tunables: 12351 InitiatorProactiveSNACKEnabled 12353 Notes: 12354 - The initiator algorithms only deal with unsolicited Nop-In 12355 PDUs for generating status SNACKs. A solicited Nop-In PDU 12356 has an assigned StatSN, which, when out of order, could 12357 trigger the out of order StatSN handling in Within-command 12358 algorithms, again leading to Recover-Status-if-Possible. 12360 - The pseudo-code shown may result in the retransmission of 12361 unacknowledged commands in more cases than necessary. This 12362 will not, however, affect the correctness of the operation 12363 because the target is required to discard the duplicate 12364 CmdSNs. 12366 - The procedure Build-And-Send-Async is defined in the 12367 Connection recovery algorithms. 12369 - The procedure Status-Expect-Timeout-Handler describes how 12370 initiators may proactively attempt to retrieve the Status if 12371 they so choose. This procedure is assumed to be triggered 12372 much before the standard ULP timeout. 12374 D.3.2. Initiator Algorithms 12376 Recover-Status-if-Possible(Connection, CurrentPDU) 12377 { 12378 if ((Connection.state == LOGGED_IN) and 12379 connection is not already considered 12380 failed) { 12381 if (operational ErrorRecoveryLevel > 0) { 12382 if (# of missing PDUs is trackable) { 12383 Note the missing StatSNs in Connection 12384 that were not already requested with SNACK; 12385 Build-And-Send-SSnack(Connection); 12386 } else { 12387 Connection.PerformConnectionCleanup = TRUE; 12388 } 12389 } else { 12390 Connection.PerformConnectionCleanup = TRUE; 12391 } 12392 if (Connection.PerformConnectionCleanup == TRUE) { 12393 Start-Timer(Connection-Cleanup-Handler, Connection, 12394 0); 12395 } 12396 } 12398 } 12400 Retransmit-Command-if-Possible(Connection, CmdSN) 12401 { 12402 if (operational ErrorRecoveryLevel > 0) { 12403 Retrieve the InitiatorTaskTag, and thus TCB for the 12404 CmdSN. 12405 Build-And-Send-Command(Connection, TCB); 12406 } 12407 } 12409 Evaluate-a-StatSN(Connection, CurrentPDU) 12410 { 12411 send-status-SNACK = FALSE; 12412 if (Connection.SoFarInOrder == TRUE) { 12413 if (current StatSN is the expected) { 12414 Increment Connection.ExpectedStatSN. 12415 } else { 12416 Connection.SoFarInOrder = FALSE; 12417 send-status-SNACK = TRUE; 12418 } 12419 } else { 12420 if (current StatSN was considered missing) { 12421 remove current StatSN from the missing list. 12422 } else { 12423 if (current StatSN is higher than expected){ 12424 send-status-SNACK = TRUE; 12425 } else { 12426 send-status-SNACK = FALSE; 12427 discard the PDU; 12428 } 12429 } 12430 Adjust Connection.ExpectedStatSN if appropriate. 12431 if (missing StatSN list is empty) { 12432 Connection.SoFarInOrder = TRUE; 12433 } 12434 } 12435 return send-status-SNACK; 12436 } 12437 Receive-a-In-PDU(Connection, CurrentPDU) 12438 { 12439 check-basic-validity(CurrentPDU); 12440 if (Header-Digest-Bad) discard, return; 12441 Retrieve TCB for CurrentPDU.InitiatorTaskTag. 12442 if (CurrentPDU.type == Nop-In) { 12443 if (the PDU is unsolicited) { 12444 if (current StatSN is not expected) { 12445 Recover-Status-if-Possible(Connection, 12446 CurrentPDU); 12447 } 12448 if (current ExpCmdSN is not Session.CmdSN) { 12449 Retransmit-Command-if-Possible(Connection, 12450 CurrentPDU.ExpCmdSN); 12451 } 12452 } 12453 } else if (CurrentPDU.type == Reject) { 12454 if (it is a data digest error on immediate data) { 12455 Retransmit-Command-if-Possible(Connection, 12457 CurrentPDU.BadPDUHeader.CmdSN); 12458 } 12459 } else if (CurrentPDU.type == Response) { 12460 send-status-SNACK = Evaluate-a-StatSN(Connection, 12461 CurrentPDU); 12462 if (send-status-SNACK == TRUE) 12463 Recover-Status-if-Possible(Connection, CurrentPDU); 12464 } else { /* REST UNRELATED TO WITHIN-CONNECTION-RECOVERY, 12465 * NOT SHOWN */ 12466 } 12467 } 12469 Command-Acknowledge-Timeout-Handler(TCB) 12470 { 12471 Retrieve the Connection for TCB. 12472 Retransmit-Command-if-Possible(Connection, TCB.CmdSN); 12473 } 12475 Status-Expect-Timeout-Handler(Connection) 12476 { 12477 if (operational ErrorRecoveryLevel > 0) { 12478 Build-And-Send-Nop-Out(Connection); 12479 } else if (InitiatorProactiveSNACKEnabled){ 12480 if ((Connection.state == LOGGED_IN) and 12481 connection is not already considered 12482 failed) { 12483 Build-And-Send-SSnack(Connection); 12484 } 12485 } 12486 } 12488 D.3.3.Target Algorithms 12489 Handle-Status-SNACK-request(Connection, CurrentPDU) 12490 { 12491 if (operational ErrorRecoveryLevel > 0) { 12492 if (request for an acknowledged run) { 12493 Build-And-Send-Reject(Connection, CurrentPDU, 12494 Protocol-Error); 12495 } else if (request for an untransmitted run) { 12496 discard, return; 12497 } else { 12498 Retransmit-Status-Burst(CurrentPDU, TCB); 12499 } 12500 } else { 12501 Build-And-Send-Async(Connection, DroppedConnection, 12502 DefaultTime2Wait, 12503 DefaultTime2Retain); 12504 } 12505 } 12507 D.4. Connection Recovery Algorithms 12509 D.4.1. Procedure Descriptions 12511 Build-And-Send-Async(transport connection, reason code, 12512 minimum time, maximum time); 12513 Pick-A-Logged-In-Connection(session); 12514 Build-And-Send-Logout(transport connection, logout connection 12515 identifier, reason code); 12516 PerformImplicitLogout(transport connection, logout connection 12517 identifier, target information); 12519 PerformLogin(transport connection, target information); 12520 CreateNewTransportConnection(target information); 12521 Build-And-Send-Command(transport connection, task control 12522 block); 12523 Connection-Cleanup-Handler(transport connection); 12524 Connection-Resource-Timeout-Handler(transport connection); 12525 Quiesce-And-Prepare-for-New-Allegiance(session, task control 12526 block); 12527 Build-And-Send-Logout-Response(transport connection, 12528 CID of connection in recovery, reason 12529 code); 12530 Build-And-Send-TaskMgmt-Response(transport connection, 12531 task mgmt command PDU, response code); 12532 Establish-New-Allegiance(task control block, transport 12533 connection); 12534 Schedule-Command-To-Continue(task control block); 12536 Notes: 12537 - Transport exception conditions, such as unexpected 12538 connection termination, connection reset, and hung 12539 connection while the connection is in the full-feature 12540 phase, are all assumed to be asynchronously signaled to the 12541 iSCSI layer using the Transport_Exception_Handler procedure. 12543 D.4.2. Initiator Algorithms 12545 Receive-a-In-PDU(Connection, CurrentPDU) 12546 { 12547 check-basic-validity(CurrentPDU); 12548 if (Header-Digest-Bad) discard, return; 12549 Retrieve TCB from CurrentPDU.InitiatorTaskTag. 12550 if (CurrentPDU.type == Async) { 12551 if (CurrentPDU.AsyncEvent == ConnectionDropped) { 12552 Retrieve the AffectedConnection for 12553 CurrentPDU.Parameter1. 12554 AffectedConnection.CurrentTimeout = 12555 CurrentPDU.Parameter3; 12556 AffectedConnection.State = CLEANUP_WAIT; 12557 Start-Timer(Connection-Cleanup-Handler, 12558 AffectedConnection, 12559 CurrentPDU.Parameter2); 12560 } else if (CurrentPDU.AsyncEvent == LogoutRequest)) { 12561 AffectedConnection = Connection; 12562 AffectedConnection.State = LOGOUT_REQUESTED; 12563 AffectedConnection.PerformConnectionCleanup = TRUE; 12564 AffectedConnection.CurrentTimeout = 12565 CurrentPDU.Parameter3; 12566 Start-Timer(Connection-Cleanup-Handler, 12567 AffectedConnection, 0); 12568 } else if (CurrentPDU.AsyncEvent == SessionDropped)) { 12569 for (each Connection) { 12570 Connection.State = CLEANUP_WAIT; 12571 Connection.CurrentTimeout = CurrentPDU.Parameter3; 12572 Start-Timer(Connection-Cleanup-Handler, 12573 Connection, CurrentPDU.Parameter2); 12574 } 12575 Session.state = FAILED; 12576 } 12578 } else if (CurrentPDU.type == LogoutResponse) { 12579 Retrieve the CleanupConnection for CurrentPDU.CID. 12580 if (CurrentPDU.Response = failure) { 12581 CleanupConnection.State = CLEANUP_WAIT; 12582 } else { 12583 CleanupConnection.State = FREE; 12584 } 12585 } else if (CurrentPDU.type == LoginResponse) { 12586 if (this is a response to an implicit Logout) { 12587 Retrieve the CleanupConnection. 12588 if (successful) { 12589 CleanupConnection.State = FREE; 12590 Connection.State = LOGGED_IN; 12591 } else { 12592 CleanupConnection.State = CLEANUP_WAIT; 12593 DestroyTransportConnection(Connection); 12594 } 12595 } 12596 } else { /* REST UNRELATED TO CONNECTION-RECOVERY, 12597 * NOT SHOWN */ 12599 } 12600 if (CleanupConnection.State == FREE) { 12601 for (each command that was active on CleanupConnection) { 12602 /* Establish new connection allegiance */ 12603 NewConnection = Pick-A-Logged-In- 12604 Connection(Session); 12605 Build-And-Send-Command(NewConnection, TCB); 12606 } 12607 } 12608 } 12610 Connection-Cleanup-Handler(Connection) 12611 { 12612 Retrieve Session from Connection. 12613 if (Connection can still exchange iSCSI PDUs) { 12614 NewConnection = Connection; 12615 } else { 12616 Start-Timer(Connection-Resource-Timeout-Handler, 12617 Connection, Connection.CurrentTimeout); 12618 if (there are other logged-in connections) { 12619 NewConnection = Pick-A-Logged-In- 12620 Connection(Session); 12621 } else { 12622 NewConnection = 12624 CreateTransportConnection(Session.OtherEndInfo); 12625 Initiate an implicit Logout on NewConnection for 12626 Connection.CID. 12627 return; 12628 } 12629 } 12630 Build-And-Send-Logout(NewConnection, Connection.CID, 12631 RecoveryRemove); 12632 } 12634 Transport_Exception_Handler(Connection) 12635 { 12636 Connection.PerformConnectionCleanup = TRUE; 12637 if (the event is an unexpected transport disconnect) { 12638 Connection.State = CLEANUP_WAIT; 12639 Connection.CurrentTimeout = DefaultTime2Retain; 12640 Start-Timer(Connection-Cleanup-Handler, Connection, 12641 DefaultTime2Wait); 12643 } else { 12644 Connection.State = FREE; 12645 } 12646 } 12648 D.4.3. Target Algorithms 12650 Receive-a-In-PDU(Connection, CurrentPDU) 12651 { 12652 check-basic-validity(CurrentPDU); 12653 if (Header-Digest-Bad) discard, return; 12654 else if (Data-Digest-Bad) { 12655 Build-And-Send-Reject(Connection, CurrentPDU, 12656 Payload-Digest-Error); 12657 discard, return; 12658 } 12659 Retrieve TCB and Session. 12660 if (CurrentPDU.type == Logout) { 12661 if (CurrentPDU.ReasonCode = RecoveryRemove) { 12662 Retrieve the CleanupConnection from CurrentPDU.CID). 12663 for (each command active on CleanupConnection) { 12664 Quiesce-And-Prepare-for-New-Allegiance(Session, 12665 TCB); 12666 TCB.CurrentlyAllegiant = FALSE; 12667 } 12668 Cleanup-Connection-State(CleanupConnection); 12669 if ((quiescing successful) and (cleanup successful)) 12670 { 12671 Build-And-Send-Logout-Response(Connection, 12672 CleanupConnection.CID, 12673 Success); 12674 } else { 12675 Build-And-Send-Logout-Response(Connection, 12676 CleanupConnection.CID, 12677 Failure); 12678 } 12680 } 12681 } else if ((CurrentPDU.type == Login) and 12682 operational ErrorRecoveryLevel == 2) { 12683 Retrieve the CleanupConnection from CurrentPDU.CID). 12684 for (each command active on CleanupConnection) { 12685 Quiesce-And-Prepare-for-New-Allegiance(Session, 12686 TCB); 12687 TCB.CurrentlyAllegiant = FALSE; 12688 } 12689 Cleanup-Connection-State(CleanupConnection); 12690 if ((quiescing successful) and (cleanup successful)) 12691 { 12692 Continue with the rest of the Login processing; 12693 } else { 12694 Build-And-Send-Login-Response(Connection, 12695 CleanupConnection.CID, Target 12696 Error); 12697 } 12698 } 12699 } else if (CurrentPDU.type == TaskManagement) { 12700 if (CurrentPDU.function == "TaskReassign") { 12701 if (Session.ErrorRecoveryLevel < 2) { 12702 Build-And-Send-TaskMgmt-Response(Connection, 12703 CurrentPDU, "Allegiance reassignment 12704 not supported"); 12705 } else if (task is not found) { 12706 Build-And-Send-TaskMgmt-Response(Connection, 12707 CurrentPDU, "Task not in task set"); 12708 } else if (task is currently allegiant) { 12709 Build-And-Send-TaskMgmt-Response(Connection, 12710 CurrentPDU, "Task still allegiant"); 12711 } else { 12712 Establish-New-Allegiance(TCB, Connection); 12713 TCB.CurrentlyAllegiant = TRUE; 12714 Schedule-Command-To-Continue(TCB); 12715 } 12716 } 12717 } else { /* REST UNRELATED TO CONNECTION-RECOVERY, 12718 * NOT SHOWN */ 12719 } 12721 } 12723 Transport_Exception_Handler(Connection) 12724 { 12725 Connection.PerformConnectionCleanup = TRUE; 12726 if (the event is an unexpected transport disconnect) { 12727 Connection.State = CLEANUP_WAIT; 12728 Start-Timer(Connection-Resource-Timeout-Handler, 12729 Connection, 12731 (DefaultTime2Wait+DefaultTime2Retain)); 12732 if (this Session has full-feature phase connections 12733 left) { 12734 DifferentConnection = 12735 Pick-A-Logged-In-Connection(Session); 12736 Build-And-Send-Async(DifferentConnection, 12737 DroppedConnection, DefaultTime2Wait, 12738 DefaultTime2Retain); 12739 } 12740 } else { 12741 Connection.State = FREE; 12742 } 12743 } 12744 Appendix E. Clearing Effects of Various Events on Targets 12746 E.1. C 12747 learing Effects on iSCSI Objects 12749 The following tables describe the target behavior on receiving the 12750 events specified in the rows of the table. The second table is 12751 an extension of the first table and defines clearing actions for 12752 more objects on the same events. The legend is: 12754 Y = Yes (cleared/discarded/reset on the event specified in 12755 the row). Unless otherwise noted, the clearing action is 12756 only applicable for the issuing initiator port. 12758 N = No (not affected on the event specified in the row, 12759 i.e., stays at previous value). 12761 NA = Not Applicable or Not Defined. 12763 +-----+-----+-----+-----+-----+ 12764 |IT(1)|IC(2)|CT(5)|ST(6)|PP(7)| 12765 +---------------------+-----+-----+-----+-----+-----+ 12766 |connection failure(8)|Y |Y |N |N |Y | 12767 +---------------------+-----+-----+-----+-----+-----+ 12768 |connection state |NA |NA |Y |N |NA | 12769 |timeout (9) | | | | | | 12770 +---------------------+-----+-----+-----+-----+-----+ 12771 |session timeout/ |Y |Y |Y |Y |Y(14)| 12772 |closure/reinstatement| | | | | | 12773 |(10) | | | | | | 12774 +---------------------+-----+-----+-----+-----+-----+ 12775 |session continuation |NA |NA |N(11)|N |NA | 12776 |(12) | | | | | | 12777 +---------------------+-----+-----+-----+-----+-----+ 12778 |successful connection|Y |Y |Y |N |Y(13)| 12779 |close logout | | | | | | 12780 +---------------------+-----+-----+-----+-----+-----+ 12781 |session failure (18) |Y |Y |N |N |Y | 12782 +---------------------+-----+-----+-----+-----+-----+ 12783 |successful recovery |Y |Y |N |N |Y(13)| 12784 |Logout | | | | | | 12785 +---------------------+-----+-----+-----+-----+-----+ 12786 |failed Logout |Y |Y |N |N |Y | 12787 +---------------------+-----+-----+-----+-----+-----+ 12788 |connection Login |NA |NA |NA |Y(15)|NA | 12789 |(leading) | | | | | | 12790 +---------------------+-----+-----+-----+-----+-----+ 12791 |connection Login |NA |NA |N(11)|N |Y | 12792 |(non-leading) | | | | | | 12793 +---------------------+-----+-----+-----+-----+-----+ 12794 |target cold reset(16)|Y(20)|Y |Y |Y |Y | 12795 +---------------------+-----+-----+-----+-----+-----+ 12796 |target warm reset(16)|Y(20)|Y |Y |Y |Y | 12797 +---------------------+-----+-----+-----+-----+-----+ 12798 |LU reset(19) |Y(20)|Y |Y |Y |Y | 12799 +---------------------+-----+-----+-----+-----+-----+ 12800 |powercycle(16) |Y |Y |Y |Y |Y | 12801 +---------------------+-----+-----+-----+-----+-----+ 12803 1. Incomplete TTTs - Target Transfer Tags on which the target is 12804 still expecting PDUs to be received. Examples include TTTs 12805 received via R2T, NOP-IN, etc. 12807 2. Immediate Commands - immediate commands, but waiting for 12808 execution on a target. For example, Abort Task Set. 12810 5. Connection Tasks - tasks that are active on the iSCSI connection 12811 in question. 12813 6. Session Tasks - tasks that are active on the entire iSCSI 12814 session. A union of "connection tasks" on all participating 12815 connections. 12817 7. Partial PDUs (if any) - PDUs that are partially sent and waiting 12818 for transport window credit to complete the transmission. 12820 8. Connection failure is a connection exception condition - one of 12821 the transport connections shutdown, transport connections 12822 reset, or transport connections timed out, which abruptly 12823 terminated the iSCSI full-feature phase connection. A 12824 connection failure always takes the connection state machine to 12825 the CLEANUP_WAIT state. 12827 9. Connection state timeout happens if a connection spends more 12828 time than agreed upon during Login negotiation in the 12829 CLEANUP_WAIT state, and this takes the connection to the FREE 12830 state (M1 transition in connection cleanup state diagram). 12832 10.These are defined in Section 6.3.5. 12834 11.This clearing effect is "Y" only if it is a connection 12835 reinstatement and the operational ErrorRecoveryLevel is less 12836 than 2. 12838 12.Session continuation is defined in Section 6.3.5. 12840 13.This clearing effect is only valid if the connection is being 12841 logged out on a different connection and when the connection 12842 being logged out on the target may have some partial PDUs 12843 pending to be sent. In all other cases, the effect is "NA". 12845 14.This clearing effect is only valid for a "close the session" 12846 logout in a multi-connection session. In all other cases, the 12847 effect is "NA". 12848 15.Only applicable if this leading connection login is a session 12849 reinstatement. If this is not the case, it is "NA". 12850 16.This operation affects all logged-in initiators. 12851 18.Session failure is defined in Section 6.3.5. 12852 19.This operation affects all logged-in initiators and the clearing 12853 effects are only applicable to the LU being reset. 12854 20.With Standard multi-task abort semantics (Section 4.2.3.3), a 12855 target warm reset or a target cold reset or an LU reset would 12856 clear the active TTTs upon completion. However, the FastAbort 12857 multi-task abort semantics defined by Section 4.2.3.4 do not 12858 guarantee that the active TTTs are cleared by the end of the 12859 reset operations. In fact, the FastAbort semantics are designed 12860 to allow clearing the TTTs in a "lazy" fashion after the TMF 12861 Response is delivered. Thus, when TaskReporting=FastAbort 12862 (Section 13.23) is operational on a session, the clearing 12863 effects of reset operations on "Incomplete TTTs" is "N". 12865 +-----+-----+-----+-----+-----+ 12866 |DC(1)|DD(2)|SS(3)|CS(4)|DS(5)| 12867 +---------------------+-----+-----+-----+-----+-----+ 12868 |connection failure |N |Y |N |N |N | 12869 +---------------------+-----+-----+-----+-----+-----+ 12870 |connection state |Y |NA |Y |N |NA | 12871 |timeout | | | | | | 12872 +---------------------+-----+-----+-----+-----+-----+ 12873 |session timeout/ |Y |Y |Y(7) |Y |NA | 12874 |closure/reinstatement| | | | | | 12875 +---------------------+-----+-----+-----+-----+-----+ 12876 |session continuation |N(11)|NA*12|NA |N |NA*13| 12877 +---------------------+-----+-----+-----+-----+-----+ 12878 |successful connection|Y |Y |Y |N |NA | 12879 |close Logout | | | | | | 12880 +---------------------+-----+-----+-----+-----+-----+ 12881 |session failure |N |Y |N |N |N | 12882 +---------------------+-----+-----+-----+-----+-----+ 12883 |successful recovery |Y |Y |Y |N |N | 12884 |Logout | | | | | | 12885 +---------------------+-----+-----+-----+-----+-----+ 12886 |failed Logout |N |Y(9) |N |N |N | 12887 +---------------------+-----+-----+-----+-----+-----+ 12888 |connection Login |NA |NA |N(8) |N(8) |NA | 12889 |(leading | | | | | | 12890 +---------------------+-----+-----+-----+-----+-----+ 12891 |connection Login |N(11)|NA*12|N(8) |N |NA*13| 12892 |(non-leading) | | | | | | 12893 +---------------------+-----+-----+-----+-----+-----+ 12894 |target cold reset |Y |Y |Y |Y(10)|NA | 12895 +---------------------+-----+-----+-----+-----+-----+ 12896 |target warm reset |Y |Y |N |N |NA | 12897 +---------------------+-----+-----+-----+-----+-----+ 12898 |LU reset |N |Y |N |N |N | 12899 +---------------------+-----+-----+-----+-----+-----+ 12900 |powercycle |Y |Y |Y |Y(10)|NA | 12901 +---------------------+-----+-----+-----+-----+-----+ 12903 1. Discontiguous Commands - commands allegiant to the connection 12904 in question and waiting to be reordered in the iSCSI layer. All 12905 "Y"s in this column assume that the task causing the event (if 12906 indeed the event is the result of a task) is issued as an 12907 immediate command, because the discontiguities can be ahead of the 12908 task. 12910 2. Discontiguous Data - data PDUs received for the task in 12911 question and waiting to be reordered due to prior discontiguities 12912 in DataSN. 12914 3. StatSN 12916 4. CmdSN 12918 5. DataSN 12920 7. It clears the StatSN on all the connections. 12922 8. This sequence number is instantiated on this event. 12924 9. A logout failure drives the connection state machine to the 12925 CLEANUP_WAIT state, similar to the connection failure event. 12926 Hence, it has a similar effect on this and several other protocol 12927 aspects. 12929 10. This is cleared by virtue of the fact that all sessions with 12930 all initiators are terminated. 12932 11. This clearing effect is "Y" if it is a connection 12933 reinstatement. 12935 12. This clearing effect is "Y" only if it is a connection 12936 reinstatement and the operational ErrorRecoveryLevel is 2. 12938 13. This clearing effect is "N" only if it is a connection 12939 reinstatement and the operational ErrorRecoveryLevel is 2. 12941 E.2. C 12942 learing Effects on SCSI Objects 12944 The only iSCSI protocol action that can effect clearing actions on 12945 SCSI objects is the "I_T nexus loss" notification (Section 6.3.5.1 12946 Loss of Nexus notification). [SPC3] describes the clearing effects 12947 of this notification on a variety of SCSI attributes. In addition, 12948 SCSI standards documents (such as [SAM2] and [SBC2]) define 12949 additional clearing actions that may take place for several SCSI 12950 objects on SCSI events such as LU resets and power-on resets. 12952 Since iSCSI defines a target cold reset as a protocol-equivalent 12953 to a target power-cycle, the iSCSI target cold reset must also be 12954 considered as the power-on reset event in interpreting the actions 12955 defined in the SCSI standards. 12957 When the iSCSI session is reconstructed (between the same SCSI 12958 ports with the same nexus identifier) reestablishing the same I_T 12959 nexus, all SCSI objects that are defined to not clear on the "I_T 12960 nexus loss" notification event, such as persistent reservations, 12961 are automatically associated to this new session. 12963 Acknowledgments 12965 Several individuals on the original IPS Working Group made 12966 significant contributions to the original RFCs 3720, 3980, 4850 12967 and 5048. 12969 Specifically, the authors of the original RFCs - which this draft 12970 consolidates into a single document - were the following: 12972 RFC 3720: Julian Satran, Kalman Meth, Costa Sapuntzakis, 12973 Mallikarjun Chadalapaka, Efri Zeidner 12975 RFC 3980: Marjorie Krueger, Mallikarjun Chadalapaka, Rob Elliott 12977 RFC 4850: David Wysochanski 12979 RFC 5048: Mallikarjun Chadalapaka 12981 Many thanks to Fred Knight for contributing to the UML notations 12982 and drawings in this draft. 12984 We would in addition like to acknowledge the following individuals 12985 who contributed to this revised draft: David Harrington, Paul 12986 Koning, Mark Edwards, Rob Elliott, Martin Stiemerling. Finally, 12987 this draft also benefited from significant review contributions 12988 from the Storm Working Group at large. 12990 Authors' Addresses 12992 Mallikarjun Chadalapaka 12993 Microsoft 12994 One Microsoft Way 12995 Redmond WA 98052 USA 12996 E-mail: cbm@chadalapaka.com 12998 Julian Satran 12999 Infinidat Ltd. 13000 E-mail: julians@infinidat.com, julian@satran.net 13002 Kalman Meth 13003 IBM Haifa Research Lab 13004 Haifa University Campus - Mount Carmel 13005 Haifa 31905, Israel 13006 Phone +972.4.829.6341 13007 E-mail: meth@il.ibm.com 13009 David L. Black, 13010 EMC Corporation, 13011 176 South St., Hopkinton, MA 01748 13012 Phone +1 (508) 293-7953 13013 Email: david.black@emc.com 13015 Comments may be sent to Mallikarjun Chadalapaka 13017 Acknowledgement 13019 Funding for the RFC Editor function is currently provided by the 13020 Internet Society