idnits 2.17.1 draft-ietf-storm-iscsi-cons-07.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 2920 -- Looks like a reference, but probably isn't: '0' on line 6777 -- Looks like a reference, but probably isn't: '7' on line 6777 == Missing Reference: 'RFCyyyy' is mentioned on line 10929, but not defined == Missing Reference: 'MaxMissingDPDU' is mentioned on line 11971, but not defined == Missing Reference: 'MaxOutStandingR2T' is mentioned on line 11979, but not defined == Missing Reference: 'MaxMissingSPDU' is mentioned on line 11992, but not defined == Missing Reference: 'MaxSupportedConns' is mentioned on line 12002, but not defined -- 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: 3 errors (**), 0 flaws (~~), 8 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-07.txt 4 Intended status: Proposed Standard Julian Satran 5 Expires: April 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 April 1, 2013. 38 Copyright Notice 40 Copyright (c) 2012 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 1. Introduction.................................................... 14 74 2. Acronyms, Definitions and Document Summary...................... 15 75 2.1. Acronyms .................................................... 15 76 2.2. Definitions ................................................. 17 77 2.3. Summary of Changes .......................................... 23 78 2.4. Conventions ................................................. 24 79 2.4.1. Word Rule ............................................... 25 80 2.4.2. Half-Word Rule .......................................... 25 81 2.4.3. Byte Rule ............................................... 26 82 3. UML Conventions................................................. 27 83 3.1. UML Conventions Overview ...................................27 84 3.2. Multiplicity Notion ........................................27 85 3.3. Class Diagram Conventions ..................................28 86 3.4. Class Diagram Notation for Associations ....................29 87 3.5. Class Diagram Notation for Aggregations ....................30 88 3.6. Class Diagram Notation for Generalizations .................30 89 4. Overview........................................................ 32 90 4.1. SCSI Concepts ............................................... 32 91 4.2. iSCSI Concepts and Functional Overview ...................... 33 92 4.2.1. Layers and Sessions ..................................... 34 93 4.2.2. Ordering and iSCSI Numbering ............................ 35 94 4.2.2.1. Command Numbering and Acknowledging ..................35 95 4.2.2.2. Response/Status Numbering and Acknowledging ..........39 96 4.2.2.3. Response Ordering ....................................40 97 4.2.2.3.1. Need for Response Ordering .......................40 98 4.2.2.3.2. Response Ordering Model Description ..............40 99 4.2.2.3.3. iSCSI Semantics with the Interface Model .........41 100 4.2.2.3.4. Current List of Fenced Response Use Cases ........42 101 4.2.2.4. Data Sequencing ......................................43 102 4.2.3. iSCSI Task Management ................................... 43 103 4.2.3.1. Task Management Overview .............................43 104 4.2.3.2. Notion of Affected Tasks .............................44 105 4.2.3.3. Standard Multi-task Abort Semantics ..................44 106 4.2.3.4. FastAbort Multi-task Abort Semantics ................46 107 4.2.3.5. Affected Tasks Shared across Standard and FastAbort 108 Sessions .....................................................48 109 4.2.3.6. Rationale behind the FastAbort Semantics ............49 110 4.2.4. iSCSI Login .............................................51 111 4.2.5. iSCSI Full Feature Phase ................................52 112 4.2.5.1. Command Connection Allegiance .......................53 113 4.2.5.2. Data Transfer Overview ..............................53 114 4.2.5.3. Tags and Integrity Checks ...........................55 115 4.2.5.4. Task Management .....................................56 116 4.2.6. iSCSI Connection Termination ............................56 117 4.2.7. iSCSI Names .............................................56 118 4.2.7.1. iSCSI Name Properties ...............................57 119 4.2.7.2. iSCSI Name Encoding .................................59 120 4.2.7.3. iSCSI Name Structure ................................60 121 4.2.7.4. Type "iqn." (iSCSI Qualified Name) ..................62 122 4.2.7.5. Type "eui." (IEEE EUI-64 format) ....................63 123 4.2.7.6. Type "naa." - Network Address Authority .............64 124 4.2.8. Persistent State ........................................65 125 4.2.9. Message Synchronization and Steering ....................65 126 4.2.9.1. Sync/Steering and iSCSI PDU Length ..................67 127 4.3. iSCSI Session Types .........................................67 128 4.4. SCSI to iSCSI Concepts Mapping Model ........................67 129 4.4.1. iSCSI Architecture Model ................................68 130 4.4.2. SCSI Architecture Model .................................71 131 4.4.3. Consequences of the Model ...............................73 132 4.4.3.1. I_T Nexus State .....................................74 133 4.4.3.2. Reservations ........................................74 134 4.5. iSCSI UML Model .............................................75 135 4.6. Request/Response Summary ....................................78 136 4.6.1. Request/Response Types Carrying SCSI Payload ............78 137 4.6.1.1. SCSI-Command ........................................78 138 4.6.1.2. SCSI-Response .......................................79 139 4.6.1.3. Task Management Function Request ....................79 140 4.6.1.4. Task Management Function Response ...................80 141 4.6.1.5. SCSI Data-out and SCSI Data-in ......................80 142 4.6.1.6. Ready To Transfer (R2T) .............................81 143 4.6.2. Requests/Responses carrying SCSI and iSCSI Payload ......82 144 4.6.2.1. Asynchronous Message ................................82 145 4.6.3. Requests/Responses Carrying iSCSI Only Payload ..........82 146 4.6.3.1. Text Request and Text Response ......................82 147 4.6.3.2. Login Request and Login Response ....................83 148 4.6.3.3. Logout Request and Response .........................84 149 4.6.3.4. SNACK Request .......................................84 150 4.6.3.5. Reject ..............................................84 151 4.6.3.6. NOP-Out Request and NOP-In Response .................85 152 5. SCSI Mode Parameters for iSCSI..................................86 154 6. Login and Full Feature Phase Negotiation........................87 155 6.1. Text Format .................................................88 156 6.2. Text Mode Negotiation .......................................92 157 6.2.1. List negotiations .......................................96 158 6.2.2. Simple-value Negotiations ...............................97 159 6.3. Login Phase .................................................98 160 6.3.1. Login Phase Start ...................................... 101 161 6.3.2. iSCSI Security Negotiation ............................. 104 162 6.3.3. Operational Parameter Negotiation During the Login Phase 105 163 6.3.4. Connection Reinstatement ............................... 106 164 6.3.5. Session Reinstatement, Closure, and Timeout ............ 107 165 6.3.5.1. Loss of Nexus Notification ..........................107 166 6.3.6. Session Continuation and Failure ....................... 108 167 6.4. Operational Parameter Negotiation Outside the Login Phase .. 108 168 7. iSCSI Error Handling and Recovery.............................. 110 169 7.1. Overview ................................................... 110 170 7.1.1. Background ............................................. 110 171 7.1.2. Goals .................................................. 110 172 7.1.3. Protocol Features and State Expectations ............... 111 173 7.1.4. Recovery Classes ....................................... 112 174 7.1.4.1. Recovery Within-command ............................ 113 175 7.1.4.2. Recovery Within-connection ......................... 114 176 7.1.4.3. Connection Recovery ................................ 115 177 7.1.4.4. Session Recovery ................................... 116 178 7.1.5. Error Recovery Hierarchy ............................... 116 179 7.2. Retry and Reassign in Recovery ............................. 118 180 7.2.1. Usage of Retry ......................................... 118 181 7.2.2. Allegiance Reassignment ................................ 119 182 7.3. Usage Of Reject PDU in Recovery ............................ 120 183 7.4. Error Recovery Considerations for Discovery Sessions ....... 121 184 7.4.1. ErrorRecoveryLevel for Discovery Sessions .............. 121 185 7.4.2. Reinstatement Semantics for Discovery Sessions ......... 121 186 7.4.2.1. Unnamed Discovery Sessions ......................... 122 187 7.4.2.2. Named Discovery Session ............................ 123 188 7.4.3. Target PDUs During Discovery ........................... 123 189 7.5. Connection Timeout Management .............................. 123 190 7.5.1. Timeouts on Transport Exception Events ................. 124 191 7.5.2. Timeouts on Planned Decommissioning .................... 124 192 7.6. Implicit Termination of Tasks .............................. 124 193 7.7. Format Errors .............................................. 125 194 7.8. Digest Errors .............................................. 126 195 7.9. Sequence Errors ............................................ 128 196 7.10. Message Error Checking .................................... 128 197 7.11. SCSI Timeouts ............................................. 129 198 7.12. Negotiation Failures ...................................... 130 199 7.13. Protocol Errors ........................................... 130 200 7.14. Connection Failures ....................................... 131 201 7.15. Session Errors ............................................ 132 202 8. State Transitions.............................................. 133 203 8.1. Standard Connection State Diagrams ......................... 133 204 8.1.1. State Descriptions for Initiators and Targets .......... 133 205 8.1.2. State Transition Descriptions for Initiators and Targets 134 206 8.1.3. Standard Connection State Diagram for an Initiator ..... 138 207 8.1.4. Standard Connection State Diagram for a Target ......... 140 208 8.2. Connection Cleanup State Diagram for Initiators and Targets 142 209 8.2.1. State Descriptions for Initiators and Targets .......... 144 210 8.2.2. State Transition Descriptions for Initiators and Targets 145 211 8.3. Session State Diagrams ..................................... 147 212 8.3.1. Session State Diagram for an Initiator ............... 147 213 8.3.2. Session State Diagram for a Target ................... 148 214 8.3.3. State Descriptions for Initiators and Targets ........ 149 215 8.3.4. State Transition Descriptions for Initiators and Targets150 216 9. Security Considerations........................................ 152 217 9.1. iSCSI Security Mechanisms .................................. 152 218 9.2. In-band Initiator-Target Authentication .................... 153 219 9.2.1. CHAP Considerations .................................... 154 220 9.2.2. SRP Considerations ..................................... 156 221 9.3. IPsec ...................................................... 157 222 9.3.1. Data Integrity and Authentication ...................... 157 223 9.3.2. Confidentiality ........................................ 158 224 9.3.3. Policy, Security Associations, and Cryptographic Key 225 Management .................................................... 159 226 9.4. Security Considerations for the X#NodeArchitecture Key ..... 161 227 10. Notes to Implementers......................................... 163 228 10.1. Multiple Network Adapters ................................. 163 229 10.1.1. Conservative Reuse of ISIDs ........................... 163 230 10.1.2. iSCSI Name, ISID, and TPGT Use ........................ 164 231 10.2. Autosense and Auto Contingent Allegiance (ACA) ............ 166 232 10.3. iSCSI Timeouts ............................................ 166 233 10.4. Command Retry and Cleaning Old Command Instances .......... 167 234 10.5. Synch and Steering Layer and Performance .................. 168 235 10.6. Considerations for State-dependent Devices and Long-lasting 236 SCSI Operations ................................................. 168 237 10.6.1. Determining the Proper ErrorRecoveryLevel ............. 169 238 10.7. Multi-task Abort Implementation Considerations ............ 170 239 11. iSCSI PDU Formats............................................. 171 240 11.1. iSCSI PDU Length and Padding .............................. 171 241 11.2. PDU Template, Header, and Opcodes ......................... 171 242 11.2.1. Basic Header Segment (BHS) ............................ 172 243 11.2.1.1. I ................................................. 173 244 11.2.1.2. Opcode ............................................ 173 245 11.2.1.3. Final (F) bit ..................................... 175 246 11.2.1.4. Opcode-specific Fields .............................175 247 11.2.1.5. TotalAHSLength .....................................175 248 11.2.1.6. DataSegmentLength ..................................175 249 11.2.1.7. LUN ................................................175 250 11.2.1.8. Initiator Task Tag .................................176 251 11.2.2. Additional Header Segment (AHS) ....................... 176 252 11.2.2.1. AHSType ............................................176 253 11.2.2.2. AHSLength ..........................................177 254 11.2.2.3. Extended CDB AHS ...................................177 255 11.2.2.4. Bidirectional Expected Read-Data Length AHS ........177 256 11.2.3. Header Digest and Data Digest ......................... 178 257 11.2.4. Data Segment .......................................... 178 258 11.3. SCSI Command .............................................. 178 259 11.3.1. Flags and Task Attributes (byte 1) .................... 179 260 11.3.2. CmdSN - Command Sequence Number ....................... 180 261 11.3.3. ExpStatSN ............................................. 181 262 11.3.4. Expected Data Transfer Length ......................... 181 263 11.3.5. CDB - SCSI Command Descriptor Block ................... 182 264 11.3.6. Data Segment - Command Data ........................... 182 265 11.4. SCSI Response ............................................. 182 266 11.4.1. Flags (byte 1) ........................................ 183 267 11.4.2. Status ................................................ 184 268 11.4.3. Response .............................................. 185 269 11.4.4. SNACK Tag ............................................. 186 270 11.4.5. Residual Count ........................................ 186 271 11.4.5.1. Field Semantics ....................................186 272 11.4.5.2. Residuals Concepts Overview ........................187 273 11.4.5.3. SCSI REPORT LUNS and Residual Overflow .............187 274 11.4.6. Bidirectional Read Residual Count ..................... 189 275 11.4.7. Data Segment - Sense and Response Data Segment ........ 189 276 11.4.7.1. SenseLength ........................................190 277 11.4.7.2. Sense Data .........................................190 278 11.4.8. ExpDataSN ............................................. 191 279 11.4.9. StatSN - Status Sequence Number ....................... 191 280 11.4.10. ExpCmdSN - Next Expected CmdSN from this Initiator ... 192 281 11.4.11. MaxCmdSN - Maximum CmdSN from this Initiator ......... 192 283 11.5. Task Management Function Request ..........................193 284 11.5.1. Function ..............................................193 285 11.5.2. TotalAHSLength and DataSegmentLength ..................197 286 11.5.3. LUN ...................................................197 287 11.5.4. Referenced Task Tag ...................................197 288 11.5.5. RefCmdSN ..............................................197 289 11.5.6. ExpDataSN .............................................198 290 11.6. Task Management Function Response .........................198 291 11.6.1. Response ..............................................199 292 11.6.2. TotalAHSLength and DataSegmentLength ..................201 293 11.7. SCSI Data-out & SCSI Data-in ..............................201 294 11.7.1. F (Final) Bit .........................................204 295 11.7.2. A (Acknowledge) bit ...................................204 296 11.7.3. Flags (byte 1) ........................................205 297 11.7.4. Target Transfer Tag and LUN ...........................206 298 11.7.5. DataSN ................................................206 299 11.7.6. Buffer Offset .........................................206 300 11.7.7. DataSegmentLength .....................................207 301 11.8. Ready To Transfer (R2T) ...................................208 302 11.8.1. TotalAHSLength and DataSegmentLength ..................210 303 11.8.2. R2TSN .................................................210 304 11.8.3. StatSN ................................................210 305 11.8.4. Desired Data Transfer Length and Buffer Offset ........210 306 11.8.5. Target Transfer Tag ...................................210 307 11.9. Asynchronous Message ......................................211 308 11.9.1. AsyncEvent ............................................212 309 11.9.2. AsyncVCode ............................................215 310 11.9.3. LUN ...................................................215 311 11.9.4. Sense Data and iSCSI Event Data .......................215 312 11.9.4.1. SenseLength .......................................216 313 11.10. Text Request .............................................216 314 11.10.1. F (Final) Bit ........................................218 315 11.10.2. C (Continue) Bit .....................................218 316 11.10.3. Initiator Task Tag ...................................218 317 11.10.4. Target Transfer Tag ..................................218 318 11.10.5. Text .................................................219 320 11.11. Text Response ............................................220 321 11.11.1. F (Final) Bit ........................................221 322 11.11.2. C (Continue) Bit .....................................222 323 11.11.3. Initiator Task Tag ...................................222 324 11.11.4. Target Transfer Tag ..................................222 325 11.11.5. StatSN ...............................................223 326 11.11.6. Text Response Data ...................................223 327 11.12. Login Request ............................................223 328 11.12.1. T (Transit) Bit ......................................224 329 11.12.2. C (Continue) Bit .....................................225 330 11.12.3. CSG and NSG ..........................................225 331 11.12.4. Version ..............................................225 332 11.12.4.1. Version-max ......................................225 333 11.12.4.2. Version-min ......................................226 334 11.12.5. ISID .................................................226 335 11.12.6. TSIH .................................................228 336 11.12.7. Connection ID - CID ..................................228 337 11.12.8. CmdSN ................................................228 338 11.12.9. ExpStatSN ............................................229 339 11.12.10. Login Parameters ....................................229 340 11.13. Login Response ...........................................229 341 11.13.1. Version-max ..........................................230 342 11.13.2. Version-active .......................................231 343 11.13.3. TSIH .................................................231 344 11.13.4. StatSN ...............................................231 345 11.13.5. Status-Class and Status-Detail .......................231 346 11.13.6. T (Transit) bit ......................................235 347 11.13.7. C (Continue) Bit .....................................236 348 11.13.8. Login Parameters .....................................236 349 11.14. Logout Request ...........................................236 350 11.14.1. Reason Code ..........................................239 351 11.14.2. TotalAHSLength and DataSegmentLength .................240 352 11.14.3. CID ..................................................240 353 11.14.4. ExpStatSN ............................................240 354 11.14.5. Implicit termination of tasks ........................240 355 11.15. Logout Response ..........................................241 356 11.15.1. Response ............................................ 242 357 11.15.2. TotalAHSLength and DataSegmentLength ................ 243 358 11.15.3. Time2Wait ........................................... 243 359 11.15.4. Time2Retain ......................................... 243 360 11.16. SNACK Request ........................................... 244 361 11.16.1. Type ................................................ 245 362 11.16.2. Data Acknowledgement ................................ 246 363 11.16.3. Resegmentation ...................................... 246 364 11.16.4. Initiator Task Tag .................................. 247 365 11.16.5. Target Transfer Tag or SNACK Tag .................... 247 366 11.16.6. BegRun .............................................. 248 367 11.16.7. RunLength ........................................... 248 368 11.17. Reject .................................................. 249 369 11.17.1. Reason .............................................. 250 370 11.17.2. DataSN/R2TSN ........................................ 251 371 11.17.3. StatSN, ExpCmdSN and MaxCmdSN ....................... 251 372 11.17.4. Complete Header of Bad PDU .......................... 252 373 11.18. NOP-Out ................................................. 252 374 11.18.1. Initiator Task Tag .................................. 253 375 11.18.2. Target Transfer Tag ................................. 253 376 11.18.3. Ping Data ........................................... 254 377 11.19. NOP-In .................................................. 255 378 11.19.1. Target Transfer Tag ................................. 256 379 11.19.2. StatSN .............................................. 256 380 11.19.3. LUN ................................................. 256 381 12. iSCSI Security Text Keys and Authentication Methods.......... 257 382 12.1. AuthMethod ............................................... 257 383 12.1.1. Kerberos ............................................. 259 384 12.1.2. Secure Remote Password (SRP) ......................... 260 385 12.1.3. Challenge Handshake Authentication Protocol (CHAP) ... 261 386 13. Login/Text Operational Text Keys............................. 264 387 13.1. HeaderDigest and DataDigest ............................ 264 388 13.2. MaxConnections ......................................... 267 389 13.3. SendTargets ............................................ 267 390 13.4. TargetName ............................................. 267 391 13.5. InitiatorName ............................................ 268 392 13.6. TargetAlias .............................................. 269 393 13.7. InitiatorAlias ........................................... 269 394 13.8. TargetAddress ............................................ 270 395 13.9. TargetPortalGroupTag ..................................... 271 396 13.10. InitialR2T .............................................. 271 397 13.11. ImmediateData ........................................... 272 398 13.12. MaxRecvDataSegmentLength ................................ 273 399 13.13. MaxBurstLength .......................................... 274 400 13.14. FirstBurstLength ........................................ 274 401 13.15. DefaultTime2Wait ........................................ 275 402 13.16. DefaultTime2Retain ...................................... 275 403 13.17. MaxOutstandingR2T ....................................... 276 404 13.18. DataPDUInOrder .......................................... 276 405 13.19. DataSequenceInOrder ..................................... 277 406 13.20. ErrorRecoveryLevel ...................................... 277 407 13.21. SessionType ............................................. 278 408 13.22. The Private Extension Key Format ........................ 279 409 13.23. TaskReporting ........................................... 279 410 13.24. iSCSIProtocolLevel Negotiation .......................... 280 411 13.25. Obsoleted Keys .......................................... 280 412 13.26. X#NodeArchitecture ...................................... 281 413 13.26.1. Definition .......................................... 281 414 13.26.2. Implementation Requirements ......................... 282 415 14. Rationale for revised IANA Considerations.................... 283 417 15. IANA Considerations.......................................... 285 419 Appendix A. Examples ............................................ 292 420 Read Operation Example ......................................... 292 421 Write Operation Example ........................................ 293 422 R2TSN/DataSN Use Examples ...................................... 293 423 CRC Examples ................................................... 297 424 Appendix B. Login Phase Examples ................................ 299 426 Appendix C. SendTargets Operation ............................... 309 427 Appendix D. Algorithmic Presentation of Error Recovery Classes .. 314 428 D.2.1. Procedure Descriptions ................................ 316 429 Appendix E. Clearing Effects of Various Events on Targets ....... 333 430 1. Introduction 432 The Small Computer Systems Interface (SCSI) is a popular family of 433 protocols for communicating with I/O devices, especially storage 434 devices. SCSI is a client-server architecture. Clients of a SCSI 435 interface are called "initiators". Initiators issue SCSI 436 "commands" to request services from components, logical units of a 437 server known as a "target". A "SCSI transport" maps the client- 438 server SCSI protocol to a specific interconnect. An Initiator is 439 one endpoint of a SCSI transport and a target is the other 440 endpoint. 442 The SCSI protocol has been mapped over various transports, 443 including Parallel SCSI, IPI, IEEE-1394 (firewire) and Fibre 444 Channel. These transports are I/O specific and have limited 445 distance capabilities. 447 The iSCSI protocol defined in this document describes a means of 448 transporting of the SCSI packets over TCP/IP, providing for an 449 interoperable solution which can take advantage of existing 450 Internet infrastructure, Internet management facilities and 451 address distance limitations. 453 2. Acronyms, Definitions and Document Summary 455 2.1. Acronyms 457 Acronym Definition 458 -------------------------------------------------------------- 459 3DES Triple Data Encryption Standard 460 ACA Auto Contingent Allegiance 461 AEN Asynchronous Event Notification 462 AES Advanced Encryption Standard 463 AH Additional Header (not the IPsec AH!) 464 AHS Additional Header Segment 465 API Application Programming Interface 466 ASC Additional Sense Code 467 ASCII American Standard Code for Information Interchange 468 ASCQ Additional Sense Code Qualifier 469 BHS Basic Header Segment 470 CBC Cipher Block Chaining 471 CD Compact Disk 472 CDB Command Descriptor Block 473 CHAP Challenge Handshake Authentication Protocol 474 CID Connection ID 475 CO Connection Only 476 CRC Cyclic Redundancy Check 477 CRL Certificate Revocation List 478 CSG Current Stage 479 CSM Connection State Machine 480 DES Data Encryption Standard 481 DNS Domain Name Server 482 DOI Domain of Interpretation 483 DVD Digital Versatile Disk 484 EDTL Expected Data Transfer Length 485 ESP Encapsulating Security Payload 486 EUI Extended Unique Identifier 487 FFP Full Feature Phase 488 FFPO Full Feature Phase Only 489 Gbps Gigabits per Second 490 HBA Host Bus Adapter 491 HMAC Hashed Message Authentication Code 492 I_T Initiator_Target 494 I_T_L Initiator_Target_LUN 495 IANA Internet Assigned Numbers Authority 496 IB InfiniBand 497 ID Identifier 498 IDN Internationalized Domain Name 499 IEEE Institute of Electrical & Electronics Engineers 500 IETF Internet Engineering Task Force 501 IKE Internet Key Exchange 502 I/O Input-Output 503 IO Initialize Only 504 IP Internet Protocol 505 IPsec Internet Protocol Security 506 IPv4 Internet Protocol Version 4 507 IPv6 Internet Protocol Version 6 508 IQN iSCSI Qualified Name 509 iSCSI Internet SCSI 510 iSER iSCSI Extensions for RDMA 511 ISID Initiator Session ID 512 iSNS Internet Storage Name Service (see [RFC4171]) 513 ITN iSCSI Target Name 514 ITT Initiator Task Tag 515 KRB5 Kerberos V5 516 LFL Lower Functional Layer 517 LTDS Logical-Text-Data-Segment 518 LO Leading Only 519 LU Logical Unit 520 LUN Logical Unit Number 521 MAC Message Authentication Codes 522 NA Not Applicable 523 NAA Network Address Authority 524 NIC Network Interface Card 525 NOP No Operation 526 NSG Next Stage 527 OS Operating System 528 PDU Protocol Data Unit 529 PKI Public Key Infrastructure 530 R2T Ready To Transfer 531 R2TSN Ready To Transfer Sequence Number 532 RDMA Remote Direct Memory Access 533 RFC Request For Comments 534 SAM SCSI Architecture Model 535 SAM2 SCSI Architecture Model - 2 536 SAN Storage Area Network 537 SAS Serial Attached SCSI 538 SCSI Small Computer Systems Interface 539 SN Sequence Number 540 SNACK Selective Negative Acknowledgment - also 541 Sequence Number Acknowledgement for data 542 SPDTL SCSI-Presented Data Transfer Length 543 SPKM Simple Public-Key Mechanism 544 SRP Secure Remote Password 545 SSID Session ID 546 SW Session-Wide 547 TCB Task Control Block 548 TCP Transmission Control Protocol 549 TMF Task Management Function 550 TPGT Target Portal Group Tag 551 TSIH Target Session Identifying Handle 552 TTT Target Transfer Tag 553 UA Unit Attention 554 UFL Upper Functional Layer 555 ULP Upper Level Protocol 556 URN Uniform Resource Names 557 UTF Universal Transformation Format 558 WG Working Group 560 2.2. Definitions 562 - Alias: An alias string can also be associated with an iSCSI 563 Node. The alias allows an organization to associate a user- 564 friendly string with the iSCSI Name. However, the alias string is 565 not a substitute for the iSCSI Name. 567 - CID (Connection ID): Connections within a session are identified 568 by a connection ID. It is a unique ID for this connection within 569 the session for the initiator. It is generated by the initiator 570 and presented to the target during login requests and during 571 logouts that close connections. 573 - Connection: A connection is a TCP connection. Communication 574 between the initiator and target occurs over one or more TCP 575 connections. The TCP connections carry control messages, SCSI 577 commands, parameters, and data within iSCSI Protocol Data Units 578 (iSCSI PDUs). 580 - I/O Buffer:A buffer that is used in a SCSI Read or Write 581 operation so SCSI data may be sent from or received into that 582 buffer. For a read or write data transfer to take place for a 583 task, an I/O Buffer is required on the initiator and at least one 584 is required on the 585 target. 587 - INCITS: INCITS stands for InterNational Committee of Information 588 Technology Standards. The INCITS has a broad standardization scope 589 within the field of Information and Communications Technologies 590 (ICT), encompassing storage, processing, transfer, display, 591 management, organization, and retrieval of information. INCITS 592 serves as ANSI's Technical Advisory Group for the ISO/IEC Joint 593 Technical Committee 1 (JTC 1). See http://www.incits.org. 595 - InfiniBand: An I/O architecture originally intended to replace 596 PCI and to address high performance server interconnectivity [IB]. 598 - iSCSI Device: A SCSI Device using an iSCSI service delivery 599 subsystem. Service Delivery Subsystem is defined by [SAM2] as a 600 transport mechanism for SCSI commands and responses. 602 - iSCSI Initiator Name: The iSCSI Initiator Name specifies the 603 worldwide unique name of the initiator. 605 - iSCSI Initiator Node: The "initiator" device. The word 606 "initiator" has been appropriately qualified as either a port or a 607 device in the rest of the document when the context is ambiguous. 608 All unqualified usages of "initiator" refer to an initiator port 609 (or device) depending on the context. 611 - iSCSI Layer: This layer builds/receives iSCSI PDUs and 612 relays/receives them to/from one or more TCP connections that form 613 an initiator-target "session". 615 - iSCSI Name: The name of an iSCSI initiator or iSCSI target. 617 - iSCSI Node: The iSCSI Node represents a single iSCSI initiator 618 or iSCSI target or a single instance of each. There are one or 619 more iSCSI Nodes within a Network Entity. The iSCSI Node is 620 accessible via one or more Network Portals. An iSCSI Node is 621 identified by its iSCSI Name. The separation of the iSCSI Name 622 from the addresses used by and for the iSCSI Node allows multiple 623 iSCSI nodes to use the same address, and the same iSCSI node to 624 use multiple addresses. 626 - iSCSI Target Name: The iSCSI Target Name specifies the worldwide 627 unique name of the target. 629 - iSCSI Target Node: The "target" device. The word "target" has 630 been appropriately qualified as either a port or a device in the 631 rest of the document when the context is ambiguous. All 632 unqualified usages of "target" refer to a target port (or device) 633 depending on the context. 635 - iSCSI Task: An iSCSI task is an iSCSI request for which a 636 response is expected. 638 - iSCSI Transfer Direction: The iSCSI transfer direction is 639 defined with regard to the initiator. Outbound or outgoing 640 transfers are transfers from the initiator to the target, while 641 inbound or incoming transfers are from the target to the 642 initiator. 644 - ISID: The initiator part of the Session Identifier. It is 645 explicitly specified by the initiator during Login. 647 - I_T nexus: According to [SAM2], the I_T nexus is a relationship 648 between a SCSI Initiator Port and a SCSI Target Port. For iSCSI, 649 this relationship is a session, defined as a relationship between 650 an iSCSI Initiator's end of the session (SCSI Initiator Port) and 651 the iSCSI Target's Portal Group. The I_T nexus can be identified 652 by the conjunction of the SCSI port names; that is, the I_T nexus 653 identifier is the tuple (iSCSI Initiator Name + ',i,'+ ISID, iSCSI 654 Target Name + ',t,'+ Portal Group Tag). 656 - NAA: Network Address Authority, a naming format defined by the 657 INCITS T11 Fibre Channel protocols [FC-FS3]. 659 - Network Entity: The Network Entity represents a device or 660 gateway that is accessible from the IP network. A Network Entity 661 must have one or more Network Portals, each of which can be used 662 to gain access to the IP network by some iSCSI Nodes contained in 663 that Network Entity. 665 - Network Portal: The Network Portal is a component of a Network 666 Entity that has a TCP/IP network address and that may be used by 667 an iSCSI Node within that Network Entity for the connection(s) 668 within one of its iSCSI sessions. A Network Portal in an initiator 669 is identified by its IP address. A Network Portal in a target is 670 identified by its IP address and its listening TCP port. 672 - Originator: In a negotiation or exchange, the party that 673 initiates the negotiation or exchange. 675 - PDU (Protocol Data Unit): The initiator and target divide their 676 communications into messages. The term "iSCSI protocol data unit" 677 (iSCSI PDU) is used for these messages. 679 - Portal Groups: iSCSI supports multiple connections within the 680 same session; some implementations will have the ability to 681 combine connections in a session across multiple Network Portals. 682 A Portal Group defines a set of Network Portals within an iSCSI 683 Network Entity that collectively supports the capability of 684 coordinating a session with connections spanning these portals. 685 Not all Network Portals within a Portal Group need participate in 686 every session connected through that Portal Group. One or more 687 Portal Groups may provide access to an iSCSI Node. Each Network 688 Portal, as utilized by a given iSCSI Node, belongs to exactly one 689 portal group within that node. 691 - Portal Group Tag: This 16-bit quantity identifies a Portal Group 692 within an iSCSI Node. All Network Portals with the same portal 693 group tag in the context of a given iSCSI Node are in the same 694 Portal Group. 696 - Recovery R2T: An R2T generated by a target upon detecting the 697 loss of one or more Data-Out PDUs through one of the following 698 means: a digest error, a sequence error, or a sequence reception 699 timeout. A recovery R2T carries the next unused R2TSN, but 700 requests all or part of the data burst that an earlier R2T (with a 701 lower R2TSN) had already requested. 703 - Responder: In a negotiation or exchange, the party that responds 704 to the originator of the negotiation or exchange. 706 - SAS: Serial Attached SCSI. The Serial Attached SCSI (SAS) 707 standard contains both a physical layer compatible with Serial 708 ATA, and protocols for transporting SCSI commands to SAS devices 709 and ATA commands to SATA devices [SAS]. 711 - SCSI Device: This is the SAM2 term for an entity that contains 712 one or more SCSI ports that are connected to a service delivery 713 subsystem and supports a SCSI application protocol. For example, a 714 SCSI Initiator Device contains one or more SCSI Initiator Ports 715 and zero or more application clients. A Target Device contains one 716 or more SCSI Target Ports and one or more device servers and 717 associated logical units. For iSCSI, the SCSI Device is the 718 component within an iSCSI Node that provides the SCSI 719 functionality. As such, there can be, at most, one SCSI Device 720 within a given iSCSI Node. Access to the SCSI Device can only be 721 achieved in an iSCSI normal operational session. The SCSI Device 722 Name is defined to be the iSCSI Name of the node. 724 - SCSI Layer: This builds/receives SCSI CDBs (Command Descriptor 725 Blocks) and relays/receives them with the remaining command 726 execute [SAM2] parameters to/from the iSCSI Layer. 728 - Session: The group of TCP connections that link an initiator 729 with a target form a session (loosely equivalent to a SCSI I-T 730 nexus). TCP connections can be added and removed from a session. 731 Across all connections within a session, an initiator sees one and 732 the same target. 734 - SCSI Port: This is the SAM2 term for an entity in a SCSI Device 735 that provides the SCSI functionality to interface with a service 736 delivery subsystem. For iSCSI, the definition of the SCSI 737 Initiator Port and the SCSI Target Port are different. 739 - SCSI Initiator Port: This maps to the endpoint of an iSCSI 740 normal operational session. An iSCSI normal operational session is 741 negotiated through the login process between an iSCSI initiator 742 node and an iSCSI target node. At successful completion of this 743 process, a SCSI Initiator Port is created within the SCSI 744 Initiator Device. The SCSI Initiator Port Name and SCSI Initiator 745 Port Identifier are both defined to be the iSCSI Initiator Name 746 together with (a) a label that identifies it as an initiator port 747 name/identifier and (b) the ISID portion of the session 748 identifier. 750 - SCSI Port Name: A name made up as UTF-8 characters and includes 751 the iSCSI Name + 'i' or 't' + ISID or Portal Group Tag. 753 - SCSI-Presented Data Transfer Length (SPDTL): SPDTL is the 754 aggregate data length of the data that the SCSI layer logically 755 "presents" to the iSCSI layer for a Data-In or Data-Out transfer 756 in the context of a SCSI task. For a bidirectional task, there are 757 two SPDTL values -- one for Data-In and one for Data-Out. Note 758 that the notion of "presenting" includes immediate data per the 759 data transfer model in [SAM2], and excludes overlapping data 760 transfers, if any, requested by the SCSI layer. 762 - SCSI Target Port: This maps to an iSCSI Target Portal Group. 764 - SCSI Target Port Name and SCSI Target Port Identifier: These are 765 both defined to be the iSCSI Target Name together with (a) a label 766 that identifies it as a target port name/identifier and (b) the 767 portal group tag. 769 - SSID (Session ID): A session between an iSCSI initiator and an 770 iSCSI target is defined by a session ID that is a tuple composed 771 of an initiator part (ISID) and a target part (Target Portal Group 772 Tag). The ISID is explicitly specified by the initiator at session 773 establishment. The Target Portal Group Tag is implied by the 774 initiator through the selection of the TCP endpoint at connection 775 establishment. The TargetPortalGroupTag key must also be returned 776 by the target as a confimation during connection establishment. 778 - T10: A technical committee within INCITS that develops standards 779 and technical reports on I/O interfaces, particularly the series 780 of SCSI (Small Computer Systems Interface) standards. See 781 http://www.t10.org. 783 - T11: A technical committee within INCITS responsible for 784 standards development in the areas of Intelligent Peripheral 785 Interface (IPI), High-Performance Parallel Interface (HIPPI) and 786 Fibre Channel (FC). See http://www.t11.org. 788 - Target Portal Group Tag: A numerical identifier (16-bit) for an 789 iSCSI Target Portal Group. 791 - Third-party: A term used in this document to denote nexus 792 objects (I_T or I_T_L) and iSCSI sessions that reap the side 793 effects of actions that take place in the context of a separate 794 iSCSI session, while being third parties to the action that caused 795 the side effects. One example of a third-party session is an 796 iSCSI session hosting an I_T_L nexus to an LU that is reset with 797 an LU Reset TMF via a separate I_T nexus. 799 - TSIH (Target Session Identifying Handle): A target assigned tag 800 for a session with a specific named initiator. The target 801 generates it during session establishment. Other than defining it 802 as a 16 bit binary string, its internal format and content are not 803 defined by this protocol but for the all 0 value that is reserved 804 and used by the initiator to indicate a new session. It is given 805 to the target during additional connection establishment for the 806 same session. 808 2.3. Summary of Changes 810 1) Consolidated RFCs 3720, 3980, 4850 and 5048, and made the 811 necessary editorial changes 812 2) iSCSIProtocolLevel is specified as "1" in Section 13.24, and 813 added a related normative reference to [iSCSI-SAM] draft 814 3) Markers and related keys were removed 815 4) SPKM authentication and related keys were removed 816 5) Added a new Section 13.25 on responding to obsoleted keys 817 6) Have explicitly allowed initiator+target implementations 818 throughout the text 819 7) Clarified in Section 4.2.7 that implementations SHOULD NOT 820 rely on SLP-based discovery 822 8) Added UML diagrams and related conventions in Section 3 823 9) FastAbort implementation is made a "SHOULD" requirement in 824 Section 4.2.3.4 from the previous "MUST" requirement. 825 10) Clarified in Section 6.2 that validity of NotUnderstood 826 response depends on iSCSIProtocolLevel 827 11) Required in Section 4.2.7.1 that iSCSI Target Name must be 828 the same as iSCSI Initiator Name for SCSI (composite) devices 829 with both roles 830 12) Clarified in Section 10.2 that ACA is a SHOULD requirement 831 only for iSCSI targets 832 13) Updated Section 9.3 to require the following: MUST implement 833 IPsec, 2400-series RFCs (IPsec v2, IKEv1) and SHOULD implement 834 IPsec, 4300-series RFCs (IPsec v3, IKEv2). 835 14) Prohibited usage of X# name prefix for new public keys in 836 Section 6.2 837 15) Prohibited usage of Y# name prefix for new digest extensions 838 in Section 13.1, and Z# name prefix for new authentication 839 method extensions in Section 12.1 840 16) Added a SHOULD requirement in Section 6.2 that initiators and 841 targets support at least six (6) exchanges during text 842 negotiation. 843 17) Added a clarification that Appendix.C is normative. 845 2.4. Conventions 847 In examples, "I->" and "T->" show iSCSI PDUs sent by the initiator 848 and target respectively. 850 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL 851 NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" 852 in this document are to be interpreted as described in RFC 2119 853 [RFC2119]. 855 iSCSI messages - PDUs - are represented by diagrams as in the 856 following example: 858 Byte/ 0 | 1 | 2 | 3 | 859 / | | | | 860 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 861 +---------------+---------------+---------------+---------------+ 862 0| Basic Header Segment (BHS) | 863 +---------------+---------------+---------------+---------------+ 864 +| | 865 +---------------+---------------+---------------+---------------+ 867 The diagrams include byte and bit numbering. 869 The following representation and ordering rules are observed in 870 this document: 872 - Word Rule 874 - Half-word Rule 876 - Byte Rule 878 2.4.1. Word Rule 880 A word holds four consecutive bytes. Whenever a word has numeric 881 content, it is considered an unsigned number in base 2 positional 882 representation with the lowest numbered byte (e.g., byte 0) bit 0 883 representing 2**31 and bit 1 representing 2**30 through lowest 884 numbered byte + 3 (e.g., byte 3) bit 7 representing 2**0. 886 Decimal and hexadecimal representation of word values map this 887 representation to decimal or hexadecimal positional notation. 889 2.4.2. Half-Word Rule 891 A half-word holds two consecutive bytes. Whenever a half-word has 892 numeric content it is considered an unsigned number in base 2 893 positional representation with the lowest numbered byte (e.g., 894 byte 0) bit 0 representing 2**15 and bit 1 representing 2**14 895 through lowest numbered byte + 1 (e.g., byte 1) bit 7 representing 896 2**0. 898 Decimal and hexadecimal representation of half-word values map 899 this representation to decimal or hexadecimal positional notation. 901 2.4.3. Byte Rule 903 For every PDU, bytes are sent and received in increasing numbered 904 order (network order). 906 Whenever a byte has numerical content it is considered an unsigned 907 number in base 2 positional representation with bit 0 representing 908 2**7 and bit 1 representing 2**6 through bit 7 representing 2**0. 910 3. UML Conventions 912 3.1. UML Conventions Overview 914 The SCSI Architecture Model (SAM) uses class diagrams and object 915 diagrams with notation that is based on the Unified Modeling 916 Language [UML]. Therefore, this document also uses UML to model 917 the relationships for SCSI and iSCSI objects. 919 A treatise on the graphical notation used in UML is beyond the 920 scope of this document. However, given the use of ASCII drawing 921 for UML static class diagrams, a description of the notational 922 conventions used in this document is included in the remainder of 923 this Section. 925 3.2. Multiplicity Notion 927 Not specified The number of instances of an attribute is not 928 specified. 930 1 One instance of the class or attribute exists. 932 0..* Zero or more instances of the class or attribute exist. 934 1..* One or more instances of the class or attribute exist. 936 0..1 Zero or one instance of the class or attribute exists. 938 n..m n to m instances of the class or attribute exist 939 (e.g., 2..8). 941 x, n..m Multiple disjoint instances of the class or 942 attribute exist (e.g., 2, 8..15). 944 3.3. Class Diagram Conventions 946 +--------------+ +--------------+ +--------------+ 947 | Class Name | | Class Name | | Class Name | 948 +--------------+ +--------------+ +--------------+ 949 | | | | 950 +--------------+ +--------------+ 951 | | 952 +--------------+ 953 The previous three diagrams are examples of a class with no 954 attributes and with no operations. 956 +-------------------+ +-------------------+ 957 | Class Name | | Class Name | 958 +-------------------+ +-------------------+ 959 | attribute 01[1] | | attribute 01[1] | 960 | attribute 02[1] | | attribute 02[1] | 961 +-------------------+ +-------------------+ 962 | | 963 +-------------------+ 964 The preceding two diagrams are examples of a class with attributes 965 and with no operations. 967 +------------------------+ 968 | Class Name | 969 +------------------------+ 970 | attribute 01[1..*] | 971 | attribute 02[1] | 972 +------------------------+ 973 | operation 01() | 974 | operation 02() | 975 +------------------------+ 976 The preceding diagram is an example of a class with attributes 977 that have a specified multiplicity and operations. 979 3.4. Class Diagram Notation for Associations 981 +-----------------+ 982 | Class A | 983 +-----------------+ association_name +-----------------+ 984 | attribute 01[1] |<------------------>| Class B | 985 | attribute 02[1] | 1..* 0..1 +-----------------+ 986 +-----------------+ | attribute 03[1] | 987 | operation 1() | +-----------------+ 988 +-----------------+ 989 The preceding diagram is an example where Class A knows about 990 Class B (i.e., read as "Class A association_name ClassB") and 991 Class B knows about Class A (i.e., read as "Class B 992 association_name Class A"). The use of association_name is 993 optional. The multiplicity notation (1..* and 0..1) indicates the 994 number of instances of the object. 996 +--------------------+ 997 | Class A | 998 +--------------------+ +--------------------+ 999 | attribute 01[1] |<-------------| Class B | 1000 | attribute 02[1] | 1 0..1 +--------------------+ 1001 +--------------------+ | attribute 03[1] | 1002 | operation 1() | +--------------------+ 1003 +--------------------+ 1004 The preceding diagram is an example where Class B knows about 1005 Class A (i.e., read as "Class B knows about Class A") but Class A 1006 does not know about Class B. 1008 +----------------------+ 1009 | Class A | 1010 +----------------------+ +--------------------+ 1011 | attribute 01[1] |----------->| Class B | 1012 | attribute 02[1] | 0..* 1 +--------------------+ 1013 +----------------------+ | attribute 03[1] | 1014 | operation 1() | +--------------------+ 1015 +----------------------+ 1016 The preceding diagram is an example where Class A knows about 1017 Class B (i.e., read as "Class A knows about Class B") but Class B 1018 does not know about Class A. 1020 3.5. Class Diagram Notation for Aggregations 1022 +---------------+ +--------------+ 1023 | Class whole |o------------| Class part | 1024 +---------------+ +--------------+ 1025 The preceding diagram is an example where Class whole is an 1026 aggregate that contains Class part and where Class part may 1027 continue to exist even if Class whole is removed (i.e., read as 1028 "the whole contains the part"). 1030 +---------------+ +--------------+ 1031 | Class whole |@------------| Class part | 1032 +---------------+ +--------------+ 1033 The preceding diagram is an example where Class whole is an 1034 aggregate that contains Class part where Class part only belongs 1035 to one Class whole, and the Class part does not continue to exist 1036 if the Class whole is removed (i.e., read as "the whole contains 1037 the part"). 1039 +-------------+ 1040 | | 1041 +-------------+ 1042 | | 1043 + =(a)= + 1044 | | 1045 The preceding diagram is an example where there is a constraint 1046 between the associations where the (a) footnote describes the 1047 constraint. 1049 3.6. Class Diagram Notation for Generalizations 1051 +---------------+ 1052 | Superclass | 1053 +-------^-------+ 1054 /_\ 1055 | 1056 +---------------+ 1057 | Subclass | 1058 +---------------+ 1059 The preceding diagram is an example where the subclass is a kind 1060 of superclass. A subclass shares all the attributes and 1061 operations of the superclass (i.e., the subclass inherits from the 1062 superclass). 1064 4. Overview 1066 4.1. SCSI Concepts 1068 The SCSI Architecture Model-2 [SAM2] describes in detail the 1069 architecture of the SCSI family of I/O protocols. This Section 1070 provides a brief background of the SCSI architecture and is 1071 intended to familiarize readers with its terminology. 1073 At the highest level, SCSI is a family of interfaces for 1074 requesting services from I/O devices, including hard drives, tape 1075 drives, CD and DVD drives, printers, and scanners. In SCSI 1076 terminology, an individual I/O device is called a "logical unit" 1077 (LU). 1079 SCSI is a client-server architecture. Clients of a SCSI interface 1080 are called "initiators". Initiators issue SCSI "commands" to 1081 request services from components, logical units, of a server known 1082 as a "target". The "device server" on the logical unit accepts 1083 SCSI commands and processes them. 1085 A "SCSI transport" maps the client-server SCSI protocol to a 1086 specific interconnect. Initiator is one endpoint of a SCSI 1087 transport. The "target" is the other endpoint. A target can 1088 contain multiple Logical Units (LUs). Each Logical Unit has an 1089 address within a target called a Logical Unit Number (LUN). 1091 A SCSI task is a SCSI command or possibly a linked set of SCSI 1092 commands. Some LUs support multiple pending (queued) tasks, but 1093 the queue of tasks is managed by the logical unit. The target uses 1094 an initiator provided "task tag" to distinguish between tasks. 1095 Only one command in a task can be outstanding at any given time. 1097 Each SCSI command results in an optional data phase and a required 1098 response phase. In the data phase, information can travel from the 1099 initiator to target (e.g., WRITE), target to initiator (e.g., 1100 READ), or in both directions. In the response phase, the target 1101 returns the final status of the operation, including any errors. 1103 Command Descriptor Blocks (CDB) are the data structures used to 1104 contain the command parameters that an initiator sends to a 1106 target. The CDB content and structure is defined by [SAM2] and 1107 device-type specific SCSI standards. 1109 4.2. iSCSI Concepts and Functional Overview 1111 The iSCSI protocol is a mapping of the SCSI command, event and 1112 task management model (see [SAM2]) over the TCP protocol. SCSI 1113 commands are carried by iSCSI requests and SCSI responses and 1114 status are carried by iSCSI responses. iSCSI also uses the request 1115 response mechanism for iSCSI protocol mechanisms. 1117 For the remainder of this document, the terms "initiator" and 1118 "target" refer to "iSCSI initiator node" and "iSCSI target node", 1119 respectively (see iSCSI) unless otherwise qualified. 1121 In keeping with similar protocols, the initiator and target divide 1122 their communications into messages. This document uses the term 1123 "iSCSI protocol data unit" (iSCSI PDU) for these messages. 1125 For performance reasons, iSCSI allows a "phase-collapse". A 1126 command and its associated data may be shipped together from 1127 initiator to target, and data and responses may be shipped 1128 together from targets. 1130 The iSCSI transfer direction is defined with respect to the 1131 initiator. Outbound or outgoing transfers are transfers from an 1132 initiator to a target, while inbound or incoming transfers are 1133 from a target to an initiator. 1135 An iSCSI task is an iSCSI request for which a response is 1136 expected. 1138 In this document "iSCSI request", "iSCSI command", request, or 1139 (unqualified) command have the same meaning. Also, unless 1140 otherwise specified, status, response, or numbered response have 1141 the same meaning. 1143 4.2.1. Layers and Sessions 1145 The following conceptual layering model is used to specify 1146 initiator and target actions and the way in which they relate to 1147 transmitted and received Protocol Data Units: 1149 - The SCSI layer builds/receives SCSI CDBs (Command Descriptor 1150 Blocks) and passes/receives them with the remaining command 1151 execute parameters ([SAM2]) to/from 1153 - the iSCSI layer that builds/receives iSCSI PDUs and 1154 relays/receives them to/from one or more TCP connections; 1155 the group of connections form an initiator-target "session". 1157 Communication between the initiator and target occurs over one or 1158 more TCP connections. The TCP connections carry control messages, 1159 SCSI commands, parameters, and data within iSCSI Protocol Data 1160 Units (iSCSI PDUs). The group of TCP connections that link an 1161 initiator with a target form a session (equivalent to a SCSI I_T 1162 nexus, see Section 4.4.2). A session is defined by a session ID 1163 that is composed of an initiator part and a target part. TCP 1164 connections can be added and removed from a session. Each 1165 connection within a session is identified by a connection ID 1166 (CID). 1168 Across all connections within a session, an initiator sees one 1169 "target image". All target identifying elements, such as LUN, are 1170 the same. A target also sees one "initiator image" across all 1171 connections within a session. Initiator-identifying elements, such 1172 as the Initiator Task Tag, are global across the session 1173 regardless of the connection on which they are sent or received. 1175 iSCSI targets and initiators MUST support at least one TCP 1176 connection and MAY support several connections in a session. For 1177 error recovery purposes, targets and initiators that support a 1178 single active connection in a session SHOULD support two 1179 connections during recovery. 1181 4.2.2. Ordering and iSCSI Numbering 1183 iSCSI uses Command and Status numbering schemes and a Data 1184 sequencing scheme. 1186 Command numbering is session-wide and is used for ordered command 1187 delivery over multiple connections. It can also be used as a 1188 mechanism for command flow control over a session. 1190 Status numbering is per connection and is used to enable missing 1191 status detection and recovery in the presence of transient or 1192 permanent communication errors. 1194 Data sequencing is per command or part of a command (R2T-triggered 1195 sequence) and is used to detect missing data and/or R2T PDUs due 1196 to header digest errors. 1198 Typically, fields in the iSCSI PDUs communicate the Sequence 1199 Numbers between the initiator and target. During periods when 1200 traffic on a connection is unidirectional, iSCSI NOP-Out/In PDUs 1201 may be utilized to synchronize the command and status ordering 1202 counters of the target and initiator. 1204 The iSCSI session abstraction is equivalent to the SCSI I_T nexus, 1205 and the iSCSI session provides an ordered command delivery from 1206 the SCSI initiator to the SCSI target. For detailed design 1207 considerations that led to the iSCSI session model as it is 1208 defined here and how it relates the SCSI command ordering features 1209 defined in SCSI specifications to the iSCSI concepts see 1210 [RFC3783]. 1212 4.2.2.1. Command Numbering and Acknowledging 1214 iSCSI performs ordered command delivery within a session. All 1215 commands (initiator-to-target PDUs) in transit from the initiator 1216 to the target are numbered. 1218 iSCSI considers a task to be instantiated on the target in 1219 response to every request issued by the initiator. A set of task 1220 management operations including abort and reassign (see Section 1221 11.5) may be performed on an iSCSI task - however an abort 1222 operation cannot be performed on a task management operation, and 1223 usage of reassign operation has certain constraints. See Section 1224 11.5.1 for the details. 1226 Some iSCSI tasks are SCSI tasks, and many SCSI activities are 1227 related to a SCSI task ([SAM2]). In all cases, the task is 1228 identified by the Initiator Task Tag for the life of the task. 1230 The command number is carried by the iSCSI PDU as CmdSN (Command- 1231 Sequence-Number). The numbering is session-wide. Outgoing iSCSI 1232 PDUs carry this number. The iSCSI initiator allocates CmdSNs with 1233 a 32-bit unsigned counter (modulo 2**32). Comparisons and 1234 arithmetic on CmdSN use Serial Number Arithmetic as defined in 1235 [RFC1982] where SERIAL_BITS = 32. 1237 Commands meant for immediate delivery are marked with an immediate 1238 delivery flag; they MUST also carry the current CmdSN. CmdSN MUST 1239 NOT advance after a command marked for immediate delivery is sent. 1241 Command numbering starts with the first login request on the first 1242 connection of a session (the leading login on the leading 1243 connection) and CmdSN MUST be incremented by 1, in a Serial Number 1244 Arithmetic sense as defined in [RFC1982], for every non-immediate 1245 command issued afterwards. 1247 If immediate delivery is used with task management commands, these 1248 commands may reach the target before the tasks on which they are 1249 supposed to act. However their CmdSN serves as a marker of their 1250 position in the stream of commands. The initiator and target MUST 1251 ensure that the SCSI task management functions specified in [SAM2] 1252 act in accordance with the [SAM2] specification. For example, both 1253 commands and responses appear as if delivered in order. Whenever 1254 CmdSN for an outgoing PDU is not specified by an explicit rule, 1255 CmdSN will carry the current value of the local CmdSN variable 1256 (see later in this Section). 1258 The means by which an implementation decides to mark a PDU for 1259 immediate delivery or by which iSCSI decides by itself to mark a 1260 PDU for immediate delivery are beyond the scope of this document. 1262 The number of commands used for immediate delivery is not limited 1263 and their delivery to execution is not acknowledged through the 1264 numbering scheme. An iSCSI target MAY reject immediate commands, 1265 e.g., due to lack of resources to accommodate additional commands. 1266 An iSCSI target MUST be able to handle at least one immediate task 1267 management command and one immediate non-task-management iSCSI 1268 command per connection at any time. 1270 In this document, delivery for execution means delivery to the 1271 SCSI execution engine or an iSCSI protocol specific execution 1272 engine (e.g., for text requests with public or private extension 1273 keys involving an execution component). With the exception of the 1274 commands marked for immediate delivery, the iSCSI target layer 1275 MUST deliver the commands for execution in the order specified by 1276 CmdSN. Commands marked for immediate delivery may be delivered by 1277 the iSCSI target layer for execution as soon as detected. iSCSI 1278 may avoid delivering some commands to the SCSI target layer if 1279 required by a prior SCSI or iSCSI action (e.g., CLEAR TASK SET 1280 Task Management request received before all the commands on which 1281 it was supposed to act). 1283 On any connection, the iSCSI initiator MUST send the commands in 1284 increasing order of CmdSN, except for commands that are 1285 retransmitted due to digest error recovery and connection 1286 recovery. 1288 For the numbering mechanism, the initiator and target maintain the 1289 following three variables for each session: 1291 - CmdSN - the current command Sequence Number, advanced by 1 1292 on each command shipped except for commands marked for 1293 immediate delivery (see Section 4.2.2.1). CmdSN always 1294 contains the number to be assigned to the next Command PDU. 1296 - ExpCmdSN - the next expected command by the target. The 1297 target acknowledges all commands up to, but not including, 1298 this number. The initiator treats all commands with CmdSN 1299 less than ExpCmdSN as acknowledged. The target iSCSI layer 1300 sets the ExpCmdSN to the largest non-immediate CmdSN that it 1301 can deliver for execution "plus 1" per [RFC1982]. There 1302 MUST NOT be any holes in the acknowledged CmdSN sequence. 1304 - MaxCmdSN - the maximum number to be shipped. The queuing 1305 capacity of the receiving iSCSI layer is MaxCmdSN - ExpCmdSN 1306 + 1. 1308 The initiator's ExpCmdSN and MaxCmdSN are derived from target-to- 1309 initiator PDU fields. Comparisons and arithmetic on ExpCmdSN and 1310 MaxCmdSN MUST use Serial Number Arithmetic as defined in [RFC1982] 1311 where SERIAL_BITS = 32. 1313 The target MUST NOT transmit a MaxCmdSN that is less than 1314 ExpCmdSN-1. For non-immediate commands, the CmdSN field can take 1315 any value from ExpCmdSN to MaxCmdSN inclusive. The target MUST 1316 silently ignore any non-immediate command outside of this range or 1317 non-immediate duplicates within the range. The CmdSN carried by 1318 immediate commands may lie outside the ExpCmdSN to MaxCmdSN range. 1319 For example, if the initiator has previously sent a non-immediate 1320 command carrying the CmdSN equal to MaxCmdSN, the target window is 1321 closed. For group task management commands issued as immediate 1322 commands, CmdSN indicates the scope of the group action (e.g., on 1323 ABORT TASK SET indicates which commands are to be aborted). 1325 MaxCmdSN and ExpCmdSN fields are processed by the initiator as 1326 follows: 1328 -If the PDU MaxCmdSN is less than the PDU ExpCmdSN-1 (in 1329 Serial Arithmetic Sense), they are both ignored. 1331 -If the PDU MaxCmdSN is greater than the local MaxCmdSN (in 1332 Serial Arithmetic Sense), it updates the local MaxCmdSN; 1333 otherwise, it is ignored. 1335 -If the PDU ExpCmdSN is greater than the local ExpCmdSN (in 1336 Serial Arithmetic Sense), it updates the local ExpCmdSN; 1337 otherwise, it is ignored. 1339 This sequence is required because updates may arrive out of order 1340 (e.g., the updates are sent on different TCP connections). 1342 iSCSI initiators and targets MUST support the command numbering 1343 scheme. 1345 A numbered iSCSI request will not change its allocated CmdSN, 1346 regardless of the number of times and circumstances in which it is 1347 reissued (see Section 7.2.1). At the target, CmdSN is only 1348 relevant while the command has not created any state related to 1349 its execution (execution state); afterwards, CmdSN becomes 1350 irrelevant. Testing for the execution state (represented by 1351 identifying the Initiator Task Tag) MUST precede any other action 1352 at the target. If no execution state is found, it is followed by 1353 ordering and delivery. If an execution state is found, it is 1354 followed by delivery if it has not already been delivered. 1356 If an initiator issues a command retry for a command with CmdSN R 1357 on a connection when the session CmdSN value is Q, it MUST NOT 1358 advance the CmdSN past R + 2**31 -1 unless the connection is no 1359 longer operational (i.e., it has returned to the FREE state, see 1360 Section 8.1.3), the connection has been reinstated (see Section 1361 6.3.4), or a non-immediate command with CmdSN equal or greater 1362 than Q was issued subsequent to the command retry on the same 1363 connection and the reception of that command is acknowledged by 1364 the target (see Section 10.4). 1366 A target command response or Data-in PDU with status MUST NOT 1367 precede the command acknowledgement. However, the acknowledgement 1368 MAY be included in the response or the Data-in PDU. 1370 4.2.2.2. Response/Status Numbering and Acknowledging 1372 Responses in transit from the target to the initiator are 1373 numbered. The StatSN (Status Sequence Number) is used for this 1374 purpose. StatSN is a counter maintained per connection. ExpStatSN 1375 is used by the initiator to acknowledge status. The status 1376 sequence number space is 32-bit unsigned-integers and the 1377 arithmetic operations are the regular mod(2**32) arithmetic. 1379 Status numbering starts with the Login response to the first Login 1380 request of the connection. The Login response includes an initial 1381 value for status numbering (any initial value is valid). 1383 To enable command recovery, the target MAY maintain enough state 1384 information for data and status recovery after a connection 1385 failure. A target doing so can safely discard all of the state 1386 information maintained for recovery of a command after the 1387 delivery of the status for the command (numbered StatSN) is 1388 acknowledged through ExpStatSN. 1390 A large absolute difference between StatSN and ExpStatSN may 1391 indicate a failed connection. Initiators MUST undertake recovery 1392 actions if the difference is greater than an implementation 1393 defined constant that MUST NOT exceed 2**31-1. 1395 Initiators and Targets MUST support the response-numbering scheme. 1397 4.2.2.3. Response Ordering 1399 4.2.2.3.1. Need for Response Ordering 1401 Whenever an iSCSI session is composed of multiple connections, the 1402 Response PDUs (task responses or TMF responses) originating in 1403 the target SCSI layer are distributed onto the multiple 1404 connections by the target iSCSI layer according to iSCSI 1405 connection allegiance rules. This process generally may not 1406 preserve the ordering of the responses by the time they are 1407 delivered to the initiator SCSI layer. 1409 Since ordering is not expected across SCSI responses anyway, this 1410 approach works fine in the general case. However, to address the 1411 special cases where some ordering is desired by the SCSI layer, 1412 the following "Response Fence" semantics are defined with respect 1413 to handling SCSI response messages as they are handed off from the 1414 SCSI protocol layer to the iSCSI layer. 1416 4.2.2.3.2. Response Ordering Model Description 1418 The target SCSI protocol layer hands off the SCSI response 1419 messages to the target iSCSI layer by invoking the "Send Command 1420 Complete" protocol data service ([SAM2], clause 5.4.2) and "Task 1421 Management Function Executed" ([SAM2], clause 6.9) service. On 1422 receiving the SCSI response message, the iSCSI layer exhibits the 1423 Response Fence behavior for certain SCSI response messages 1424 (Section 4.2.2.3.4 describes the specific instances where the 1425 semantics must be realized). 1427 Whenever the Response Fence behavior is required for a SCSI 1428 response message, the target iSCSI layer MUST ensure that the 1429 following conditions are met in delivering the response message to 1430 the initiator iSCSI layer: 1432 - Response with Response Fence MUST be delivered 1433 chronologically after all the "preceding" responses on the 1434 I_T_L nexus, if the preceding responses are delivered at 1435 all, to the initiator iSCSI layer. 1437 - Response with Response Fence MUST be delivered 1438 chronologically prior to all the "following" responses on 1439 the I_T_L nexus. 1441 The "preceding" and "following" notions refer to the order of 1442 handoff of a response message from the target SCSI protocol layer 1443 to the target iSCSI layer. 1445 4.2.2.3.3. iSCSI Semantics with the Interface Model 1447 Whenever the TaskReporting key (Section 13.23) is negotiated to 1448 ResponseFence or FastAbort for an iSCSI session and the Response 1449 Fence behavior is required for a SCSI response message, the target 1450 iSCSI layer MUST perform the actions described in this Section for 1451 that session. 1453 a) If it is a single-connection session, no special 1454 processing is required. The standard SCSI Response PDU 1455 build and dispatch process happens. 1456 b) If it is a multi-connection session, the target iSCSI 1457 layer takes note of the last-sent and unacknowledged 1458 StatSN on each of the connections in the iSCSI session, 1459 and waits for an acknowledgement (NOP-In PDUs MAY be used 1460 to solicit acknowledgements as needed in order to 1461 accelerate this process) of each such StatSN to clear the 1462 fence. The SCSI response requiring Response Fence 1463 behavior MUST NOT be sent to the initiator before 1464 acknowledgements are received for each of the 1465 unacknowledged StatSNs. 1466 c) The target iSCSI layer must wait for an acknowledgement 1467 of the SCSI Response PDU that carried the SCSI response 1468 requiring the Response Fence behavior. The fence MUST be 1469 considered cleared only after receiving the 1470 acknowledgement. 1471 d) All further status processing for the LU is resumed only 1472 after clearing the fence. If any new responses for the 1473 I_T_L nexus are received from the SCSI layer before the 1474 fence is cleared, those Response PDUs MUST be held and 1475 queued at the iSCSI layer until the fence is cleared. 1477 4.2.2.3.4. Current List of Fenced Response Use Cases 1479 This Section lists the situations in which fenced response 1480 behavior is REQUIRED in iSCSI target implementations. However, 1481 this is not an exhaustive enumeration. It is expected that as SCSI 1482 protocol specifications evolve, the specifications will specify 1483 when response fencing is required on a case-by-case basis. 1485 Whenever the TaskReporting key (Section 13.23) is negotiated to 1486 ResponseFence or FastAbort for an iSCSI session, the target iSCSI 1487 layer MUST assume that the Response Fence is required for the 1488 following SCSI completion messages: 1490 1. The first completion message carrying the UA after the 1491 multi-task abort on issuing and third-party sessions. See 1492 Section 4.2.3.2 for related TMF discussion. 1494 2. The TMF Response carrying the multi-task TMF Response on 1495 the issuing session. 1497 3. The completion message indicating ACA establishment on the 1498 issuing session. 1500 4. The first completion message carrying the ACA ACTIVE status 1501 after ACA establishment on issuing and third-party 1502 sessions. 1504 5. The TMF Response carrying the Clear ACA response on the 1505 issuing session. 1507 6. The response to a PERSISTENT RESERVE OUT/PREEMPT AND ABORT 1508 command. 1510 Note: 1512 - Due to the absence of ACA-related fencing requirements in 1513 [RFC3720], initiator implementations SHOULD NOT use ACA on 1514 multi-connection iSCSI sessions with targets complying only 1515 with [RFC3720]. 1517 - Initiators that want to employ ACA on multi-connection iSCSI 1518 sessions SHOULD first assess response-fencing behavior via 1519 negotiating for ResponseFence or FastAbort values for the 1520 TaskReporting (Section 13.23) key. 1522 4.2.2.4. Data Sequencing 1524 Data and R2T PDUs transferred as part of some command execution 1525 MUST be sequenced. The DataSN field is used for data sequencing. 1526 For input (read) data PDUs, DataSN starts with 0 for the first 1527 data PDU of an input command and advances by 1 for each subsequent 1528 data PDU. For output data PDUs, DataSN starts with 0 for the first 1529 data PDU of a sequence (the initial unsolicited sequence or any 1530 data PDU sequence issued to satisfy an R2T) and advances by 1 for 1531 each subsequent data PDU. R2Ts are also sequenced per command. For 1532 example, the first R2T has an R2TSN of 0 and advances by 1 for 1533 each subsequent R2T. For bidirectional commands, the target uses 1534 the DataSN/R2TSN to sequence Data-In and R2T PDUs in one 1535 continuous sequence (undifferentiated). Unlike command and status, 1536 data PDUs and R2Ts are not acknowledged by a field in regular 1537 outgoing PDUs. Data-In PDUs can be acknowledged on demand by a 1538 special form of the SNACK PDU. Data and R2T PDUs are implicitly 1539 acknowledged by status for the command. The DataSN/R2TSN field 1540 enables the initiator to detect missing data or R2T PDUs. 1542 For any read or bidirectional command, a target MUST issue less 1543 than 2**32 combined R2T and Data-In PDUs. Any output data sequence 1544 MUST contain less than 2**32 Data-Out PDUs. 1546 4.2.3. iSCSI Task Management 1548 4.2.3.1. Task Management Overview 1550 iSCSI task management features allow an initiator to control the 1551 active iSCSI tasks on an operational iSCSI session that it has 1552 with an iSCSI target. Section 11.5 defines the task management 1553 function types that this specification defines - ABORT TASK, ABORT 1554 TASK SET, CLEAR ACA, CLEAR TASK SET, LOGICAL UNIT RESET, TARGET 1555 WARM RESET, TARGET COLD RESET, and TASK REASSIGN. 1557 Out of these function types, ABORT TASK and TASK REASSIGN 1558 functions manage a single active task, whereas ABORT TASK SET, 1559 CLEAR TASK SET, LOGICAL UNIT RESET, TARGET WARM RESET and TARGET 1560 COLD RESET functions can each potentially affect multiple active 1561 tasks. 1563 4.2.3.2. Notion of Affected Tasks 1565 This Section defines the notion of "affected tasks" in multi-task 1566 abort scenarios. Scope definitions in this Section apply to both 1567 the Standard Multi-task Abort semantics (Section 4.2.3.3) and the 1568 FastAbort Multi-task Abort semantics behavior (Section 4.2.3.4). 1570 ABORT TASK SET: All outstanding tasks for the I_T_L nexus 1571 identified by the LUN field in the ABORT TASK SET TMF Request PDU 1572 (Section 11.5). 1574 CLEAR TASK SET: All outstanding tasks in the task set for the LU 1575 identified by the LUN field in the CLEAR TASK SET TMF Request PDU. 1576 See [SPC3] for the definition of a "task set". 1578 LOGICAL UNIT RESET: All outstanding tasks from all initiators for 1579 the LU identified by the LUN field in the LOGICAL UNIT RESET 1580 Request PDU. 1582 TARGET WARM RESET/TARGET COLD RESET: All outstanding tasks from 1583 all initiators across all LUs to which the TMF-issuing session has 1584 access on the SCSI target device hosting the iSCSI session. 1586 Usage: An "ABORT TASK SET TMF Request PDU" in the preceding text 1587 is an iSCSI TMF Request PDU with the "Function" field set to 1588 "ABORT TASK SET" as defined in Section 11.5. Similar usage is 1589 employed for other scope descriptions. 1591 4.2.3.3. Standard Multi-task Abort Semantics 1593 All iSCSI implementations MUST support the protocol behavior 1594 defined in this Section as the default behavior. The execution of 1595 ABORT TASK SET, CLEAR TASK SET, LOGICAL UNIT RESET, TARGET WARM 1596 RESET, and TARGET COLD RESET TMF Requests consists of the 1597 following sequence of actions in the specified order on the 1598 specified party. 1600 The initiator iSCSI layer: 1601 a. MUST continue to respond to each TTT received for the 1602 affected tasks. 1603 b. SHOULD process any responses received for affected tasks in 1604 the normal fashion. This is acceptable because the 1605 responses are guaranteed to have been sent prior to the TMF 1606 response. 1607 c. SHOULD receive the TMF Response concluding all the tasks in 1608 the set of affected tasks unless the initiator has done 1609 something (e.g., LU reset, connection drop) that may 1610 prevent the TMF Response from being sent or received. The 1611 initiator MUST thus conclude all affected tasks as part of 1612 this step in either case, and MUST discard any TMF Response 1613 received after the affected tasks are concluded. 1615 The target iSCSI layer: 1616 a. MUST wait for responses on currently valid target-transfer 1617 tags of the affected tasks from the issuing initiator. MAY 1618 wait for responses on currently valid target-transfer tags 1619 of the affected tasks from third-party initiators. 1620 b. MUST wait (concurrent with the wait in Step a) for all 1621 commands of the affected tasks to be received based on the 1622 CmdSN ordering. SHOULD NOT wait for new commands on third- 1623 party affected sessions -- only the instantiated tasks have 1624 to be considered for the purpose of determining the 1625 affected tasks. In the case of target-scoped requests 1626 (i.e., TARGET WARM RESET and TARGET COLD RESET), all of the 1627 commands that are not yet received on the issuing session 1628 in the command stream however can be considered to have 1629 been received with no command waiting period -- i.e., the 1630 entire CmdSN space up to the CmdSN of the task management 1631 function can be "plugged". 1632 c. MUST propagate the TMF request to and receive the response 1633 from the target SCSI layer. 1635 d. MUST provide the Response Fence behavior for the TMF 1636 Response on the issuing session as specified in Section 1637 4.2.2.3.2. 1638 e. MUST provide the Response Fence behavior on the first post- 1639 TMF Response on third-party sessions as specified in 1640 Section 4.2.2.3.3. If some tasks originate from non-iSCSI 1641 I_T_L nexuses, then the means by which the target ensures 1642 that all affected tasks have returned their status to the 1643 initiator are defined by the specific non-iSCSI transport 1644 protocol(s). 1646 Technically, the TMF servicing is complete in Step d. Data 1647 transfers corresponding to terminated tasks may however still be 1648 in progress on third-party iSCSI sessions even at the end of Step 1649 e. The TMF Response MUST NOT be sent by the target iSCSI layer 1650 before the end of Step d, and MAY be sent at the end of Step d 1651 despite these outstanding data transfers until after Step e. 1653 4.2.3.4. FastAbort Multi-task Abort Semantics 1655 Protocol behavior defined in this Section SHOULD be implemented by 1656 all iSCSI implementations complying with this document. Protocol 1657 behavior defined in this Section MUST be exhibited by iSCSI 1658 implementations on an iSCSI session when they negotiate the 1659 TaskReporting (Section 13.23) key to "FastAbort" on that session. 1660 The execution of ABORT TASK SET, CLEAR TASK SET, LOGICAL UNIT 1661 RESET, TARGET WARM RESET, and TARGET COLD RESET TMF Requests 1662 consists of the following sequence of actions in the specified 1663 order on the specified party. 1665 The initiator iSCSI layer: 1666 a. MUST NOT send any more Data-Out PDUs for affected tasks on 1667 the issuing connection of the issuing iSCSI session once 1668 the TMF is sent to the target. 1669 b. SHOULD process any responses received for affected tasks in 1670 the normal fashion. This is acceptable because the 1671 responses are guaranteed to have been sent prior to the TMF 1672 response. 1673 c. MUST respond to each Async Message PDU with FAST_ABORT 1674 AsyncEvent as defined in Section 11.9. 1676 d. MUST treat the TMF response as terminating all affected 1677 tasks for which responses have not been received, and MUST 1678 discard any responses for affected tasks received after the 1679 TMF response is passed to the SCSI layer (although the 1680 semantics defined in this Section ensure that such an out- 1681 of-order scenario will never happen with a compliant target 1682 implementation). 1684 The target iSCSI layer: 1685 a. MUST wait for all commands of the affected tasks to be 1686 received based on the CmdSN ordering on the issuing 1687 session. SHOULD NOT wait for new commands on third-party 1688 affected sessions - only the instantiated tasks have to be 1689 considered for the purpose of determining the affected 1690 tasks. In the case of target-scoped requests (i.e., TARGET 1691 WARM RESET and TARGET COLD RESET), all the commands that 1692 are not yet received on the issuing session in the command 1693 stream can be considered to have been received with no 1694 command waiting period -- i.e., the entire CmdSN space up 1695 to the CmdSN of the task management function can be 1696 "plugged". 1697 b. MUST propagate the TMF request to and receive the response 1698 from the target SCSI layer. 1699 c. MUST leave all active "affected TTTs" (i.e., active TTTs 1700 associated with affected tasks) valid. 1701 d. MUST send an Asynchronous Message PDU with AsyncEvent=5 1702 (Section 11.9) on: 1703 i) each connection of each third-party session to 1704 which at least one affected task is allegiant if 1705 TaskReporting=FastAbort is operational on that third- 1706 party session, and, 1707 ii) each connection except the issuing connection of 1708 the issuing session that has at least one allegiant 1709 affected task. 1710 If there are multiple affected LUs (say, due to a target 1711 reset), then one Async Message PDU MUST be sent for each 1712 such LU on each connection that has at least one allegiant 1713 affected task. The LUN field in the Asynchronous Message PDU 1714 MUST be set to match the LUN for each such LU. 1716 e. MUST address the Response Fence flag on the TMF Response on 1717 the issuing session as defined in Section 4.2.2.3.3. 1718 f. MUST address the Response Fence flag on the first post-TMF 1719 Response on third-party sessions as defined in Section 1720 4.2.2.3.3. If some tasks originate from non-iSCSI I_T_L 1721 nexuses, then the means by which the target ensures that 1722 all affected tasks have returned their status to the 1723 initiator are defined by the specific non-iSCSI transport 1724 protocol(s). 1725 g. MUST free up the affected TTTs (and STags, if applicable) 1726 and the corresponding buffers, if any, once it receives 1727 each associated NOP-Out acknowledgement that the initiator 1728 generated in response to each Async Message. 1730 Technically, the TMF servicing is complete in Step e. Data 1731 transfers corresponding to terminated tasks may however still be 1732 in progress even at the end of Step f. A TMF Response MUST NOT be 1733 sent by the target iSCSI layer before the end of Step e, and MAY 1734 be sent at the end of Step e despite these outstanding Data 1735 transfers until Step g. Step g specifies an event to free up any 1736 such resources that may have been reserved to support outstanding 1737 data transfers. 1739 4.2.3.5. Affected Tasks Shared across Standard and FastAbort Sessions 1741 If an iSCSI target implementation is capable of supporting 1742 TaskReporting=FastAbort functionality (Section 13.23), it may end 1743 up in a situation where some sessions have TaskReporting=RFC3720 1744 operational (RFC 3720 sessions) while some other sessions have 1745 TaskReporting=FastAbort operational (FastAbort sessions) even 1746 while accessing a shared set of affected tasks (Section 4.2.3.2). 1747 If the issuing session is an RFC 3720 session, the iSCSI target 1748 implementation is FastAbort-capable, and the third-party affected 1749 session is a FastAbort session, the following behavior SHOULD be 1750 exhibited by the iSCSI target layer: 1751 a. Between Steps c and d of the target behavior in Section 1752 4.2.3.3, send an Asynchronous Message PDU with AsyncEvent=5 1753 (Section 11.9) on each connection of each third-party 1754 session to which at least one affected task is allegiant. 1755 If there are multiple affected LUs, then send one Async 1756 Message PDU for each such LU on each connection that has at 1757 least one allegiant affected task. When sent, the LUN field 1758 in the Asynchronous Message PDU MUST be set to match the 1759 LUN for each such LU. 1760 b. After Step e of the target behavior in Section 4.2.3.3, 1761 free up the affected TTTs (and STags, if applicable) and 1762 the corresponding buffers, if any, once each associated 1763 NOP-Out acknowledgement is received that the third-party 1764 initiator generated in response to each Async Message sent 1765 in Step a. 1767 If the issuing session is a FastAbort session, the iSCSI target 1768 implementation is FastAbort-capable, and the third-party affected 1769 session is an RFC 3720 session, the following behavior MUST be 1770 exhibited by the iSCSI target layer: Asynchronous Message PDUs 1771 MUST NOT be sent on the third-party session to prompt the 1772 FastAbort behavior. 1774 If the third-party affected session is a FastAbort session and the 1775 issuing session is a FastAbort session, the initiator in the 1776 third-party role MUST respond to each Async Message PDU with 1777 AsyncEvent=5 as defined in Section 11.9. Note that an initiator 1778 MAY thus receive these Async Messages on a third-party affected 1779 session even if the session is a single-connection session. 1781 4.2.3.6. Rationale behind the FastAbort Semantics 1783 There are fundamentally three basic objectives behind the 1784 semantics 1785 specified in Sections 4.2.3.3 and 4.2.3.4. 1786 1. Maintaining an ordered command flow I_T nexus abstraction 1787 to the target SCSI layer even with multi-connection 1788 sessions. 1789 - Target iSCSI processing of a TMF request must 1790 maintain the single flow illusion. Target behavior in 1791 Step b of Section 4.2.3.3 and Step a of Section 4.2.3.4 1792 correspond to this objective. 1793 2. Maintaining a single ordered response flow I_T nexus 1794 abstraction to the initiator SCSI layer even with multi- 1795 connection sessions when one response (i.e., TMF response) 1796 could imply the status of other unfinished tasks from the 1797 initiator's perspective. 1799 - The target must ensure that the initiator does not 1800 see "old" task responses (that were placed on the wire 1801 chronologically earlier than the TMF Response) after 1802 seeing the TMF response. The target behavior in Step d 1803 of Section 4.2.3.3 and Step e of Section 4.2.3.4 1804 correspond to this objective. 1805 - Whenever the result of a TMF action is visible across 1806 multiple I_T_L nexuses, [SAM2] requires the SCSI device 1807 server to trigger a UA on each of the other I_T_L 1808 nexuses. Once an initiator is notified of such an UA, 1809 the application client on the receiving initiator is 1810 required to clear its task state (clause 5.5 in [SAM2]) 1811 for the affected tasks. It would thus be inappropriate 1812 to deliver a SCSI Response for a task after the task 1813 state is cleared on the initiator, i.e., after the UA 1814 is notified. The UA notification contained in the first 1815 SCSI Response PDU on each affected Third-party I_T_L 1816 nexus after the TMF action thus MUST NOT pass the 1817 affected task responses on any of the iSCSI sessions 1818 accessing the LU. The target behavior in Step e of 1819 Section 4.2.3.3 and Step f of Section 4.2.3.4 1820 correspond to this objective. 1821 3. Draining all active TTTs corresponding to affected tasks in 1822 a deterministic fashion. 1823 - Data-Out PDUs with stale TTTs arriving after the 1824 tasks are terminated can create a buffer management 1825 problem even for traditional iSCSI implementations, and 1826 is fatal for the connection for iSCSI/iSER 1827 implementations. Either the termination of affected 1828 tasks should be postponed until the TTTs are retired 1829 (as in Step a of Section 4.2.3.3), or the TTTs and the 1830 buffers should stay allocated beyond task termination 1831 to be deterministically freed up later (as in Steps c 1832 and g of Section 4.2.3.4). 1834 The only other notable optimization is the plugging. If all tasks 1835 on an I_T nexus will be aborted anyway (as with a target reset), 1836 there is no need to wait to receive all commands to plug the CmdSN 1837 holes. The target iSCSI layer can simply plug all missing CmdSN 1838 slots and move on with TMF processing. The first objective 1839 (maintaining a single ordered command flow) is still met with this 1840 optimization because the target SCSI layer only sees ordered 1841 commands. 1843 4.2.4. iSCSI Login 1845 The purpose of the iSCSI login is to enable a TCP connection for 1846 iSCSI use, authentication of the parties, negotiation of the 1847 session's parameters and marking of the connection as belonging to 1848 an iSCSI session. 1850 A session is used to identify to a target all the connections with 1851 a given initiator that belong to the same I_T nexus. (For more 1852 details on how a session relates to an I_T nexus, see Section 1853 4.4.2). 1855 The targets listen on a well-known TCP port or other TCP port for 1856 incoming connections. The initiator begins the login process by 1857 connecting to one of these TCP ports. 1859 As part of the login process, the initiator and target SHOULD 1860 authenticate each other and MAY set a security association 1861 protocol for the session. This can occur in many different ways 1862 and is subject to negotiation. 1864 To protect the TCP connection, an IPsec security association MAY 1865 be established before the Login request. For information on using 1866 IPsec security for iSCSI see Section 9 and [RFC3723]. 1868 The iSCSI Login Phase is carried through Login requests and 1869 responses. Once suitable authentication has occurred and 1870 operational parameters have been set, the session transitions to 1871 Full Feature Phase and the initiator may start to send SCSI 1872 commands. The security policy for whether, and by what means, a 1873 target chooses to authorize an initiator is beyond the scope of 1874 this document. For a more detailed description of the Login Phase, 1875 see Section 6. 1877 The login PDU includes the ISID part of the session ID (SSID). The 1878 target portal group that services the login is implied by the 1879 selection of the connection endpoint. For a new session, the TSIH 1880 is zero. As part of the response, the target generates a TSIH. 1882 During session establishment, the target identifies the SCSI 1883 initiator port (the "I" in the "I_T nexus") through the value pair 1884 (InitiatorName, ISID). We describe InitiatorName later in this 1885 Section. Any persistent state (e.g., persistent reservations) on 1886 the target that is associated with a SCSI initiator port is 1887 identified based on this value pair. Any state associated with the 1888 SCSI target port (the "T" in the "I_T nexus") is identified 1889 externally by the TargetName and portal group tag (see Section 1890 4.4.1). ISID is subject to reuse restrictions because it is used 1891 to identify a persistent state (see Section 4.4.3). 1893 Before the Full Feature Phase is established, only Login Request 1894 and Login Response PDUs are allowed. Login requests and responses 1895 MUST be used exclusively during Login. On any connection, the 1896 login phase MUST immediately follow TCP connection establishment 1897 and a subsequent Login Phase MUST NOT occur before tearing down a 1898 connection. 1900 A target receiving any PDU except a Login request before the Login 1901 phase is started MUST immediately terminate the connection on 1902 which the PDU was received. Once the Login phase has started, if 1903 the target receives any PDU except a Login request, it MUST send a 1904 Login reject (with Status "invalid during login") and then 1905 disconnect. If the initiator receives any PDU except a Login 1906 response, it MUST immediately terminate the connection. 1908 4.2.5. iSCSI Full Feature Phase 1910 Once the initiator is authorized to do so, the iSCSI session is in 1911 the iSCSI Full Feature Phase. A session is in Full Feature Phase 1912 after successfully finishing the Login Phase on the first 1913 (leading) connection of a session. A connection is in Full Feature 1914 Phase if the session is in Full Feature Phase and the connection 1915 login has completed successfully. An iSCSI connection is not in 1916 Full Feature Phase 1918 a) when it does not have an established transport 1919 connection, 1920 OR 1922 b) when it has a valid transport connection, but a 1923 successful login was not performed or the connection is 1924 currently logged out. 1926 In a normal Full Feature Phase, the initiator may send SCSI 1927 commands and data to the various LUs on the target by 1928 encapsulating them in iSCSI PDUs that go over the established 1929 iSCSI session. 1931 4.2.5.1. Command Connection Allegiance 1933 For any iSCSI request issued over a TCP connection, the 1934 corresponding response and/or other related PDU(s) MUST be sent 1935 over the same connection. We call this "connection allegiance". If 1936 the original connection fails before the command is completed, the 1937 connection allegiance of the command may be explicitly reassigned 1938 to a different transport connection as described in detail in 1939 Section 7.2. 1941 Thus, if an initiator issues a READ command, the target MUST send 1942 the requested data, if any, followed by the status to the 1943 initiator over the same TCP connection that was used to deliver 1944 the SCSI command. If an initiator issues a WRITE command, the 1945 initiator MUST send the data, if any, for that command over the 1946 same TCP connection that was used to deliver the SCSI command. The 1947 target MUST return Ready To Transfer (R2T), if any, and the status 1948 over the same TCP connection that was used to deliver the SCSI 1949 command. Retransmission requests (SNACK PDUs) and the data and 1950 status that they generate MUST also use the same connection. 1952 However, consecutive commands that are part of a SCSI linked 1953 command-chain task (see [SAM2]) MAY use different connections. 1954 Connection allegiance is strictly per-command and not per-task. 1955 During the iSCSI Full Feature Phase, the initiator and target MAY 1956 interleave unrelated SCSI commands, their SCSI Data, and responses 1957 over the session. 1959 4.2.5.2. Data Transfer Overview 1961 Outgoing SCSI data (initiator to target user data or command 1962 parameters) is sent as either solicited data or unsolicited data. 1963 Solicited data are sent in response to R2T PDUs. Unsolicited data 1964 can be sent as part of an iSCSI command PDU ("immediate data") or 1965 in separate iSCSI data PDUs. 1967 Immediate data are assumed to originate at offset 0 in the 1968 initiator SCSI write-buffer (outgoing data buffer). All other Data 1969 PDUs have the buffer offset set explicitly in the PDU header. 1971 An initiator may send unsolicited data up to FirstBurstLength 1972 (see Section 13.14) as immediate (up to the negotiated maximum PDU 1973 length), in a separate PDU sequence or both. All subsequent data 1974 MUST be solicited. The maximum length of an individual data PDU or 1975 the immediate-part of the first unsolicited burst MAY be 1976 negotiated at login. 1978 The maximum amount of unsolicited data that can be sent with a 1979 command is negotiated at login through the FirstBurstLength (see 1980 Section 13.14) key. A target MAY separately enable immediate data 1981 (through the ImmediateData key) without enabling the more general 1982 (separate data PDUs) form of unsolicited data (through the 1983 InitialR2T key). 1985 Unsolicited data on write are meant to reduce the effect of 1986 latency on throughput (no R2T is needed to start sending data). In 1987 addition, immediate data is meant to reduce the protocol overhead 1988 (both bandwidth and execution time). 1990 An iSCSI initiator MAY choose not to send unsolicited data, only 1991 immediate data or FirstBurstLength bytes of unsolicited data with 1992 a command. If any non-immediate unsolicited data is sent, the 1993 total unsolicited data MUST be either FirstBurstLength, or all of 1994 the data if the total amount is less than the FirstBurstLength. 1996 It is considered an error for an initiator to send unsolicited 1997 data PDUs to a target that operates in R2T mode (only solicited 1998 data are allowed). It is also an error for an initiator to send 1999 more unsolicited data, whether immediate or as separate PDUs, than 2000 FirstBurstLength. 2002 An initiator MUST honor an R2T data request for a valid 2003 outstanding command (i.e., carrying a valid Initiator Task Tag) 2004 and deliver all the requested data provided the command is 2005 supposed to deliver outgoing data and the R2T specifies data 2006 within the command bounds. The initiator action is unspecified for 2007 receiving an R2T request that specifies data, all or part, outside 2008 of the bounds of the command. 2010 A target SHOULD NOT silently discard data and then request 2011 retransmission through R2T. Initiators SHOULD NOT keep track of 2012 the data transferred to or from the target (scoreboarding). SCSI 2013 targets perform residual count calculation to check how much data 2014 was actually transferred to or from the device by a command. This 2015 may differ from the amount the initiator sent and/or received for 2016 reasons such as retransmissions and errors. Read or bidirectional 2017 commands implicitly solicit the transmission of the entire amount 2018 of data covered by the command. SCSI data packets are matched to 2019 their corresponding SCSI commands by using tags specified in the 2020 protocol. 2022 In addition, iSCSI initiators and targets MUST enforce some 2023 ordering rules. When unsolicited data is used, the order of the 2024 unsolicited data on each connection MUST match the order in which 2025 the commands on that connection are sent. Command and unsolicited 2026 data PDUs may be interleaved on a single connection as long as the 2027 ordering requirements of each are maintained (e.g., command N+1 2028 MAY be sent before the unsolicited Data-Out PDUs for command N, 2029 but the unsolicited Data-Out PDUs for command N MUST precede the 2030 unsolicited Data-Out PDUs of command N+1). A target that receives 2031 data out of order MAY terminate the session. 2033 4.2.5.3. Tags and Integrity Checks 2035 Initiator tags for pending commands are unique initiator-wide for 2036 a session. Target tags are not strictly specified by the protocol. 2037 It is assumed that target tags are used by the target to tag 2038 (alone or in combination with the LUN) the solicited data. Target 2039 tags are generated by the target and "echoed" by the initiator. 2040 These mechanisms are designed to accomplish efficient data 2041 delivery along with a large degree of control over the data flow. 2043 As the Initiator Task Tag is used to identify a task during its 2044 execution the iSCSI initiator and target MUST verify that all 2045 other fields used in task related PDUs have values that are 2046 consistent with the values used at the task instantiation based on 2047 Initiator Task Tag (e.g., the LUN used in an R2T PDU MUST be the 2048 same as the one used in the SCSI command PDU used to instantiate 2049 the task). Using inconsistent field values is considered a 2050 protocol error. 2052 4.2.5.4. Task Management 2054 SCSI task management assumes that individual tasks and task groups 2055 can be aborted solely based on the task tags (for individual 2056 tasks) or the timing of the task management command (for task 2057 groups) and that the task management action is executed 2058 synchronously - i.e, no message involving an aborted task will be 2059 seen by the SCSI initiator after receiving the task management 2060 response. In iSCSI initiators and targets interact asynchronously 2061 over several connections. iSCSI specifies the protocol mechanism 2062 and implementation requirements needed to present a synchronous 2063 view while using an asynchronous infrastructure. 2065 4.2.6. iSCSI Connection Termination 2067 An iSCSI connection may be terminated by use of a transport 2068 connection shutdown or a transport reset. Transport reset is 2069 assumed to be an exceptional event. 2071 Graceful TCP connection shutdowns are done by sending TCP FINs. A 2072 graceful transport connection shutdown SHOULD only be initiated by 2073 either party when the connection is not in iSCSI Full Feature 2074 Phase. A target MAY terminate a Full Feature Phase connection on 2075 internal exception events, but it SHOULD announce the fact through 2076 an Asynchronous Message PDU. Connection termination with 2077 outstanding commands may require recovery actions. 2079 If a connection is terminated while in Full Feature Phase, 2080 connection cleanup (see Section 7) is required prior to recovery. 2081 By doing connection cleanup before starting recovery, the 2082 initiator and target will avoid receiving stale PDUs after 2083 recovery. 2085 4.2.7. iSCSI Names 2087 Both targets and initiators require names for the purpose of 2088 identification. In addition, names enable iSCSI storage resources 2090 to be managed regardless of location (address). An iSCSI node name 2091 is also the SCSI device name contained in the iSCSI Node. The 2092 iSCSI name of a SCSI device is the principal object used in 2093 authentication of targets to initiators and initiators to targets. 2094 This name is also used to identify and manage iSCSI storage 2095 resources. 2097 iSCSI names must be unique within the operation domain of the end 2098 user. However, because the operation domain of an IP network is 2099 potentially worldwide, the iSCSI name formats are architected to 2100 be worldwide unique. To assist naming authorities in the 2101 construction of worldwide unique names, iSCSI provides three name 2102 formats for different types of naming authorities. 2104 iSCSI names are associated with iSCSI nodes, and not iSCSI network 2105 adapter cards, to ensure that the replacement of network adapter 2106 cards does not require reconfiguration of all SCSI and iSCSI 2107 resource allocation information. 2109 Some SCSI commands require that protocol-specific identifiers be 2110 communicated within SCSI CDBs. See SCSI for the definition of the 2111 SCSI port name/identifier for iSCSI ports. 2113 An initiator may discover the iSCSI Target Names to which it has 2114 access, along with their addresses, using the SendTargets text 2115 request, or other techniques discussed in [RFC3721]. 2117 iSCSI equipment that needs discovery functions beyond SendTargets 2118 SHOULD implement iSNS (see [RFC4171]) for extended discovery 2119 management capabilities and interoperability. Although [RFC3721] 2120 implies an SLP implementation requirement, SLP has not been widely 2121 implemented or deployed for use with iSCSI in practice. iSCSI 2122 implementations therefore SHOULD NOT rely on SLP-based discovery 2123 interoperability. 2125 4.2.7.1. iSCSI Name Properties 2127 Each iSCSI node, whether it is an initiator or target or both, 2128 MUST have an iSCSI name. Whenever an iSCSI Node contains an iSCSI 2129 Initiator Node and an iSCSI Target Node, the iSCSI Initiator Name 2130 MUST be the same as the iSCSI Target Name for the contained Nodes 2131 such that there is only one iSCSI Node Name for the iSCSI Node 2132 overall. Note the related requirements in Section 9.2.1 on how to 2133 map CHAP names to iSCSI Names in such a scenario. 2135 Initiators and targets MUST support the receipt of iSCSI names of 2136 up to the maximum length of 223 bytes. 2138 The initiator MUST present both its iSCSI Initiator Name and the 2139 iSCSI Target Name to which it wishes to connect in the first login 2140 request of a new session or connection. The only exception is if a 2141 discovery session (see Section 4.3) is to be established. In this 2142 case, the iSCSI Initiator Name is still required, but the iSCSI 2143 Target Name MAY be omitted. 2145 iSCSI names have the following properties: 2147 - iSCSI names are globally unique. No two initiators or 2148 targets can have the same name. 2150 - iSCSI names are permanent. An iSCSI initiator node or target 2151 node has the same name for its lifetime. 2153 - iSCSI names do not imply a location or address. An iSCSI 2154 initiator or target can move, or have multiple addresses. A 2155 change of address does not imply a change of name. 2157 - iSCSI names do not rely on a central name broker; the naming 2158 authority is distributed. 2160 - iSCSI names support integration with existing unique naming 2161 schemes. 2163 - iSCSI names rely on existing naming authorities. iSCSI does 2164 not create any new naming authority. 2166 The encoding of an iSCSI name has the following properties: 2168 - iSCSI names have the same encoding method regardless of the 2169 underlying protocols. 2171 - iSCSI names are relatively simple to compare. The algorithm 2172 for comparing two iSCSI names for equivalence does not rely 2173 on an external server. 2175 - iSCSI names are composed only of displayable characters. 2176 iSCSI names allow the use of international character sets 2177 but are not case sensitive. No whitespace characters are 2178 used in iSCSI names. 2180 - iSCSI names may be transported using both binary and ASCII- 2181 based protocols. 2183 An iSCSI name really names a logical software entity, and is not 2184 tied to a port or other hardware that can be changed. For 2185 instance, an initiator name should name the iSCSI initiator node, 2186 not a particular NIC or HBA. When multiple NICs are used, they 2187 should generally all present the same iSCSI initiator name to the 2188 targets, because they are simply paths to the same SCSI layer. In 2189 most operating systems, the named entity is the operating system 2190 image. 2192 Similarly, a target name should not be tied to hardware interfaces 2193 that can be changed. A target name should identify the logical 2194 target and must be the same for the target regardless of the 2195 physical portion being addressed. This assists iSCSI initiators in 2196 determining that the two targets it has discovered are really two 2197 paths to the same target. 2199 The iSCSI name is designed to fulfill the functional requirements 2200 for Uniform Resource Names (URN) [RFC1737]. For example, it is 2201 required that the name have a global scope, be independent of 2202 address or location, and be persistent and globally unique. Names 2203 must be extensible and scalable with the use of naming 2204 authorities. The name encoding should be both human and machine 2205 readable. See [RFC1737] for further requirements. 2207 4.2.7.2. iSCSI Name Encoding 2209 An iSCSI name MUST be a UTF-8 (see [RFC3629]) encoding of a string 2210 of Unicode characters with the following properties: 2212 - It is in Normalization Form C (see "Unicode Normalization 2213 Forms" [UNICODE]). 2215 - It only contains characters allowed by the output of the 2216 iSCSI stringprep template (described in [RFC3722]). 2218 - The following characters are used for formatting iSCSI 2219 names: 2221 - dash ('-'=U+002d) 2222 - dot ('.'=U+002e) 2223 - colon (':'=U+003a) 2225 - The UTF-8 encoding of the name is not larger than 223 bytes. 2227 The stringprep process is described in [RFC3454]; iSCSI's use of 2228 the stringprep process is described in [RFC3722]. Stringprep is a 2229 method designed by the Internationalized Domain Name (IDN) working 2230 group to translate human-typed strings into a format that can be 2231 compared as opaque strings. Strings MUST NOT include punctuation, 2232 spacing, diacritical marks, or other characters that could get in 2233 the way of readability. The stringprep process also converts 2234 strings into equivalent strings of lower-case characters. 2236 The stringprep process does not need to be implemented if the 2237 names are only generated using numeric and lower-case (any 2238 character set) alphabetic characters. 2240 Once iSCSI names encoded in UTF-8 are "normalized" they may be 2241 safely compared byte-for-byte. 2243 4.2.7.3. iSCSI Name Structure 2245 An iSCSI name consists of two parts--a type designator followed by 2246 a unique name string. 2248 iSCSI uses three existing naming authorities in constructing 2249 globally unique iSCSI names. Type designator in an iSCSI name 2250 indicates the naming authority on which the name is based. The 2251 three iSCSI name formats are the following: 2253 a) iSCSI-Qualified Name: it is based on domain names to 2254 identify a naming authority, 2255 b) NAA format Name: it is based on a naming format defined 2256 by [FC-FS3] for constructing globally unique identifiers, 2257 referred to as the Network Address Authority (NAA), and, 2258 c) EUI format Name: it is based on EUI names where the IEEE 2259 Registration Authority assists in the formation of 2260 worldwide unique names (EUI-64 format). 2262 The corresponding type designator strings currently defined are: 2264 a) iqn. - iSCSI Qualified name 2266 b) naa. - Remainder of the string is an INCITS T11-defined 2267 Network Address Authority identifier, in ASCII-encoded 2268 hexadecimal. 2270 c) eui. - Remainder of the string is an IEEE EUI-64 2271 identifier, in ASCII-encoded hexadecimal. 2273 These three naming authority designators were considered 2274 sufficient at the time of writing this document. The creation of 2275 additional naming type designators for iSCSI may be considered by 2276 the IETF and detailed in separate RFCs. 2278 The following table summarizes the current SCSI transport 2279 protocols and their naming formats. 2281 SCSI Transport Protocol Naming Format 2282 +----------------------------+-------+-----+----+ 2283 | | EUI-64| NAA |IQN | 2284 |----------------------------|-------|-----|----| 2285 | iSCSI (Internet SCSI) | X | X | X | 2286 |----------------------------|-------|-----|----| 2287 | FCP (Fibre Channel) | | X | | 2288 |----------------------------|-------|-----|----| 2289 | SAS (Serial Attached SCSI) | | X | | 2290 +----------------------------+-------+-----+----+ 2292 4.2.7.4. Type "iqn." (iSCSI Qualified Name) 2294 This iSCSI name type can be used by any organization that owns a 2295 domain name. This naming format is useful when an end user or 2296 service provider wishes to assign iSCSI names for targets and/or 2297 initiators. 2299 To generate names of this type, the person or organization 2300 generating the name must own a registered domain name. This domain 2301 name does not have to be active, and does not have to resolve to 2302 an address; it just needs to be reserved to prevent others from 2303 generating iSCSI names using the same domain name. 2305 Since a domain name can expire, be acquired by another entity, or 2306 may be used to generate iSCSI names by both owners, the domain 2307 name must be additionally qualified by a date during which the 2308 naming authority owned the domain name. A date code is provided as 2309 part of the "iqn." format for this reason. 2311 The iSCSI qualified name string consists of: 2313 - The string "iqn.", used to distinguish these names from 2314 "eui." formatted names. 2316 - A date code, in yyyy-mm format. This date MUST be a date 2317 during which the naming authority owned the domain name used 2318 in this format, and SHOULD be the first month in which the 2319 domain name was owned by this naming authority at 00:01 GMT 2320 of the first day of the month. This date code uses the 2321 Gregorian calendar. All four digits in the year must be 2322 present. Both digits of the month must be present, with 2323 January == "01" and December == "12". The dash must be 2324 included. 2326 - A dot "." 2328 - The reversed domain name of the naming authority (person or 2329 organization) creating this iSCSI name. 2331 - An optional, colon (:) prefixed, string within the character 2332 set and length boundaries that the owner of the domain name 2333 deems appropriate. This may contain product types, serial 2334 numbers, host identifiers, or software keys (e.g, it may 2335 include colons to separate organization boundaries). With 2336 the exception of the colon prefix, the owner of the domain 2337 name can assign everything after the reversed domain name as 2338 desired. It is the responsibility of the entity that is the 2339 naming authority to ensure that the iSCSI names it assigns 2340 are worldwide unique. For example, "Example Storage Arrays, 2341 Inc.", might own the domain name "example.com". 2343 The following are examples of iSCSI qualified names that might be 2344 generated by "EXAMPLE Storage Arrays, Inc." 2346 Naming String defined by 2347 Type Date Auth "example.com" naming authority 2348 +--++-----+ +---------+ +--------------------------------+ 2349 | || | | | | | 2351 iqn.2001-04.com.example:storage:diskarrays-sn-a8675309 2352 iqn.2001-04.com.example 2353 iqn.2001-04.com.example:storage.tape1.sys1.xyz 2354 iqn.2001-04.com.example:storage.disk2.sys1.xyz 2356 4.2.7.5. Type "eui." (IEEE EUI-64 format) 2358 The IEEE Registration Authority provides a service for assigning 2359 globally unique identifiers [EUI]. The EUI-64 format is used to 2360 build a global identifier in other network protocols. For example, 2361 Fibre Channel defines a method of encoding it into a 2362 WorldWideName. For more information on registering for EUI 2363 identifiers, see [OUI]. 2365 The format is "eui." followed by an EUI-64 identifier (16 ASCII- 2366 encoded hexadecimal digits). 2368 Example iSCSI name: 2370 Type EUI-64 identifier (ASCII-encoded hexadecimal) 2371 +--++--------------+ 2373 | || | 2375 eui.02004567A425678D 2377 The IEEE EUI-64 iSCSI name format might be used when a 2378 manufacturer is already registered with the IEEE Registration 2379 Authority and uses EUI-64 formatted worldwide unique names for its 2380 products. 2382 More examples of name construction are discussed in [RFC3721]. 2384 4.2.7.6. Type "naa." - Network Address Authority 2386 The INCITS T11 Framing and Signaling Specification [FC-FS3] 2387 defines a format called the Network Address Authority (NAA) format 2388 for constructing worldwide unique identifiers that use various 2389 identifier registration authorities. This identifier format is 2390 used by the Fibre Channel and SAS SCSI transport protocols. As FC 2391 and SAS constitute a large fraction of networked SCSI ports, the 2392 NAA format is a widely used format for SCSI transports. The 2393 objective behind iSCSI supporting a direct representation of an 2394 NAA-format name is to facilitate construction of a target device 2395 name that translates easily across multiple namespaces for a SCSI 2396 storage device containing ports served by different transports. 2397 More specifically, this format allows implementations wherein one 2398 NAA identifier can be assigned as the basis for the SCSI device 2399 name for a SCSI target with both SAS ports and iSCSI ports. 2401 The iSCSI NAA naming format is "naa.", followed by an NAA 2402 identifier represented in ASCII-encoded hexadecimal digits. 2404 An example of an iSCSI name with a 64-bit NAA value follows: 2406 Type NAA identifier (ASCII-encoded hexadecimal) 2407 +--++--------------+ 2408 | || | 2409 naa.52004567BA64678D 2411 An example of an iSCSI name with a 128-bit NAA value follows: 2413 Type NAA identifier (ASCII-encoded hexadecimal) 2414 +--++------------------------------+ 2415 | || | 2416 naa.62004567BA64678D0123456789ABCDEF 2418 The iSCSI NAA naming format might be used in an implementation 2419 when the infrastructure for generating NAA worldwide unique names 2420 is already in place because the device contains both SAS and iSCSI 2421 SCSI ports. 2423 The NAA identifier formatted in an ASCII-hexadecimal 2424 representation has a maximum size of 32 characters (128 bit NAA 2425 format). As a result, there is no issue with this naming format 2426 exceeding the maximum size for iSCSI node names. 2428 4.2.8. Persistent State 2430 iSCSI does not require any persistent state maintenance across 2431 sessions. However, in some cases, SCSI requires persistent 2432 identification of the SCSI initiator port name (See Section 4.4.2 2433 and Section 4.4.3). 2435 iSCSI sessions do not persist through power cycles and boot 2436 operations. 2438 All iSCSI session and connection parameters are re-initialized on 2439 session and connection creation. 2441 Commands persist beyond connection termination if the session 2442 persists and command recovery within the session is supported. 2443 However, when a connection is dropped, command execution, as 2444 perceived by iSCSI (i.e., involving iSCSI protocol exchanges for 2445 the affected task), is suspended until a new allegiance is 2446 established by the 'task reassign' task management function. (See 2447 Section 11.5.) 2449 4.2.9. Message Synchronization and Steering 2451 iSCSI presents a mapping of the SCSI protocol onto TCP. This 2452 encapsulation is accomplished by sending iSCSI PDUs of varying 2453 lengths. Unfortunately, TCP does not have a built-in mechanism for 2454 signaling message boundaries at the TCP layer. iSCSI overcomes 2455 this obstacle by placing the message length in the iSCSI message 2456 header. This serves to delineate the end of the current message as 2457 well as the beginning of the next message. 2459 In situations where IP packets are delivered in order from the 2460 network, iSCSI message framing is not an issue and messages are 2461 processed one after the other. In the presence of IP packet 2462 reordering (i.e., frames being dropped), legacy TCP 2463 implementations store the "out of order" TCP segments in temporary 2464 buffers until the missing TCP segments arrive, upon which the data 2465 must be copied to the application buffers. In iSCSI, it is 2466 desirable to steer the SCSI data within these out of order TCP 2467 segments into the pre-allocated SCSI buffers rather than store 2468 them in temporary buffers. This decreases the need for dedicated 2469 reassembly buffers as well as the latency and bandwidth related to 2470 extra copies. 2472 Relying solely on the "message length" information from the iSCSI 2473 message header may make it impossible to find iSCSI message 2474 boundaries in subsequent TCP segments due to the loss of a TCP 2475 segment that contains the iSCSI message length. The missing TCP 2476 segment(s) must be received before any of the following segments 2477 can be steered to the correct SCSI buffers (due to the inability 2478 to determine the iSCSI message boundaries). Since these segments 2479 cannot be steered to the correct location, they must be saved in 2480 temporary buffers that must then be copied to the SCSI buffers. 2482 Different schemes can be used to recover synchronization. The 2483 details of any such schemes are beyond this protocol 2484 specification, but it suffices to note that [RFC4297] provides an 2485 overview of the direct data placement problem on IP networks, and 2486 [RFC5046] specifies a protocol extension for iSCSI that 2487 facilitates this direct data placement objective. 2489 Under normal circumstances (no PDU loss or data reception out of 2490 order), iSCSI data steering can be accomplished by using the 2491 identifying tag and the data offset fields in the iSCSI header in 2492 addition to the TCP sequence number from the TCP header. The 2493 identifying tag helps associate the PDU with a SCSI buffer address 2494 while the data offset and TCP sequence number are used to 2495 determine the offset within the buffer. 2497 4.2.9.1. Sync/Steering and iSCSI PDU Length 2499 When a large iSCSI message is sent, the TCP segment(s) that 2500 contain the iSCSI header may be lost. The remaining TCP segment(s) 2501 up to the next iSCSI message must be buffered (in temporary 2502 buffers) because the iSCSI header that indicates to which SCSI 2503 buffers the data are to be steered was lost. To minimize the 2504 amount of buffering, it is recommended that the iSCSI PDU length 2505 be restricted to a small value (perhaps a few TCP segments in 2506 length). During login, each end of the iSCSI session specifies the 2507 maximum iSCSI PDU length it will accept. 2509 4.3. iSCSI Session Types 2511 iSCSI defines two types of sessions: 2513 a) Normal operational session - an unrestricted session. 2515 b) Discovery-session - a session only opened for target 2516 discovery. The target MUST ONLY accept text requests with 2517 the SendTargets key and a logout request with reason 2518 "close the session". All other requests MUST be rejected. 2520 The session type is defined during login with key=value parameter 2521 in the login command. 2523 4.4. SCSI to iSCSI Concepts Mapping Model 2525 The following diagram shows an example of how multiple iSCSI Nodes 2526 (targets in this case) can coexist within the same Network Entity 2527 and can share Network Portals (IP addresses and TCP ports). Other 2528 more complex configurations are also possible. For detailed 2529 descriptions of the components of these diagrams, see Section 2530 4.4.1. 2532 +-----------------------------------+ 2533 | Network Entity (iSCSI Client) | 2534 | | 2535 | +-------------+ | 2536 | | iSCSI Node | | 2537 | | (Initiator) | | 2538 | +-------------+ | 2539 | | | | 2540 | +--------------+ +--------------+ | 2541 | |Network Portal| |Network Portal| | 2542 | | 192.0.2.4 | | 192.0.2.5 | | 2543 +-+--------------+-+--------------+-+ 2544 | | 2545 | IP Networks | 2546 | | 2547 +-+--------------+-+--------------+-+ 2548 | |Network Portal| |Network Portal| | 2549 | |198.51.100.21 | |198.51.100.3 | | 2550 | | TCP Port 3260| | TCP Port 3260| | 2551 | +--------------+ +--------------+ | 2552 | | | | 2553 | ----------------- | 2554 | | | | 2555 | +-------------+ +--------------+ | 2556 | | iSCSI Node | | iSCSI Node | | 2557 | | (Target) | | (Target) | | 2558 | +-------------+ +--------------+ | 2559 | | 2560 | Network Entity (iSCSI Server) | 2561 +-----------------------------------+ 2563 4.4.1. iSCSI Architecture Model 2565 This Section describes the part of the iSCSI architecture model 2566 that has the most bearing on the relationship between iSCSI and 2567 the SCSI Architecture Model. 2569 - Network Entity - represents a device or gateway that is 2570 accessible from the IP network. A Network Entity must have 2571 one or more Network Portals (see a following item), each of 2572 which can be used by some iSCSI Nodes (see the following 2573 item) contained in that Network Entity to gain access to the 2575 IP network. 2577 - iSCSI Node - represents a single iSCSI initiator or iSCSI 2578 target or an instance of each. There are one or more iSCSI 2579 Nodes within a Network Entity. The iSCSI Node is accessible 2580 via one or more Network Portals (see item d). An iSCSI Node 2581 is identified by its iSCSI Name (see Section 4.2.7 and 2582 Section 13). The separation of the iSCSI Name from the 2583 addresses used by and for the iSCSI node allows multiple 2584 iSCSI nodes to use the same addresses, and the same iSCSI 2585 node to use multiple addresses. 2587 - An alias string may also be associated with an iSCSI Node. 2588 The alias allows an organization to associate a user 2589 friendly string with the iSCSI Name. However, the alias 2590 string is not a substitute for the iSCSI Name. 2592 - Network Portal - a component of a Network Entity that has a 2593 TCP/IP network address and that may be used by an iSCSI Node 2594 within that Network Entity for the connection(s) within one 2595 of its iSCSI sessions. In an initiator, it is identified by 2596 its IP address. In a target, it is identified by its IP 2597 address and its listening TCP port. 2599 - Portal Groups - iSCSI supports multiple connections within 2600 the same session; some implementations will have the ability 2601 to combine connections in a session across multiple Network 2602 Portals. A Portal Group defines a set of Network Portals 2603 within an iSCSI Node that collectively supports the 2604 capability of coordinating a session with connections that 2605 span these portals. Not all Network Portals within a Portal 2606 Group need to participate in every session connected through 2607 that Portal Group. One or more Portal Groups may provide 2608 access to an iSCSI Node. Each Network Portal, as utilized by 2609 a given iSCSI Node, belongs to exactly one portal group 2610 within that node. Portal Groups are identified within an 2611 iSCSI Node by a portal group tag, a simple unsigned-integer 2612 between 0 and 65535 (see Section 13.3). All Network Portals 2614 with the same portal group tag in the context of a given 2615 iSCSI Node are in the same Portal Group. 2617 Both iSCSI Initiators and iSCSI Targets have portal groups, 2618 though only the iSCSI Target Portal Groups are used directly 2619 in the iSCSI protocol (e.g., in SendTargets). For references 2620 to the Initiator Portal Groups, see Section 10.1.1. 2622 - Portals within a Portal Group should support similar session 2623 parameters, because they may participate in a common 2624 session. 2626 The following diagram shows an example of one such configuration 2627 on a target and how a session that shares Network Portals within a 2628 Portal Group may be established. 2630 ----------------------------IP Network--------------------- 2631 | | | 2632 +----|---------------|-----+ +----|---------+ 2633 | +---------+ +---------+ | | +---------+ | 2634 | | Network | | Network | | | | Network | | 2635 | | Portal | | Portal | | | | Portal | | 2636 | +--|------+ +---------+ | | +---------+ | 2637 | | | | | | | 2638 | | Portal | | | | Portal | 2639 | | Group 1 | | | | Group 2 | 2640 +--------------------------+ +--------------+ 2641 | | | 2642 +--------|---------------|--------------------|------------------+ 2643 | | | | | 2644 | +----------------------------+ +----------------------------+| 2645 | | iSCSI Session (Target side)| | iSCSI Session (Target side)|| 2646 | | | | || 2647 | | (TSIH = 56) | | (TSIH = 48) || 2648 | +----------------------------+ +----------------------------+| 2649 | | 2650 | iSCSI Target Node | 2651 | (within Network Entity, not shown) | 2652 +----------------------------------------------------------------+ 2654 4.4.2. SCSI Architecture Model 2656 This Section describes the relationship between the SCSI 2657 Architecture Model [SAM2] and constructs of the SCSI device, SCSI 2658 port and I_T nexus, and the iSCSI constructs described in Section 2659 4.4.1. 2661 This relationship implies implementation requirements in order to 2662 conform to the SAM2 model and other SCSI operational functions. 2663 These requirements are detailed in Section 4.4.3. 2665 The following list outlines mappings of SCSI architectural 2666 elements to iSCSI. 2668 a) SCSI Device - the SAM2 term for an entity that contains 2669 one or more SCSI ports that are connected to a service 2670 delivery subsystem and supports a SCSI application 2671 protocol. For example, a SCSI Initiator Device contains 2672 one or more SCSI Initiator Ports and zero or more 2673 application clients. A SCSI Target Device contains one or 2674 more SCSI Target Ports and one or more logical units. For 2675 iSCSI, the SCSI Device is the component within an iSCSI 2676 Node that provides the SCSI functionality. As such, there 2677 can be one SCSI Device, at most, within an iSCSI Node. 2678 Access to the SCSI Device can only be achieved in an 2679 iSCSI normal operational session (see Section 4.3). The 2680 SCSI Device Name is defined to be the iSCSI Name of the 2681 node and MUST be used in the iSCSI protocol. 2683 b) SCSI Port - the SAM2 term for an entity in a SCSI Device 2684 that provides the SCSI functionality to interface with a 2685 service delivery subsystem or transport. For iSCSI, the 2686 definition of SCSI Initiator Port and SCSI Target Port 2687 are different. 2689 SCSI Initiator Port: This maps to one endpoint of an 2690 iSCSI normal operational session (see Section 4.3). An 2691 iSCSI normal operational session is negotiated through 2692 the login process between an iSCSI initiator node and an 2693 iSCSI target node. At successful completion of this 2694 process, a SCSI Initiator Port is created within the SCSI 2695 Initiator Device. The SCSI Initiator Port Name and SCSI 2696 Initiator Port Identifier are both defined to be the 2697 iSCSI Initiator Name together with (a) a label that 2698 identifies it as an initiator port name/identifier and 2699 (b) the ISID portion of the session identifier. 2701 SCSI Target Port: This maps to an iSCSI Target Portal 2702 Group. The SCSI Target Port Name and the SCSI Target Port 2703 Identifier are both defined to be the iSCSI Target Name 2704 together with (a) a label that identifies it as a target 2705 port name/identifier and (b) the portal group tag. 2707 The SCSI Port Name MUST be used in iSCSI. When used in 2708 SCSI parameter data, the SCSI port name MUST be encoded 2709 as: 2710 1. The iSCSI Name in UTF-8 format, followed by 2711 2. a comma separator (1 byte), followed by 2712 3. the ASCII character 'i' (for SCSI Initiator Port) 2713 or the ASCII character 't' (for SCSI Target Port) 2714 (1 byte), followed by 2715 4. a comma separator (1 byte), followed by 2716 5. a text encoding as a hex-constant (see Section 6.1) 2717 of the ISID (for SCSI initiator port) or the 2718 portal group tag (for SCSI target port) including 2719 the initial 0X or 0x and the terminating null (14 2720 bytes). 2722 The ASCII character 'i' or 't' is the label that 2723 identifies this port as either a SCSI Initiator 2724 Port or a SCSI Target Port. 2726 c) I_T nexus - a relationship between a SCSI Initiator Port 2727 and a SCSI Target Port, according to [SAM2]. For iSCSI, 2728 this relationship is a session, defined as a relationship 2729 between an iSCSI Initiator's end of the session (SCSI 2730 Initiator Port) and the iSCSI Target's Portal Group. The 2731 I_T nexus can be identified by the conjunction of the 2732 SCSI port names or by the iSCSI session identifier SSID. 2733 iSCSI defines the I_T nexus identifier to be the tuple 2734 (iSCSI Initiator Name + ",i,0x" + ISID in text format, 2735 iSCSI Target Name + ",t,0x" + Portal Group Tag in text 2736 format) - an upper case hex prefix "0X" may alternatively 2737 be used in place of "0x". 2739 NOTE: The I_T nexus identifier is not equal to the 2740 session identifier (SSID). 2742 4.4.3. Consequences of the Model 2744 This Section describes implementation and behavioral requirements 2745 that result from the mapping of SCSI constructs to the iSCSI 2746 constructs defined above. Between a given SCSI initiator port and 2747 a given SCSI target port, only one I_T nexus (session) can exist. 2748 No more than one nexus relationship (parallel nexus) is allowed by 2749 [SAM2]. Therefore, at any given time, only one session with the 2750 same session identifier (SSID) can exist between a given iSCSI 2751 initiator node and an iSCSI target node. 2753 These assumptions lead to the following conclusions and 2754 requirements: 2756 ISID RULE: Between a given iSCSI Initiator and iSCSI Target Portal 2757 Group (SCSI target port), there can only be one session with a 2758 given value for ISID that identifies the SCSI initiator port. See 2759 Section 11.12.5. 2761 The structure of the ISID that contains a naming authority 2762 component (see Section 11.12.5 and [RFC3721]) provides a mechanism 2763 to facilitate compliance with the ISID rule. (See Section 10.1.1) 2765 The iSCSI Initiator Node should manage the assignment of ISIDs 2766 prior to session initiation. The "ISID RULE" does not preclude the 2767 use of the same ISID from the same iSCSI Initiator with different 2768 Target Portal Groups on the same iSCSI target or on other iSCSI 2769 targets (see Section 10.1.1). Allowing this would be analogous to 2770 a single SCSI Initiator Port having relationships (nexus) with 2771 multiple SCSI target ports on the same SCSI target device or SCSI 2772 target ports on other SCSI target devices. It is also possible to 2773 have multiple sessions with different ISIDs to the same Target 2774 Portal Group. Each such session would be considered to be with a 2775 different initiator even when the sessions originate from the same 2776 initiator device. The same ISID may be used by a different iSCSI 2777 initiator because it is the iSCSI Name together with the ISID that 2778 identifies the SCSI Initiator Port. 2780 NOTE: A consequence of the ISID RULE and the specification for the 2781 I_T nexus identifier is that two nexus with the same identifier 2782 should never exist at the same time. 2784 TSIH RULE: The iSCSI Target selects a non-zero value for the TSIH 2785 at session creation (when an initiator presents a 0 value at 2786 Login). After being selected, the same TSIH value MUST be used 2787 whenever initiator or target refers to the session and a TSIH is 2788 required. 2790 4.4.3.1. I_T Nexus State 2792 Certain nexus relationships contain an explicit state (e.g., 2793 initiator-specific mode pages) that may need to be preserved by 2794 the device server [SAM2] in a logical unit through changes or 2795 failures in the iSCSI layer (e.g., session failures). In order for 2796 that state to be restored, the iSCSI initiator should reestablish 2797 its session (re-login) to the same Target Portal Group using the 2798 previous ISID. That is, it should reinstate the session via iSCSI 2799 session reinstatement (Section 6.3.5) or continue via session 2800 continuation (Section 6.3.6). This is because the SCSI initiator 2801 port identifier and the SCSI target port identifier (or relative 2802 target port) form the datum that the SCSI logical unit device 2803 server uses to identify the I_T nexus. 2805 4.4.3.2. Reservations 2807 There are two reservation management methods defined in the SCSI 2808 standards, reserve/release reservations, based on the RESERVE and 2809 RELEASE commands [SPC2], and persistent reservations, based on the 2810 PERSISTENT RESERVE IN and PERSISTENT RESERVE OUT commands [SPC3]. 2811 Reserve/release reservations are obsolete [SPC3] and should not be 2812 used; persistent reservations are suggested as an alternative, see 2813 Annex B of [SPC4]. 2815 State for persistent reservations is required to persist through 2816 changes and failures at the iSCSI layer that result in I_T nexus 2817 failures, see [SPC3] for details and specific requirements. 2819 In contrast, [SPC2] does not specify detailed persistence 2820 requirements for reserve/release reservation state after an I_T 2821 nexus failure. Nonetheless, when reserve/release reservations are 2822 supported by an iSCSI target, the preferred implementation 2823 approach is to preserve reserve/release reservation state for 2824 iSCSI session reinstatement (see Section 6.3.5) or session 2825 continuation (see Section 6.3.6). 2827 Two additional caveats apply to reserve/release reservations: 2829 - Retention of a failed session's reserve/release reservation 2830 state by an iSCSI target, even after that failed iSCSI 2831 session is not reinstated or continued, may require an 2832 initiator to issue a reset (e.g., LOGICAL UNIT RESET, see 2833 Section 11.5) in order to remove that reservation state. 2835 - Reserve/release reservations may not behave as expected when 2836 persistent reservations are also used on the same logical 2837 unit; see the discussion of "Exceptions to SPC-2 RESERVE and 2838 RELEASE behavior" in [SPC4]. 2840 4.5. iSCSI UML Model 2842 This Section presents the application of the UML modeling concepts 2843 discussed in Section 3 to the iSCSI and SCSI architecture model 2844 discussed in Section 4.4. 2846 +----------------+ 2847 | Network Entity | 2848 +----------------+ 2849 @ 1 @ 1 2850 | | 2851 +--------------------+ | 2852 | | 2853 | | 0..* 2854 | +------------------+ 2855 | | iSCSI Node | 2856 | +------------------+ 2857 | @ @ 2858 | | | 2859 | +-----------+ =(a)= +-----------+ 2860 | | | 2861 | | 0..1 | 0..1 2862 | +------------------------+ +----------------------+ 2863 | | iSCSI Target Node | | iSCSI Initiator Node | 2864 | +------------------------+ +----------------------+ 2865 | @ 1 @ 1 2866 | +--------------+ | 2867 | 1..* | | 1..* 2868 | +-----------------------------+ 2869 | | Portal Group | 2870 | +-----------------------------+ 2871 | O 1 2872 | | 2873 | | 1..* 2874 | 1..* +------------------------+ 2875 +-------------------| Network Portal | 2876 +------------------------+ 2878 (a) Each instance of an iSCSI Node class MUST contain one iSCSI 2879 Target Node instance or one iSCSI Initiator Node instance, or 2880 both. 2882 +----------------+ 2883 | Network Entity | 2884 +----------------+ 2885 @ 1 @ 1 2886 | | +-------------------+ 2887 +---------------------+ | | iSCSI Session | 2888 | | +-------------------+ 2889 | | 0..* | SSID[1] | 2890 | +--------------------+ | ISID[1] | 2891 | | iSCSI Node | +-------------------+ 2892 | +--------------------+ @ 1 2893 | | iSCSI Node Name[1] | | 2894 | | Alias [0..1] | | 0..* 2895 | +--------------------+ +------------------+ 2896 | | | | iSCSI Connection | 2897 | +--------------------+ +------------------+ 2898 | @ 1 @ 1 | CID[1] | 2899 | | | +------------------+ 2900 | +-------------+ ==(b)== +----------+ 0..* | 2901 | | 1 | 1 | 2902 | +------------------------+ +------------------------+ | 2903 | | iSCSI Target Node | | iSCSI Initiator Node | | 2904 | +------------------------+ +------------------------+ | 2905 | | iSCSI Target name [1] | |iSCSI Initiator Name [1]| | 2906 | +------------------------+ +------------------------+ | 2907 | @ 1 @ 1 | 2908 | | 1..* | 1..* | 2909 | +--------------------------+ +------------------------+ | 2910 | | Target Portal Group | | Initiator Portal Group | | 2911 | +--------------------------+ +------------------------+ | 2912 | |Target Portal Group Tag[1]| | Portal group tag[1] | | 2913 | +--------------------------+ +------------------------+ | 2914 | o 1 o 1 | 2915 | +------------+ +---------+ | 2916 | 1..* | | 1..* | 2917 | +-------------------------+ | 2918 | | Network Portal | | 2919 | +-------------------------+ | 2920 | 1..* | IP Address [1] | 1 | 2921 +----------------| TCP Port [0..1] |<----------------------+ 2922 +-------------------------+ 2924 (b) Each instance of an iSCSI Node class MUST contain one iSCSI 2925 Target Node instance or one iSCSI Initiator Node instance, or 2926 both. However, in all scenarios, note that an iSCSI Node MUST 2927 only have a single iSCSI Name. Note the related requirement in 2928 Section 4.2.7.1. 2930 4.6. Request/Response Summary 2932 This Section lists and briefly describes all the iSCSI PDU types 2933 (request and responses). 2935 All iSCSI PDUs are built as a set of one or more header segments 2936 (basic and auxiliary) and zero or one data segments. The header 2937 group and the data segment may each be followed by a CRC (digest) 2938 (see [CRC]). 2940 The basic header segment has a fixed length of 48 bytes. 2942 4.6.1. Request/Response Types Carrying SCSI Payload 2944 4.6.1.1. SCSI-Command 2946 This request carries the SCSI CDB and all the other SCSI execute 2947 command procedure call (see [SAM2]) IN arguments such as task 2948 attributes, Expected Data Transfer Length for one or both transfer 2949 directions (the latter for bidirectional commands), and Task Tag 2950 (as part of the I_T_L_x nexus). The I_T_L nexus is derived by the 2951 initiator and target from the LUN field in the request and the I_T 2952 nexus is implicit in the session identification. 2954 In addition, the SCSI-command PDU carries information required for 2955 the proper operation of the iSCSI protocol - the command sequence 2956 number (CmdSN) and the expected status number (ExpStatSN) on the 2957 connection it is issued. 2959 All or part of the SCSI output (write) data associated with the 2960 SCSI command may be sent as part of the SCSI-Command PDU as a data 2961 segment. 2963 4.6.1.2. SCSI-Response 2965 The SCSI-Response carries all the SCSI execute-command procedure 2966 call (see [SAM2]) OUT arguments and the SCSI execute-command 2967 procedure call return value. 2969 The SCSI-Response contains the residual counts from the operation, 2970 if any, an indication of whether the counts represent an overflow 2971 or an underflow, and the SCSI status if the status is valid or a 2972 response code (a non-zero return value for the execute-command 2973 procedure call) if the status is not valid. 2975 For a valid status that indicates that the command has been 2976 processed, but resulted in an exception (e.g., a SCSI CHECK 2977 CONDITION), the PDU data segment contains the associated sense 2978 data. The use of Autosense ([SAM2]) is REQUIRED by iSCSI. 2980 Some data segment content may also be associated (in the data 2981 segment) with a non-zero response code. 2983 In addition, the SCSI-Response PDU carries information required 2984 for the proper operation of the iSCSI protocol: 2986 - The number of Data-In PDUs that a target has sent (to enable 2987 the initiator to check that all have arrived). 2989 - StatSN - the Status Sequence Number on this connection. 2991 - ExpCmdSN - the next Expected Command Sequence Number at the 2992 target. 2994 - MaxCmdSN - the maximum CmdSN acceptable at the target from 2995 this initiator. 2997 4.6.1.3. Task Management Function Request 2999 The Task Management function request provides an initiator with a 3000 way to explicitly control the execution of one or more SCSI Tasks 3001 or iSCSI functions. The PDU carries a function identifier (which 3002 task management function to perform) and enough information to 3003 unequivocally identify the task or task-set on which to perform 3004 the action, even if the task(s) to act upon has not yet arrived or 3005 has been discarded due to an error. 3007 The referenced tag identifies an individual task if the function 3008 refers to an individual task. 3010 The I_T_L nexus identifies task sets. In iSCSI the I_T_L nexus is 3011 identified by the LUN and the session identification (the session 3012 identifies an I_T nexus). 3014 For task sets, the CmdSN of the Task Management function request 3015 helps identify the tasks upon which to act, namely all tasks 3016 associated with a LUN and having a CmdSN preceding the Task 3017 Management function request CmdSN. 3019 For a Task Management function, the coordination between responses 3020 to the tasks affected and the Task Management function response is 3021 done by the target. 3023 4.6.1.4. Task Management Function Response 3025 The Task Management function response carries an indication of 3026 function completion for a Task Management function request 3027 including how it completed (response and qualifier) and additional 3028 information for failure responses. 3030 After the Task Management response indicates Task Management 3031 function completion, the initiator will not receive any additional 3032 responses from the affected tasks. 3034 4.6.1.5. SCSI Data-out and SCSI Data-in 3036 SCSI Data-out and SCSI Data-in are the main vehicles by which SCSI 3037 data payload is carried between initiator and target. Data payload 3038 is associated with a specific SCSI command through the Initiator 3039 Task Tag. For target convenience, outgoing solicited data also 3040 carries a Target Transfer Tag (copied from R2T) and the LUN. Each 3041 PDU contains the payload length and the data offset relative to 3042 the buffer address contained in the SCSI execute command procedure 3043 call. 3045 In each direction, the data transfer is split into "sequences". An 3046 end-of-sequence is indicated by the F bit. 3048 An outgoing sequence is either unsolicited (only the first 3049 sequence can be unsolicited) or consists of all the Data-Out PDUs 3050 sent in response to an R2T. 3052 Input sequences enable the switching of direction for 3053 bidirectional commands as required. 3055 For input, the target may request positive acknowledgement of 3056 input data. This is limited to sessions that support error 3057 recovery and is implemented through the A bit in the SCSI Data-in 3058 PDU header. 3060 Data-in and Data-out PDUs also carry the DataSN to enable the 3061 initiator and target to detect missing PDUs (discarded due to an 3062 error). 3064 In addition, StatSN is carried by the Data-In PDUs. 3066 To enable a SCSI command to be processed while involving a minimum 3067 number of messages, the last SCSI Data-in PDU passed for a command 3068 may also contain the status if the status indicates termination 3069 with no exceptions (no sense or response involved). 3071 4.6.1.6. Ready To Transfer (R2T) 3073 R2T is the mechanism by which the SCSI target "requests" the 3074 initiator for output data. R2T specifies to the initiator the 3075 offset of the requested data relative to the buffer address from 3076 the execute command procedure call and the length of the solicited 3077 data. 3079 To help the SCSI target associate the resulting Data-out with an 3080 R2T, the R2T carries a Target Transfer Tag that will be copied by 3081 the initiator in the solicited SCSI Data-out PDUs. There are no 3082 protocol specific requirements with regard to the value of these 3083 tags, but it is assumed that together with the LUN, they will 3084 enable the target to associate data with an R2T. 3086 R2T also carries information required for proper operation of the 3087 iSCSI protocol, such as: 3089 - R2TSN (to enable an initiator to detect a missing R2T) 3091 - StatSN 3093 - ExpCmdSN 3095 - MaxCmdSN 3097 4.6.2. Requests/Responses carrying SCSI and iSCSI Payload 3099 4.6.2.1. Asynchronous Message 3101 Asynchronous Messages are used to carry SCSI asynchronous events 3102 (AEN) and iSCSI asynchronous messages. 3104 When carrying an AEN, the event details are reported as sense data 3105 in the data segment. 3107 4.6.3. Requests/Responses Carrying iSCSI Only Payload 3109 4.6.3.1. Text Request and Text Response 3111 Text requests and responses are designed as a parameter 3112 negotiation vehicle and as a vehicle for future extension. 3114 In the data segment Text Requests/Responses carry text information 3115 using a simple "key=value" syntax. 3117 Text Request/Responses may form extended sequences using the same 3118 Initiator Task Tag. The initiator uses the F (Final) flag bit in 3119 the text request header to indicate its readiness to terminate a 3120 sequence. The target uses the F (Final) flag bit in the text 3121 response header to indicate its consent to sequence termination. 3123 Text Request and Responses also use the Target Transfer Tag to 3124 indicate continuation of an operation or a new beginning. A target 3125 that wishes to continue an operation will set the Target Transfer 3126 Tag in a Text Response to a value different from the default 3127 0xffffffff. An initiator willing to continue will copy this value 3128 into the Target Transfer Tag of the next Text Request. If the 3129 initiator wants to restart the current target negotiation (start 3130 fresh) will set the Target Transfer Tag to 0xffffffff. 3132 Although a complete exchange is always started by the initiator, 3133 specific parameter negotiations may be initiated by the initiator 3134 or target. 3136 4.6.3.2. Login Request and Login Response 3138 Login Requests and Responses are used exclusively during the Login 3139 Phase of each connection to set up the session and connection 3140 parameters. (The Login Phase consists of a sequence of login 3141 requests and responses carrying the same Initiator Task Tag.) 3143 A connection is identified by an arbitrarily selected connection- 3144 ID (CID) that is unique within a session. 3146 Similar to the Text Requests and Responses, Login 3147 Requests/Responses carry key=value text information with a simple 3148 syntax in the data segment. 3150 The Login Phase proceeds through several stages (security 3151 negotiation, operational parameter negotiation) that are selected 3152 with two binary coded fields in the header -- the "current stage" 3153 (CSG) and the "next stage" (NSG) with the appearance of the latter 3154 being signaled by the "transit" flag (T). 3156 The first Login Phase of a session plays a special role, called 3157 the leading login, which determines some header fields (e.g., the 3158 version number, the maximum number of connections, and the session 3159 identification). 3161 The CmdSN initial value is also set by the leading login. 3163 StatSN for each connection is initiated by the connection login. 3165 A login request may indicate an implied logout (cleanup) of the 3166 connection to be logged in (a connection restart) by using the 3167 same Connection ID (CID) as an existing connection as well as the 3168 same session identifying elements of the session to which the old 3169 connection was associated. 3171 4.6.3.3. Logout Request and Response 3173 Logout Requests and Responses are used for the orderly closing of 3174 connections for recovery or maintenance. The logout request may be 3175 issued following a target prompt (through an asynchronous message) 3176 or at an initiators initiative. When issued on the connection to 3177 be logged out no other request may follow it. 3179 The Logout response indicates that the connection or session 3180 cleanup is completed and no other responses will arrive on the 3181 connection (if received on the logging out connection). In 3182 addition, the Logout Response indicates how long the target will 3183 continue to hold resources for recovery (e.g., command execution 3184 that continues on a new connection) in the Time2Retain field and 3185 how long the initiator must wait before proceeding with recovery 3186 in the Time2Wait field. 3188 4.6.3.4. SNACK Request 3190 With the SNACK Request, the initiator requests retransmission of 3191 numbered-responses or data from the target. A single SNACK request 3192 covers a contiguous set of missing items, called a run, of a given 3193 type of items. The type is indicated in a type field in the PDU 3194 header. The run is composed of an initial item (StatSN, DataSN, 3195 R2TSN) and the number of missed Status, Data, or R2T PDUs. For 3196 long data-in sequences, the target may request (at predefined 3197 minimum intervals) a positive acknowledgement for the data sent. A 3198 SNACK request with a type field that indicates ACK and the number 3199 of Data-In PDUs acknowledged conveys this positive 3200 acknowledgement. 3202 4.6.3.5. Reject 3204 Reject enables the target to report an iSCSI error condition 3205 (e.g., protocol, unsupported option) that uses a Reason field in 3206 the PDU header and includes the complete header of the bad PDU in 3207 the Reject PDU data segment. 3209 4.6.3.6. NOP-Out Request and NOP-In Response 3211 This request/response pair may be used by an initiator and target 3212 as a "ping" mechanism to verify that a connection/session is still 3213 active and all of its components are operational. Such a ping may 3214 be triggered by the initiator or target. The triggering party 3215 indicates that it wants a reply by setting a value different from 3216 the default 0xffffffff in the corresponding Initiator/Target 3217 Transfer Tag. 3219 NOP-In/NOP-Out may also be used "unidirectional" to convey to the 3220 initiator/target command, status or data counter values when there 3221 is no other "carrier" and there is a need to update the 3222 initiator/target. 3224 5. SCSI Mode Parameters for iSCSI 3226 There are no iSCSI specific mode pages. 3228 6. Login and Full Feature Phase Negotiation 3230 iSCSI parameters are negotiated at session or connection 3231 establishment by using Login Requests and Responses (see Section 3232 4.2.4) and during Full Feature Phase (Section 4.2.5) by using Text 3233 Requests and Responses. In both cases the mechanism used is an 3234 exchange of iSCSI-text-key=value pairs. For brevity, iSCSI-text- 3235 keys are called just keys in the rest of this document. 3237 Keys are either declarative or require negotiation and the key 3238 description indicates if the key is declarative or requires 3239 negotiation. 3241 For the declarative keys the declaring party sets a value for the 3242 key. The key specification indicates if the key can be declared by 3243 the initiator, target or both. 3245 For the keys that require negotiation, one of the parties (the 3246 proposing party) proposes a value or set of values by including 3247 the key=value in the data part of a Login or Text Request or 3248 Response. The other party (the accepting party) makes a selection 3249 based on the value or list of values proposed and includes the 3250 selected value in a key=value in the data part of the following 3251 Login or Text Response or Request. For most of the keys, both the 3252 initiator and target can be proposing parties. 3254 The login process proceeds in two stages - the security 3255 negotiation stage and the operational parameter negotiation stage. 3256 Both stages are optional but at least one of them has to be 3257 present to enable setting some mandatory parameters. 3259 If present, the security negotiation stage precedes the 3260 operational parameter negotiation stage. 3262 Progression from stage to stage is controlled by the T 3263 (Transition) bit in the Login Request/Response PDU header. Through 3264 the T bit set to 1, the initiator indicates that it would like to 3265 transition. The target agrees to the transition (and selects the 3266 next stage) when ready. A field in the Login PDU header indicates 3267 the current stage (CSG) and during transition, another field 3268 indicates the next stage (NSG) proposed (initiator) and selected 3269 (target). 3271 The Text negotiation process is used to negotiate or declare 3272 operational parameters. The negotiation process is controlled by 3273 the F (final) bit in the PDU header. During text negotiations, the 3274 F bit is used by the initiator to indicate that it is ready to 3275 finish the negotiation and by the Target to acquiesce the end of 3276 negotiation. 3278 Since some key=value pairs may not fit entirely in a single PDU, 3279 the C (continuation) bit is used (both in Login and Text) to 3280 indicate that "more follows". 3282 The text negotiation uses an additional mechanism by which a 3283 target may deliver larger amounts of data to an enquiring 3284 initiator. The target sets a Target Task Tag to be used as a 3285 bookmark which when returned by the initiator, means "go on". If 3286 reset to a "neutral value", it means "forget about the rest". 3288 This Section details types of keys and values used, the syntax 3289 rules for parameter formation, and the negotiation schemes to be 3290 used with different types of parameters. 3292 6.1. Text Format 3294 The initiator and target send a set of key=value pairs encoded in 3295 UTF-8 Unicode. All the text keys and text values specified in this 3296 document are to be presented and interpreted in the case in which 3297 they appear in this document. They are case sensitive. 3299 The following character symbols are used in this document for text 3300 items (the hexadecimal values represent Unicode code points): 3302 (a-z, A-Z) - letters 3303 (0-9) - digits 3304 " " (0x20) - space 3305 "." (0x2e) - dot 3306 "-" (0x2d) - minus 3307 "+" (0x2b) - plus 3308 "@" (0x40) - commercial at 3309 "_" (0x5f) - underscore 3310 "=" (0x3d) - equal 3311 ":" (0x3a) - colon 3313 "/" (0x2f) - solidus or slash 3314 "[" (0x5b) - left bracket 3315 "]" (0x5d) - right bracket 3316 null (0x00) - null separator 3317 "," (0x2c) - comma 3318 "~" (0x7e) - tilde 3320 Key=value pairs may span PDU boundaries. An initiator or target 3321 that sends partial key=value text within a PDU indicates that more 3322 text follows by setting the C bit in the Text or Login Request or 3323 Text or Login Response to 1. Data segments in a series of PDUs 3324 that have the C bit set to 1 and end with a PDU that have the C 3325 bit set to 0, or include a single PDU that has the C bit set to 0 3326 have to be considered as forming a single logical-text-data- 3327 segment (LTDS). 3329 Every key=value pair, including the last or only pair in a LTDS, 3330 MUST be followed by one null (0x00) delimiter. 3332 A key-name is whatever precedes the first = in the key=value pair. 3333 The term key is used frequently in this document in place of key- 3334 name. 3336 A value is whatever follows the first = in the key=value pair up 3337 to the end of the key=value pair, but not including the null 3338 delimiter. 3340 The following definitions will be used in the rest of this 3341 document: 3343 - standard-label: A string of one or more characters that 3344 consist of letters, digits, dot, minus, plus, commercial at, 3345 or underscore. A standard-label MUST begin with a capital 3346 letter and must not exceed 63 characters. 3348 - key-name: A standard-label. 3350 - text-value: A string of zero or more characters that consist 3351 of letters, digits, dot, minus, plus, commercial at, 3352 underscore, slash, left bracket, right bracket, or colon. 3354 - iSCSI-name-value: A string of one or more characters that 3355 consist of minus, dot, colon, or any character allowed by 3356 the output of the iSCSI string-prep template as specified in 3357 [RFC3722] (see also Section 4.2.7.2). 3359 - iSCSI-local-name-value: A UTF-8 string; no null characters 3360 are allowed in the string. This encoding is to be used for 3361 localized (internationalized) aliases. 3363 - boolean-value: The string "Yes" or "No". 3365 - hex-constant: A hexadecimal constant encoded as a string 3366 that starts with "0x" or "0X" followed by one or more digits 3367 or the letters a, b, c, d, e, f, A, B, C, D, E, or F. Hex- 3368 constants are used to encode numerical values or binary 3369 strings. When used to encode numerical values, the excessive 3370 use of leading 0 digits is discouraged. The string following 3371 0X (or 0x) represents a base16 number that starts with the 3372 most significant base16 digit, followed by all other digits 3373 in decreasing order of significance and ending with the 3374 least-significant base16 digit. When used to encode binary 3375 strings, hexadecimal constants have an implicit byte-length 3376 that includes four bits for every hexadecimal digit of the 3377 constant, including leading zeroes. For example, a hex- 3378 constant of n hexadecimal digits has a byte-length of (the 3379 integer part of) (n+1)/2. 3381 - decimal-constant: An unsigned decimal number with the digit 3382 0 or a string of one or more digits that start with a non- 3383 zero digit. Decimal-constants are used to encode numerical 3384 values or binary strings. Decimal constants can only be used 3385 to encode binary strings if the string length is explicitly 3386 specified. There is no implicit length for decimal strings. 3387 Decimal-constant MUST NOT be used for parameter values if 3388 the values can be equal or greater than 2**64 (numerical) or 3389 for binary strings that can be longer than 64 bits. 3391 - base64-constant: base64 constant encoded as a string that 3392 starts with "0b" or "0B" followed by 1 or more digits or 3393 letters or plus or slash or equal. The encoding is done 3394 according to [RFC2045] and each character, except equal, 3395 represents a base64 digit or a 6-bit binary string. Base64- 3397 constants are used to encode numerical-values or binary 3398 strings. When used to encode numerical values, the excessive 3399 use of leading 0 digits (encoded as A) is discouraged. The 3400 string following 0B (or 0b) represents a base64 number that 3401 starts with the most significant base64 digit, followed by 3402 all other digits in decreasing order of significance and 3403 ending with the least-significant base64 digit; the least 3404 significant base64 digit may be optionally followed by pad 3405 digits (encoded as equal) that are not considered as part of 3406 the number. When used to encode binary strings, base64- 3407 constants have an implicit byte-length that includes six 3408 bits for every character of the constant, excluding trailing 3409 equals (i.e., a base64-constant of n base64 characters 3410 excluding the trailing equals has a byte-length of ((the 3411 integer part of) (n*3/4)). Correctly encoded base64 strings 3412 cannot have n values of 1, 5 ... k*4+1. 3414 - numerical-value: An unsigned integer always less than 2**64 3415 encoded as a decimal-constant or a hex-constant. Unsigned 3416 integer arithmetic applies to numerical-values. 3418 - large-numerical-value: An unsigned integer that can be 3419 larger than or equal to 2**64 encoded as a hex constant, or 3420 base64-constant. Unsigned integer arithmetic applies to 3421 large-numeric-values. 3423 - numeric-range: Two numerical-values separated by a tilde 3424 where the value to the right of tilde must not be lower than 3425 the value to the left. 3427 - regular-binary-value: A binary string not longer than 64 3428 bits encoded as a decimal constant, hex constant, or base64- 3429 constant. The length of the string is either specified by 3430 the key definition or is the implicit byte-length of the 3431 encoded string. 3433 - large-binary-value: A binary string longer than 64 bits 3434 encoded as a hex-constant or base64-constant. The length of 3435 the string is either specified by the key definition or is 3436 the implicit byte-length of the encoded string. 3438 - binary-value: A regular-binary-value or a large-binary- 3439 value. Operations on binary values are key specific. 3441 - simple-value: Text-value, iSCSI-name-value, boolean-value, 3442 numeric-value, a numeric-range, or a binary-value. 3444 - list-of-values: A sequence of text-values separated by a 3445 comma. 3447 If not otherwise specified, the maximum length of a simple-value 3448 (not its encoded representation) is 255 bytes not including the 3449 delimiter (comma or zero byte). 3451 Any iSCSI target or initiator MUST support receiving at least 8192 3452 bytes of key=value data in a negotiation sequence. When proposing 3453 or accepting authentication methods that explicitly require 3454 support for very long authentication items, the initiator and 3455 target MUST support receiving of at least 64 kilobytes of 3456 key=value data. 3458 6.2. Text Mode Negotiation 3460 During login, and thereafter, some session or connection 3461 parameters are either declared or negotiated through an exchange 3462 of textual information. 3464 The initiator starts the negotiation and/or declaration through a 3465 Text or Login request and indicates when it is ready for 3466 completion (by setting the F bit to 1 and keeping it to 1 in a 3467 Text Request or the T bit in the Login Request). As negotiation 3468 text may span PDU boundaries, a Text or Login Request or Text or 3469 Login Response PDU that have the C bit set to 1 MUST NOT have the 3470 F/T bit set to 1. 3472 A target receiving a Text or Login Request with the C bit set to 1 3473 MUST answer with a Text or Login Response with no data segment 3474 (DataSegmentLength 0). An initiator receiving a Text or Login 3475 Response with the C bit set to 1 MUST answer with a Text or Login 3476 Request with no data segment (DataSegmentLength 0). 3478 A target or initiator SHOULD NOT use a Text or Login Response or 3479 Text or Login Request with no data segment (DataSegmentLength 0) 3480 unless explicitly required by a general or a key-specific 3481 negotiation rule. 3483 There MUST NOT be more than one outstanding Text Request, or Text 3484 Response PDU on an iSCSI connection. An outstanding PDU in this 3485 context is one that has not been acknowledged by the remote iSCSI 3486 side. 3488 The format of a declaration is: 3490 Declarer-> = 3492 The general format of text negotiation is: 3494 Proposer-> = 3496 Acceptor-> ={|NotUnderstood|Irrelevant|Reject} 3498 Thus a declaration is a one-way textual exchange (unless the key 3499 is not understood by the receiver) while a negotiation is a two- 3500 way exchange. 3502 The proposer or declarer can either be the initiator or the 3503 target, and the acceptor can either be the target or initiator, 3504 respectively. Targets are not limited to respond to key=value 3505 pairs as proposed by the initiator. The target may propose 3506 key=value pairs of its own. 3508 All negotiations are explicit (i.e., the result MUST only be based 3509 on newly exchanged or declared values). There are no implicit 3510 proposals. If a proposal is not made, then a reply cannot be 3511 expected. Conservative design also requires that default values 3512 should not be relied upon when use of some other value has serious 3513 consequences. 3515 The value proposed or declared can be a numerical-value, a 3516 numerical-range defined by lower and upper value with both 3517 integers separated by tilde, a binary value, a text-value, an 3518 iSCSI-name-value, an iSCSI-local-name-value, a boolean-value (Yes 3519 or No), or a list of comma separated text-values. A range, a 3520 large-numerical-value, an iSCSI-name-value and an iSCSI-local- 3521 name-value MAY ONLY be used if it is explicitly allowed. An 3522 accepted value can be a numerical-value, a large-numerical-value, 3523 a text-value, or a boolean-value. 3525 If a specific key is not relevant for the current negotiation, the 3526 acceptor may answer with the constant "Irrelevant" for all types 3527 of negotiation. However the negotiation is not considered as 3528 failed if the answer is "Irrelevant". The "Irrelevant" answer is 3529 meant for those cases in which several keys are presented by a 3530 proposing party but the selection made by the acceptor for one of 3531 the keys makes other keys irrelevant. The following example 3532 illustrates the use of "Irrelevant": 3534 I->T InitialR2T=No,ImmediateData=Yes,FirstBurstLength=4192 3535 T->I InitialR2T=Yes,ImmediateData=No,FirstBurstLength=Irrelevant 3537 I->T X-rdname-vkey1=(bla,alb,None), X-rdname-vkey2=(bla,alb) 3538 T->I X-rdname-vkey1=None, X-rdname-vkey2=Irrelevant 3540 Any key not understood by the acceptor may be ignored by the 3541 acceptor without affecting the basic function. However, the answer 3542 for a key not understood MUST be key=NotUnderstood. Note that 3543 NotUnderstood is a valid answer for both declarative and 3544 negotiated keys. The general iSCSI philosophy is that 3545 comprehension precedes processing for any iSCSI key. A proposer 3546 of an iSCSI key, negotiated or declarative, in a text key exchange 3547 MUST thus be able to properly handle a NotUnderstood response. 3549 The proper way to handle a NotUnderstood response depends on where 3550 the key is specified and whether the key is declarative vs. 3551 negotiated. An iSCSI implementation MUST comprehend all text keys 3552 defined in iSCSI Protocol specifications from RFC 3720 through the 3553 RFC associated with the highest protocol version that the 3554 implementation has offered (or has negotiated, in the case of an 3555 acceptor) for the iSCSIProtocolLevel key in a negotiation. 3556 Returning a NotUnderstood response on any of these text keys 3557 therefore MUST be considered a protocol error and handled 3558 accordingly. For all other "later" keys, i.e. text keys defined 3559 in specifications associated with higher values of 3560 iSCSIProtocolLevel, a NotUnderstood answer concludes the 3561 negotiation for a negotiated key whereas for a declarative key, a 3562 NotUnderstood answer simply informs the declarer of a lack of 3563 comprehension by the receiver. 3565 In either case, a NotUnderstood answer always requires that the 3566 protocol behavior associated with that key not be used within the 3567 scope of the key (connection/session) by either side. 3569 The constants "None", "Reject", "Irrelevant", and "NotUnderstood" 3570 are reserved and MUST ONLY be used as described here. Violation of 3571 this rule is a protocol error (in particular the use of "Reject", 3572 "Irrelevant", and "NotUnderstood" as proposed values). 3574 Reject or Irrelevant are legitimate negotiation options where 3575 allowed but their excessive use is discouraged. A negotiation is 3576 considered complete when the acceptor has sent the key value pair 3577 even if the value is "Reject", "Irrelevant", or "NotUnderstood". 3578 Sending the key again would be a re-negotiation and is forbidden 3579 for many keys. 3581 If the acceptor sends "Reject" as an answer the negotiated key is 3582 left at its current value (or default if no value was set). If the 3583 current value is not acceptable to the proposer on the connection 3584 or to the session it is sent, the proposer MAY choose to terminate 3585 the connection or session. 3587 All keys in this document MUST be supported by iSCSI initiators 3588 and targets when used as specified here. If used as specified, 3589 these keys MUST NOT be answered with NotUnderstood. 3591 Implementers may introduce new private keys by prefixing them with 3592 X- followed by their (reversed) domain name, or with new public 3593 keys registered with IANA. For example, the entity owning the 3594 domain example.com can issue: 3596 X-com.example.bar.foo.do_something=3 3598 Each new public key in the course of standardization MUST define 3599 the acceptable responses to the key, including NotUnderstood as 3600 appropriate. Unlike [RFC3720], note that this document prohibits 3601 the X# prefix for new public keys. Based on iSCSI implementation 3602 experience, we know that there is no longer a need for a standard 3603 name prefix for keys that allow NotUnderstood response. Note that 3604 NotUnderstood will generally have to be allowed for new public 3605 keys for backwards compatibility, as well as for private X- keys. 3606 Thus the name prefix "X#" in new public key names does not carry 3607 any significance. New public key names MUST NOT begin with "X#" 3608 prefix to avoid confusion. 3610 Implementers MAY also introduce new values, but ONLY for new keys 3611 or authentication methods (see Section 12), or digests (see 3612 Section 13.1). 3614 Whenever parameter action or acceptance are dependent on other 3615 parameters, the dependency rules and parameter sequence must be 3616 specified with the parameters. 3618 In the Login Phase (see Section 6.3), every stage is a separate 3619 negotiation. In the FullFeaturePhase, a Text Request Response 3620 sequence is a negotiation. Negotiations MUST be handled as atomic 3621 operations. For example, all negotiated values go into effect 3622 after the negotiation concludes in agreement or are ignored if the 3623 negotiation fails. 3625 Some parameters may be subject to integrity rules (e.g., 3626 parameter-x must not exceed parameter-y or parameter-u not 1 3627 implies parameter-v be Yes). Whenever required, integrity rules 3628 are specified with the keys. Checking for compliance with the 3629 integrity rule must only be performed after all the parameters are 3630 available (the existent and the newly negotiated). An iSCSI target 3631 MUST perform integrity checking before the new parameters take 3632 effect. An initiator MAY perform integrity checking. 3634 An iSCSI initiator or target MAY terminate a negotiation that does 3635 not terminate within an implementation-specific reasonable time or 3636 number of exchanges, but SHOULD allow at least six (6) exchanges. 3638 6.2.1. List negotiations 3640 In list negotiation, the originator sends a list of values (which 3641 may include "None") in its order of preference. 3643 The responding party MUST respond with the same key and the first 3644 value that it supports (and is allowed to use for the specific 3645 originator) selected from the originator list. 3647 The constant "None" MUST always be used to indicate a missing 3648 function. However, "None" is only a valid selection if it is 3649 explicitly proposed. 3651 If an acceptor does not understand any particular value in a list, 3652 it MUST ignore it. If an acceptor does not support, does not 3653 understand, or is not allowed to use any of the proposed options 3654 with a specific originator, it may use the constant "Reject" or 3655 terminate the negotiation. The selection of a value not proposed 3656 MUST be handled as a protocol error. 3658 6.2.2. Simple-value Negotiations 3660 For simple-value negotiations, the accepting party MUST answer 3661 with the same key. The value it selects becomes the negotiation 3662 result. 3664 Proposing a value not admissible (e.g., not within the specified 3665 bounds) MAY be answered with the constant "Reject", otherwise the 3666 acceptor MUST select an admissible value. 3668 The selection, by the acceptor, of a value not admissible under 3669 the selection rules is considered a protocol error. The selection 3670 rules are key-specific. 3672 For a numerical range the value selected MUST be an integer within 3673 the proposed range or "Reject" (if the range is unacceptable). 3675 For Boolean negotiations (i.e., keys taking the values Yes or No), 3676 the accepting party MUST answer with the same key and the result 3677 of the negotiation when the received value does not determine that 3678 result by itself. The last value transmitted becomes the 3679 negotiation result. The rules for selecting the value to answer 3680 with are expressed as Boolean functions of the value received, and 3681 the value that the accepting party would have selected if given a 3682 choice. 3684 Specifically, the two cases in which answers are OPTIONAL are: 3686 - The Boolean function is "AND" and the value "No" is 3687 received. The outcome of the negotiation is "No". 3689 - The Boolean function is "OR" and the value "Yes" is 3690 received. The outcome of the negotiation is "Yes". 3692 Responses are REQUIRED in all other cases, and the value chosen 3693 and sent by the acceptor becomes the outcome of the negotiation. 3695 6.3. Login Phase 3697 The Login Phase establishes an iSCSI connection between an 3698 initiator and a target; it creates also a new session or 3699 associates the connection to an existing session. The Login Phase 3700 sets the iSCSI protocol parameters, security parameters, and 3701 authenticates the initiator and target to each other. 3703 The Login Phase is only implemented via Login request and 3704 responses. The whole Login Phase is considered as a single task 3705 and has a single Initiator Task Tag (similar to the linked SCSI 3706 commands). 3708 There MUST NOT be more than one outstanding Login Request, or 3709 Login Response on an iSCSI connection. An outstanding PDU in this 3710 context is one that has not been acknowledged by the remote iSCSI 3711 side. 3713 The default MaxRecvDataSegmentLength is used during Login. 3715 The Login Phase sequence of requests and responses proceeds as 3716 follows: 3718 - Login initial request 3720 - Login partial response (optional) 3722 - More Login requests and responses (optional) 3724 - Login Final-Response (mandatory) 3726 The initial login request of any connection MUST include the 3727 InitiatorName key=value pair. The initial login request of the 3728 first connection of a session MAY also include the SessionType 3729 key=value pair. For any connection within a session whose type is 3730 not "Discovery", the first login request MUST also include the 3731 TargetName key=value pair. 3733 The Login Final-response accepts or rejects the Login request. 3735 The Login Phase MAY include a SecurityNegotiation stage and a 3736 LoginOperationalNegotiation stage and MUST include at least one of 3737 them, but the included stage MAY be empty except for the mandatory 3738 names. 3740 The login requests and responses contain a field (CSG) that 3741 indicates the current negotiation stage (SecurityNegotiation or 3742 LoginOperationalNegotiation). If both stages are used, the 3743 SecurityNegotiation MUST precede the LoginOperationalNegotiation. 3745 Some operational parameters can be negotiated outside the login 3746 through Text requests and responses. 3748 Security MUST be completely negotiated within the Login Phase. The 3749 use of underlying IPsec security is specified in Section 9.3 and 3750 in [RFC3723]. iSCSI support for security within the protocol only 3751 consists of authentication in the Login Phase. 3753 In some environments, a target or an initiator is not interested 3754 in authenticating its counterpart. It is possible to bypass 3755 authentication through the Login request and response. 3757 The initiator and target MAY want to negotiate iSCSI 3758 authentication parameters. Once this negotiation is completed, the 3759 channel is considered secure. 3761 Most of the negotiation keys are only allowed in a specific stage. 3762 The SecurityNegotiation keys appear in Section 12 and the 3763 LoginOperationalNegotiation keys appear in Section 13. Only a 3764 limited set of keys (marked as Any-Stage in Section 13) may be 3765 used in any of the two stages. 3767 Any given Login request or response belongs to a specific stage; 3768 this determines the negotiation keys allowed with the request or 3769 response. It is considered to be a protocol error to send a key 3770 not allowed in the current stage. 3772 Stage transition is performed through a command exchange 3773 (request/response) that carries the T bit and the same CSG code. 3774 During this exchange, the next stage is selected by the target 3775 through the "next stage" code (NSG). The selected NSG MUST NOT 3776 exceed the value stated by the initiator. The initiator can 3777 request a transition whenever it is ready, but a target can only 3778 respond with a transition after one is proposed by the initiator. 3780 In a negotiation sequence, the T bit settings in one pair of login 3781 request-responses have no bearing on the T bit settings of the 3782 next pair. An initiator that has a T bit set to 1 in one pair and 3783 is answered with a T bit setting of 0 may issue the next request 3784 with T bit set to 0. 3786 When a transition is requested by the initiator and acknowledged 3787 by the target, both the initiator and target switch to the 3788 selected stage. 3790 Targets MUST NOT submit parameters that require an additional 3791 initiator login request in a login response with the T bit set to 3792 1. 3794 Stage transitions during login (including entering and exit) are 3795 only possible as outlined in the following table: 3797 +-----------------------------------------------------------+ 3798 |From To -> | Security | Operational | FullFeature | 3799 | | | | | | 3800 | V | | | | 3801 +-----------------------------------------------------------+ 3802 | (start) | yes | yes | no | 3803 +-----------------------------------------------------------+ 3804 | Security | no | yes | yes | 3805 +-----------------------------------------------------------+ 3806 | Operational | no | no | yes | 3807 +-----------------------------------------------------------+ 3809 The Login Final-Response that accepts a Login Request can only 3810 come as a response to a Login request with the T bit set to 1, and 3811 both the request and response MUST indicate FullFeaturePhase as 3812 the next phase via the NSG field. 3814 Neither the initiator nor the target should attempt to declare or 3815 negotiate a parameter more than once during login except for 3816 responses to specific keys that explicitly allow repeated key 3817 declarations (e.g., TargetAddress). An attempt to 3818 renegotiate/redeclare parameters not specifically allowed MUST be 3819 detected by the initiator and target. If such an attempt is 3820 detected by the target, the target MUST respond with Login reject 3821 (initiator error); if detected by the initiator, the initiator 3822 MUST drop the connection. 3824 6.3.1. Login Phase Start 3826 The Login Phase starts with a login request from the initiator to 3827 the target. The initial login request includes: 3829 -Protocol version supported by the initiator. 3831 -iSCSI Initiator Name and iSCSI Target Name 3833 -ISID, TSIH, and connection Ids 3835 -Negotiation stage that the initiator is ready to enter. 3837 A login may create a new session or it may add a connection to an 3838 existing session. Between a given iSCSI Initiator Node (selected 3839 only by an InitiatorName) and a given iSCSI target defined by an 3840 iSCSI TargetName and a Target Portal Group Tag, the login results 3841 are defined by the following table: 3843 +----------------------------------------------------------------+ 3844 |ISID | TSIH | CID | Target action | 3845 +----------------------------------------------------------------+ 3846 |new | non-zero | any | fail the login | 3847 | | | | ("session does not exist") | 3848 +----------------------------------------------------------------+ 3849 |new | zero | any | instantiate a new session | 3850 +----------------------------------------------------------------+ 3851 |existing| zero | any | do session reinstatement | 3852 | | | | (see Section 6.3.5) | 3853 +----------------------------------------------------------------+ 3854 |existing| non-zero | new | add a new connection to | 3855 | | existing | | the session | 3856 +----------------------------------------------------------------+ 3857 |existing| non-zero |existing| do connection reinstatement| 3858 | | existing | | (see Section 7.1.4.3) | 3859 +----------------------------------------------------------------+ 3860 |existing| non-zero | any | fail the login | 3861 | | new | | ("session does not exist") | 3862 +----------------------------------------------------------------+ 3864 Determination of "existing" or "new" are made by the target. 3866 Optionally, the login request may include: 3868 -Security parameters 3869 OR 3871 -iSCSI operational parameters 3872 AND/OR 3874 -The next negotiation stage that the initiator is ready to 3875 enter. 3877 The target can answer the login in the following ways: 3879 -Login Response with Login reject. This is an immediate 3880 rejection from the target that causes the connection to 3881 terminate and the session to terminate if this is the first 3882 (or only) connection of a new session. The T bit and the CSG 3883 and NSG fields are reserved. 3885 -Login Response with Login accept as a final response (T bit 3886 set to 1 and the NSG in both request and response are set to 3887 FullFeaturePhase). The response includes the protocol 3888 version supported by the target and the session ID, and may 3889 include iSCSI operational or security parameters (that 3890 depend on the current stage). 3892 -Login Response with Login Accept as a partial response (NSG 3893 not set to FullFeaturePhase in both request and response) 3894 that indicates the start of a negotiation sequence. The 3895 response includes the protocol version supported by the 3896 target and either security or iSCSI parameters (when no 3897 security mechanism is chosen) supported by the target. 3899 If the initiator decides to forego the SecurityNegotiation stage, 3900 it issues the Login with the CSG set to 3901 LoginOperationalNegotiation and the target may reply with a Login 3902 Response that indicates that it is unwilling to accept the 3903 connection (see Section 11.13) without SecurityNegotiation and 3904 will terminate the connection with a response of Authentication 3905 failure (see Section 11.13.5). 3907 If the initiator is willing to negotiate iSCSI security, but is 3908 unwilling to make the initial parameter proposal and may accept a 3909 connection without iSCSI security, it issues the Login with the T 3910 bit set to 1, the CSG set to SecurityNegotiation, and NSG set to 3911 LoginOperationalNegotiation. If the target is also ready to skip 3912 security, the login response only contains the 3913 TargetPortalGroupTag key (see Section 13.9), the T bit set to 1, 3914 the CSG set to SecurityNegotiation, and NSG set to 3915 LoginOperationalNegotiation. 3917 An initiator that chooses to operate without iSCSI security and 3918 with all the operational parameters taking the default values 3919 issues the Login with the T bit set to 1, the CSG set to 3920 LoginOperationalNegotiation, and NSG set to FullFeaturePhase. If 3921 the target is also ready to forego security and can finish its 3922 LoginOperationalNegotiation, the Login response has T bit set to 3923 1, the CSG set to LoginOperationalNegotiation, and NSG set to 3924 FullFeaturePhase in the next stage. 3926 During the Login Phase the iSCSI target MUST return the 3927 TargetPortalGroupTag key with the first Login Response PDU with 3928 which it is allowed to do so (i.e., the first Login Response 3929 issued after the first Login Request with the C bit set to 0) for 3930 all session types. The TargetPortalGroupTag key value indicates 3931 the iSCSI portal group servicing the Login Request PDU. If the 3932 reconfiguration of iSCSI portal groups is a concern in a given 3933 environment, the iSCSI initiator should use this key to ascertain 3934 that it had indeed initiated the Login Phase with the intended 3935 target portal group. 3937 6.3.2. iSCSI Security Negotiation 3939 The security exchange sets the security mechanism and 3940 authenticates the initiator user and the target to each other. The 3941 exchange proceeds according to the authentication method chosen in 3942 the negotiation phase and is conducted using the login requests' 3943 and responses' key=value parameters. 3945 An initiator directed negotiation proceeds as follows: 3947 -The initiator sends a login request with an ordered list of 3948 the options it supports (authentication algorithm). The 3949 options are listed in the initiator's order of preference. 3950 The initiator MAY also send private or public extension 3951 options. 3952 -The target MUST reply with the first option in the list it 3953 supports and is allowed to use for the specific initiator 3954 unless it does not support any in which case it MUST answer 3955 with "Reject" (see Section 6.2). The parameters are encoded 3956 in UTF8 as key=value. For security parameters, see Section 3957 12. 3959 -When the initiator considers that it is ready to conclude the 3960 SecurityNegotiation stage, it sets the T bit to 1 and the 3961 NSG to what it would like the next stage to be. The target 3962 will then set the T bit to 1 and set NSG to the next stage 3963 in the Login response when it finishes sending its security 3964 keys. The next stage selected will be the one the target 3965 selected. If the next stage is FullFeaturePhase, the target 3966 MUST respond with a Login Response with the TSIH value. 3968 If the security negotiation fails at the target, then the target 3969 MUST send the appropriate Login Response PDU. If the security 3970 negotiation fails at the initiator, the initiator SHOULD close the 3971 connection. 3973 It should be noted that the negotiation might also be directed by 3974 the target if the initiator does support security, but is not 3975 ready to direct the negotiation (propose options). 3977 6.3.3. Operational Parameter Negotiation During the Login Phase 3979 Operational parameter negotiation during the login MAY be done: 3981 - Starting with the first Login request if the initiator does 3982 not propose any security/ integrity option. 3984 - Starting immediately after the security negotiation if the 3985 initiator and target perform such a negotiation. 3987 Operational parameter negotiation MAY involve several Login 3988 request-response exchanges started and terminated by the 3989 initiator. The initiator MUST indicate its intent to terminate the 3990 negotiation by setting the T bit to 1; the target sets the T bit 3991 to 1 on the last response. 3993 Even when the initiator indicates its intent to switch stage by 3994 setting the T bit to 1 in a Login request, the target MAY respond 3995 with a Login response with the T bit set to 0. In that case, the 3996 initiator SHOULD continue to set the T bit to 1 in subsequent 3997 Login requests (even empty) that it sends, until target sends a 3998 Login response with the T bit set to 1 or sends a key that 3999 requires initiator to set the T bit to 0. 4001 Some session specific parameters can only be specified during the 4002 Login Phase of the first connection of a session (i.e., begun by a 4003 login request that contains a zero-valued TSIH) - the leading 4004 Login Phase (e.g., the maximum number of connections that can be 4005 used for this session). 4007 A session is operational once it has at least one connection in 4008 FullFeaturePhase. New or replacement connections can only be added 4009 to a session after the session is operational. 4011 For operational parameters, see Section 13. 4013 6.3.4. Connection Reinstatement 4015 Connection reinstatement is the process of an initiator logging in 4016 with a ISID-TSIH-CID combination that is possibly active from the 4017 target's perspective, which causes the implicit logging out of the 4018 connection corresponding to the CID and reinstating a new Full 4019 Feature Phase iSCSI connection in its place (with the same CID). 4020 Thus, the TSIH in the Login Request PDU MUST be non-zero and CID 4021 does not change during a connection reinstatement. The Login 4022 request performs the logout function of the old connection if an 4023 explicit logout was not performed earlier. In sessions with a 4024 single connection, this may imply the opening of a second 4025 connection with the sole purpose of cleaning up the first. Targets 4026 MUST support opening a second connection even when they do not 4027 support multiple connections in Full Feature Phase if 4028 ErrorRecoveryLevel is 2 and SHOULD support opening a second 4029 connection if ErrorRecoveryLevel is less than 2. 4031 If the operational ErrorRecoveryLevel is 2, connection 4032 reinstatement enables future task reassignment. If the operational 4033 ErrorRecoveryLevel is less than 2, connection reinstatement is the 4034 replacement of the old CID without enabling task reassignment. In 4035 this case, all the tasks that were active on the old CID must be 4036 immediately terminated without further notice to the initiator. 4038 The initiator connection state MUST be CLEANUP_WAIT (Section 4039 8.1.3) when the initiator attempts a connection reinstatement. 4041 In practical terms, in addition to the implicit logout of the old 4042 connection, reinstatement is equivalent to a new connection login. 4044 6.3.5. Session Reinstatement, Closure, and Timeout 4046 Session reinstatement is the process of the initiator logging in 4047 with an ISID that is possibly active from the target's 4048 perspective. Thus implicitly logging out the session that 4049 corresponds to the ISID and reinstating a new iSCSI session in its 4050 place (with the same ISID). Therefore, the TSIH in the Login PDU 4051 MUST be zero to signal session reinstatement. Session 4052 reinstatement causes all the tasks that were active on the old 4053 session to be immediately terminated by the target without further 4054 notice to the initiator. 4056 The initiator session state MUST be FAILED (Section 8.3) when the 4057 initiator attempts a session reinstatement. 4059 Session closure is an event defined to be one of the following: 4061 - A successful "session close" logout. 4063 - A successful "connection close" logout for the last Full 4064 Feature Phase connection when no other connection in the 4065 session is waiting for cleanup (Section 8.2) and no tasks in 4066 the session are waiting for reassignment. 4068 Session timeout is an event defined to occur when the last 4069 connection state timeout expires and no tasks are waiting for 4070 reassignment. This takes the session to the FREE state (N6 4071 transition in the session state diagram). 4073 6.3.5.1. Loss of Nexus Notification 4075 The iSCSI layer provides the SCSI layer with the "I_T nexus loss" 4076 notification when any one of the following events happens: 4078 Successful completion of session reinstatement. 4079 Session closure event. 4080 Session timeout event. 4082 Certain SCSI object clearing actions may result due to the 4083 notification in the SCSI end nodes, as documented in Appendix E. 4085 6.3.6. Session Continuation and Failure 4087 Session continuation is the process by which the state of a 4088 preexisting session continues to be used by connection 4089 reinstatement (Section 6.3.4), or by adding a connection with a 4090 new CID. Either of these actions associates the new transport 4091 connection with the session state. 4093 Session failure is an event where the last Full Feature Phase 4094 connection reaches the CLEANUP_WAIT state (Section 8.2), or 4095 completes a successful recovery logout thus causing all active 4096 tasks (that are formerly allegiant to the connection) to start 4097 waiting for task reassignment. 4099 6.4. Operational Parameter Negotiation Outside the Login Phase 4101 Some operational parameters MAY be negotiated outside (after) the 4102 Login Phase. 4104 Parameter negotiation in Full Feature Phase is done through Text 4105 requests and responses. Operational parameter negotiation MAY 4106 involve several Text request-response exchanges, which the 4107 initiator always starts, terminates, and uses the same Initiator 4108 Task Tag. The initiator MUST indicate its intent to finish the 4109 negotiation by setting the F bit to 1; the target sets the F bit 4110 to 1 on the last response. 4112 If the target responds to a Text request with the F bit set to 1 4113 with a Text response with the F bit set to 0, the initiator should 4114 keep sending the Text request (even empty) with the F bit set to 4115 1, while it still wants to finish the negotiation, until it 4116 receives the Text response with the F bit set to 1. Responding to 4117 a Text request with the F bit set to 1 with an empty (no key=value 4118 pairs) response with the F bit set to 0 is discouraged. 4120 Even when the initiator indicates its intent to finish the 4121 negotiation by setting the F bit to 1 in a Text request, the 4122 target MAY respond with a Text response with the F bit set to 0. 4124 In that case, the initiator SHOULD continue to set the F bit to 1 4125 in subsequent Text requests (even empty) that it sends, until 4126 target sends the final Text response with the F bit set to 1. Note 4127 that in the same case of Text request with the F bit set to 1, 4128 target SHOULD NOT respond with an empty (no key=value pairs) Text 4129 response with the F bit set to 0, because such a response may 4130 cause the initiator to abandon negotiation. 4132 Targets MUST NOT submit parameters that require an additional 4133 initiator Text request in a Text response with the F bit set to 1. 4135 In a negotiation sequence, the F bit settings in one pair of Text 4136 request-responses have no bearing on the F bit settings of the 4137 next pair. An initiator that has the F bit set to 1 in a request 4138 and is being answered with an F bit setting of 0 may issue the 4139 next request with the F bit set to 0. 4141 Whenever the target responds with the F bit set to 0, it MUST set 4142 the Target Transfer Tag to a value other than the default 4143 0xffffffff. 4145 An initiator MAY reset an operational parameter negotiation by 4146 issuing a Text request with the Target Transfer Tag set to the 4147 value 0xffffffff after receiving a response with the Target 4148 Transfer Tag set to a value other than 0xffffffff. A target may 4149 reset an operational parameter negotiation by answering a Text 4150 request with a Reject PDU. 4152 Neither the initiator nor the target should attempt to declare or 4153 negotiate a parameter more than once during any negotiation 4154 sequence, except for responses to specific keys that explicitly 4155 allow repeated key declarations (e.g., TargetAddress). If detected 4156 by the target, this MUST result in a Reject PDU with a reason of 4157 "protocol error". The initiator MUST reset the negotiation as 4158 outlined above. 4160 Parameters negotiated by a text exchange negotiation sequence only 4161 become effective after the negotiation sequence is completed. 4163 7. iSCSI Error Handling and Recovery 4165 7.1. Overview 4167 7.1.1. Background 4169 The following two considerations prompted the design of much of 4170 the error recovery functionality in iSCSI: 4172 An iSCSI PDU may fail the digest check and be dropped, despite 4173 being received by the TCP layer. The iSCSI layer must 4174 optionally be allowed to recover such dropped PDUs. 4176 A TCP connection may fail at any time during the data 4177 transfer. All the active tasks must optionally be allowed 4178 to be continued on a different TCP connection within the 4179 same session. 4181 Implementations have considerable flexibility in deciding what 4182 degree of error recovery to support, when to use it and by which 4183 mechanisms to achieve the required behavior. Only the externally 4184 visible actions of the error recovery mechanisms must be 4185 standardized to ensure interoperability. 4187 This Section describes a general model for recovery in support of 4188 interoperability. See Appendix D for further detail on how the 4189 described model may be implemented. Compliant implementations do 4190 not have to match the implementation details of this model as 4191 presented, but the external behavior of such implementations must 4192 correspond to the externally observable characteristics of the 4193 presented model. 4195 7.1.2. Goals 4197 The major design goals of the iSCSI error recovery scheme are as 4198 follows: 4200 Allow iSCSI implementations to meet different requirements by 4201 defining a collection of error recovery mechanisms that 4202 implementations may choose from. 4204 Ensure interoperability between any two implementations 4205 supporting different sets of error recovery capabilities. 4207 Define the error recovery mechanisms to ensure command 4208 ordering even in the face of errors, for initiators that 4209 demand ordering. 4211 Do not make additions in the fast path, but allow moderate 4212 complexity in the error recovery path. 4214 Prevent both the initiator and target from attempting to 4215 recover the same set of PDUs at the same time. For example, 4216 there must be a clear "error recovery functionality 4217 distribution" between the initiator and target. 4219 7.1.3. Protocol Features and State Expectations 4221 The initiator mechanisms defined in connection with error recovery 4222 are: 4224 a) NOP-OUT to probe sequence numbers of the target (Section 4225 11.18) 4226 b) Command retry (Section 7.2.1) 4227 c) Recovery R2T support (Section 7.8) 4228 d) Requesting retransmission of status/data/R2T using the 4229 SNACK facility (Section 11.16) 4230 e) Acknowledging the receipt of the data (Section 11.16) 4231 f) Reassigning the connection allegiance of a task to a 4232 different TCP connection (Section 7.2.2) 4233 g) Terminating the entire iSCSI session to start afresh 4234 (Section 7.1.4.4) 4236 The target mechanisms defined in connection with error recovery 4237 are: 4239 a) NOP-IN to probe sequence numbers of the initiator (Section 4240 11.19) 4241 b) Requesting retransmission of data using the recovery R2T 4242 feature (Section 7) 4243 c) SNACK support (Section 11.16) 4244 d) Requesting that parts of read data be acknowledged (Section 4245 11.7.2) 4246 e) Allegiance reassignment support (Section 7.2.2) 4247 f) Terminating the entire iSCSI session to force the initiator 4248 to start over (Section 7.1.4.4) 4250 For any outstanding SCSI command, it is assumed that iSCSI, in 4251 conjunction with SCSI at the initiator, is able to keep enough 4252 information to be able to rebuild the command PDU, and that 4253 outgoing data is available (in host memory) for retransmission 4254 while the command is outstanding. It is also assumed that at the 4255 target, incoming data (read data) MAY be kept for recovery or it 4256 can be reread from a device server. 4258 It is further assumed that a target will keep the "status & sense" 4259 for a command it has executed if it supports status 4260 retransmission. 4262 A target that agrees to support data retransmission is expected to 4263 be prepared to retransmit the outgoing data (i.e., Data-In) on 4264 request until either the status for the completed command is 4265 acknowledged, or the data in question has been separately 4266 acknowledged. 4268 7.1.4. Recovery Classes 4270 iSCSI enables the following classes of recovery (in the order of 4271 increasing scope of affected iSCSI tasks): 4273 - Within a command (i.e., without requiring command restart). 4275 - Within a connection (i.e., without requiring the connection 4276 to be rebuilt, but perhaps requiring command restart). 4278 - Connection recovery (i.e., perhaps requiring connections to 4279 be rebuilt and commands to be reissued). 4281 - Session recovery. 4283 The recovery scenarios detailed in the rest of this Section are 4284 representative rather than exclusive. In every case, they detail 4285 the lowest class recovery that MAY be attempted. The implementer 4286 is left to decide under which circumstances to escalate to the 4287 next recovery class and/or what recovery classes to implement. 4288 Both the iSCSI target and initiator MAY escalate the error 4289 handling to an error recovery class, which impacts a larger number 4290 of iSCSI tasks in any of the cases identified in the following 4291 discussion. 4293 In all classes, the implementer has the choice of deferring errors 4294 to the SCSI initiator (with an appropriate response code), in 4295 which case the task, if any, has to be removed from the target and 4296 all the side-effects, such as ACA, must be considered. 4298 Use of within-connection and within-command recovery classes MUST 4299 NOT be attempted before the connection is in Full Feature Phase. 4301 In the detailed description of the recovery classes, the mandating 4302 terms (MUST, SHOULD, MAY, etc.) indicate normative actions to be 4303 executed if the recovery class is supported and used. 4305 7.1.4.1. Recovery Within-command 4307 At the target, the following cases lend themselves to within- 4308 command recovery: 4310 a) Lost data PDU - realized through one of the following: 4311 b) Data digest error - dealt with as specified in Section 7.8, 4312 using the option of a recovery R2T. 4313 c) Sequence reception timeout (no data or partial-data-and-no-F- 4314 bit) - considered an implicit sequence error and dealt with 4315 as specified in Section 7.9, using the option of a recovery 4316 R2T. 4317 d) Header digest error, which manifests as a sequence reception 4318 timeout or a sequence error - dealt with as specified in 4319 Section 7.9, using the option of a recovery R2T. 4321 At the initiator, the following cases lend themselves to within- 4322 command recovery: 4324 a) Lost data PDU or lost R2T - realized through one of the 4325 following: 4326 b) Data digest error - dealt with as specified in Section 7.8, 4327 using the option of a SNACK. 4328 c) Sequence reception timeout (no status) or response reception 4329 timeout - dealt with as specified in Section 7.9, using the 4330 option of a SNACK. 4331 d) Header digest error, which manifests as a sequence reception 4332 timeout or a sequence error - dealt with as specified in 4333 Section 7.9, using the option of a SNACK. 4335 To avoid a race with the target, which may already have a recovery 4336 R2T or a termination response on its way, an initiator SHOULD NOT 4337 originate a SNACK for an R2T based on its internal timeouts (if 4338 any). Recovery in this case is better left to the target. 4340 The timeout values used by the initiator and target are outside 4341 the scope of this document. Sequence reception timeout is 4342 generally a large enough value to allow the data sequence transfer 4343 to be complete. 4345 7.1.4.2. Recovery Within-connection 4347 At the initiator, the following cases lend themselves to within- 4348 connection recovery: 4350 a) Requests not acknowledged for a long time. Requests are 4351 acknowledged explicitly through ExpCmdSN or implicitly by 4352 receiving data and/or status. The initiator MAY retry non- 4353 acknowledged commands as specified in Section 7.2. 4354 b) Lost iSCSI numbered Response. It is recognized by either 4355 identifying a data digest error on a Response PDU or a Data- 4356 In PDU carrying the status, or by receiving a Response PDU 4357 with a higher StatSN than expected. In the first case, digest 4358 error handling is done as specified in Section 7.8 using the 4359 option of a SNACK. In the second case, sequence error 4360 handling is done as specified in Section 7.9, using the 4361 option of a SNACK. 4363 At the target, the following cases lend themselves to within- 4364 connection recovery: 4366 - Status/Response not acknowledged for a long time. The target 4367 MAY issue a NOP-IN (with a valid Target Transfer Tag or 4368 otherwise) that carries the next status sequence number it 4369 is going to use in the StatSN field. This helps the 4370 initiator detect any missing StatSN(s) and issue a SNACK for 4371 the status. 4373 The timeout values used by the initiator and the target are 4374 outside the scope of this document. 4376 7.1.4.3. Connection Recovery 4378 At an iSCSI initiator, the following cases lend themselves to 4379 connection recovery: 4381 a) TCP connection failure: The initiator MUST close the 4382 connection. It then MUST either implicitly or explicitly 4383 logout the failed connection with the reason code "remove the 4384 connection for recovery" and reassign connection allegiance 4385 for all commands still in progress associated with the failed 4386 connection on one or more connections (some or all of which 4387 MAY be newly established connections) using the "Task 4388 reassign" task management function (see Section 11.5.1). For 4389 an initiator, a command is in progress as long as it has not 4390 received a response or a Data-In PDU including status. 4392 Note: The logout function is mandatory. However, a new 4393 connection establishment is only mandatory if the failed 4394 connection was the last or only connection in the session. 4395 b) Receiving an Asynchronous Message that indicates one or all 4396 connections in a session has been dropped. The initiator 4397 MUST handle it as a TCP connection failure for the 4398 connection(s) referred to in the Message. 4400 At an iSCSI target, the following cases lend themselves to 4401 connection recovery: 4403 - TCP connection failure. The target MUST close the connection 4404 and, if more than one connection is available, the target 4405 SHOULD send an Asynchronous Message that indicates it has 4406 dropped the connection. Then, the target will wait for the 4407 initiator to continue recovery. 4409 7.1.4.4. Session Recovery 4411 Session recovery should be performed when all other recovery 4412 attempts have failed. Very simple initiators and targets MAY 4413 perform session recovery on all iSCSI errors and rely on recovery 4414 on the SCSI layer and above. 4416 Session recovery implies the closing of all TCP connections, 4417 internally aborting all executing and queued tasks for the given 4418 initiator at the target, terminating all outstanding SCSI commands 4419 with an appropriate SCSI service response at the initiator, and 4420 restarting a session on a new set of connection(s) (TCP connection 4421 establishment and login on all new connections). 4423 For possible clearing effects of session recovery on SCSI and 4424 iSCSI objects, refer to Appendix E. 4426 7.1.5. Error Recovery Hierarchy 4428 The error recovery classes described so far are organized into a 4429 hierarchy for ease in understanding and to limit the 4430 implementation complexity. With few and well defined recovery 4431 levels interoperability is easier to achieve. The attributes of 4432 this hierarchy are as follows: 4434 a) Each level is a superset of the capabilities of the 4435 previous level. For example, Level 1 support implies 4436 supporting all capabilities of Level 0 and more. 4437 b) As a corollary, supporting a higher error recovery level 4438 means increased sophistication and possibly an increase 4439 in resource requirements. 4440 c) Supporting error recovery level "n" is advertised and 4441 negotiated by each iSCSI entity by exchanging the text 4442 key "ErrorRecoveryLevel=n". The lower of the two 4443 exchanged values is the operational ErrorRecoveryLevel 4444 for the session. 4446 The following diagram represents the error recovery hierarchy. 4448 + 4449 / \ 4450 / 2 \ <-- Connection recovery 4451 +-----+ 4452 / 1 \ <-- Digest failure recovery 4453 +----------+ 4454 / 0 \ <-- Session failure recovery 4455 +---------------+ 4457 The following table lists the error recovery capabilities expected 4458 from the implementations that support each error recovery level. 4460 +-------------------+--------------------------------------------+ 4461 |ErrorRecoveryLevel | Associated Error recovery capabilities | 4462 +-------------------+--------------------------------------------+ 4463 | 0 | Session recovery class | 4464 | | (Session Recovery) | 4465 +-------------------+--------------------------------------------+ 4466 | 1 | Digest failure recovery (See Note below.) | 4467 | | plus the capabilities of ER Level 0 | 4468 +-------------------+--------------------------------------------+ 4469 | 2 | Connection recovery class | 4470 | | (Connection Recovery) | 4471 | | plus the capabilities of ER Level 1 | 4472 +-------------------+--------------------------------------------+ 4474 Note: Digest failure recovery is comprised of two recovery 4475 classes: Within-Connection recovery class (Recovery Within- 4476 connection) and Within-Command recovery class (Recovery Within- 4477 command). 4479 When a defined value of ErrorRecoveryLevel is proposed by an 4480 originator in a text negotiation, the originator MUST support the 4481 functionality defined for the proposed value and additionally, 4482 functionality corresponding to any defined value numerically less 4483 than the proposed. When a defined value of ErrorRecoveryLevel is 4484 returned by a responder in a text negotiation, the responder MUST 4485 support the functionality corresponding to the ErrorRecoveryLevel 4486 it is accepting. 4488 When either party attempts to use error recovery functionality 4489 beyond what is negotiated, the recovery attempts MAY fail unless 4490 an apriori agreement outside the scope of this document exists 4491 between the two parties to provide such support. 4493 Implementations MUST support error recovery level "0", while the 4494 rest are OPTIONAL to implement. In implementation terms, the 4495 above striation means that the following incremental 4496 sophistication with each level is required. 4498 +-------------------+--------------------------------------------+ 4499 |Level transition | Incremental requirement | 4500 +-------------------+--------------------------------------------+ 4501 | 0->1 | PDU retransmissions on the same connection| 4502 +-------------------+--------------------------------------------+ 4503 | 1->2 | Retransmission across connections and | 4504 | | allegiance reassignment | 4505 +-------------------+--------------------------------------------+ 4507 7.2. Retry and Reassign in Recovery 4509 This Section summarizes two important and somewhat related iSCSI 4510 protocol features used in error recovery. 4512 7.2.1. Usage of Retry 4514 By resending the same iSCSI command PDU ("retry") in the absence 4515 of a command acknowledgement (by way of an ExpCmdSN update) or a 4516 response, an initiator attempts to "plug" (what it thinks are) the 4517 discontinuities in CmdSN ordering on the target end. Discarded 4518 command PDUs, due to digest errors, may have created these 4519 discontinuities. 4521 Retry MUST NOT be used for reasons other than plugging command 4522 sequence gaps, and in particular, cannot be used for requesting 4523 PDU retransmissions from a target. Any such PDU retransmission 4524 requests for a currently allegiant command in progress may be made 4525 using the SNACK mechanism described in Section 11.16, although the 4526 usage of SNACK is OPTIONAL. 4528 If initiators, as part of plugging command sequence gaps as 4529 described above, inadvertently issue retries for allegiant 4530 commands already in progress (i.e., targets did not see the 4531 discontinuities in CmdSN ordering), the duplicate commands are 4532 silently ignored by targets as specified in Section 4.2.2.1. 4534 When an iSCSI command is retried, the command PDU MUST carry the 4535 original Initiator Task Tag and the original operational 4536 attributes (e.g., flags, function names, LUN, CDB etc.) as well as 4537 the original CmdSN. The command being retried MUST be sent on the 4538 same connection as the original command unless the original 4539 connection was already successfully logged out. 4541 7.2.2. Allegiance Reassignment 4543 By issuing a "task reassign" task management request (Section 4544 11.5.1), the initiator signals its intent to continue an already 4545 active command (but with no current connection allegiance) as part 4546 of connection recovery. This means that a new connection 4547 allegiance is requested for the command, which seeks to associate 4548 it to the connection on which the task management request is being 4549 issued. Before the allegiance reassignment is attempted for a 4550 task, an implicit or explicit Logout with the reason code "remove 4551 the connection for recovery" (see Section 11.14.1) MUST be 4552 successfully completed for the previous connection to which the 4553 task was allegiant. 4555 In reassigning connection allegiance for a command, the targets 4556 SHOULD continue the command from its current state. For example, 4557 when reassigning read commands, the target SHOULD take advantage 4558 of the ExpDataSN field provided by the Task Management function 4559 request (which must be set to zero if there was no data transfer) 4560 and bring the read command to completion by sending the remaining 4561 data and sending (or resending) the status. ExpDataSN 4562 acknowledges all data sent up to, but not including, the Data-In 4563 PDU and or R2T with DataSN (or R2TSN) equal to ExpDataSN. However, 4564 targets may choose to send/receive all unacknowledged data or all 4565 of the data on a reassignment of connection allegiance if unable 4566 to recover or maintain accurate an state. Initiators MUST NOT 4567 subsequently request data retransmission through Data SNACK for 4568 PDUs numbered less than ExpDataSN (i.e., prior to the acknowledged 4569 sequence number). For all types of commands, a reassignment 4570 request implies that the task is still considered in progress by 4571 the initiator and the target must conclude the task appropriately 4572 if the target returns the "Function Complete" response to the 4573 reassignment request. This might possibly involve retransmission 4574 of data/R2T/status PDUs as necessary, but MUST involve the 4575 (re)transmission of the status PDU. 4577 It is OPTIONAL for targets to support the allegiance reassignment. 4578 This capability is negotiated via the ErrorRecoveryLevel text key 4579 during the login time. When a target does not support allegiance 4580 reassignment, it MUST respond with a Task Management response code 4581 of "Allegiance reassignment not supported". If allegiance 4582 reassignment is supported by the target, but the task is still 4583 allegiant to a different connection, or a successful recovery 4584 Logout of the previously allegiant connection was not performed, 4585 the target MUST respond with a Task Management response code of 4586 "Task still allegiant". 4588 If allegiance reassignment is supported by the target, the Task 4589 Management response to the reassignment request MUST be issued 4590 before the reassignment becomes effective. 4592 If a SCSI Command that involves data input is reassigned, any 4593 SNACK Tag it holds for a final response from the original 4594 connection is deleted and the default value of 0 MUST be used 4595 instead. 4597 7.3. Usage Of Reject PDU in Recovery 4599 Targets MUST NOT implicitly terminate an active task by sending a 4600 Reject PDU for any PDU exchanged during the life of the task. If 4601 the target decides to terminate the task, a Response PDU (SCSI, 4602 Text, Task, etc.) must be returned by the target to conclude the 4603 task. If the task had never been active before the Reject (i.e., 4604 the Reject is on the command PDU), targets should not send any 4605 further responses because the command itself is being discarded. 4607 The above rule means that the initiator can eventually expect a 4608 response on receiving Rejects, if the received Reject is for a PDU 4609 other than the command PDU itself. The non-command Rejects only 4610 have diagnostic value in logging the errors, and they can be used 4611 for retransmission decisions by the initiators. 4613 The CmdSN of the rejected command PDU (if it is a non-immediate 4614 command) MUST NOT be considered received by the target (i.e., a 4615 command sequence gap must be assumed for the CmdSN), even though 4616 the CmdSN of the rejected command PDU may be reliably ascertained. 4617 Upon receiving the Reject, the initiator MUST plug the CmdSN gap 4618 in order to continue to use the session. The gap may be plugged 4619 either by transmitting a command PDU with the same CmdSN, or by 4620 aborting the task (see SCS on how an abort may plug a CmdSN gap). 4622 When a data PDU is rejected and its DataSN can be ascertained, a 4623 target MUST advance ExpDataSN for the current data burst if a 4624 recovery R2T is being generated. The target MAY advance its 4625 ExpDataSN if it does not attempt to recover the lost data PDU. 4627 7.4. Error Recovery Considerations for Discovery Sessions 4629 7.4.1. ErrorRecoveryLevel for Discovery Sessions 4631 The negotiation of the key ErrorRecoveryLevel is not required for 4632 Discovery sessions -- i.e., for sessions that negotiated 4633 "SessionType=Discovery" -- because the default value of 0 is 4634 necessary and sufficient for Discovery sessions. It is however 4635 possible that some legacy iSCSI implementations might attempt to 4636 negotiate the ErrorRecoveryLevel key on Discovery sessions. When 4637 such a negotiation attempt is made by the remote side, a compliant 4638 iSCSI implementation MUST propose a value of 0 (zero) in response. 4639 The operational ErrorRecoveryLevel for Discovery sessions thus 4640 MUST 4641 be 0. This naturally follows from the functionality constraints 4642 that Section 4.3 imposes on Discovery sessions. 4644 7.4.2. Reinstatement Semantics for Discovery Sessions 4646 Discovery sessions are intended to be relatively short-lived. 4647 Initiators are not expected to establish multiple Discovery 4648 sessions to the same iSCSI Network Portal. An initiator may use 4649 the same iSCSI Initiator Name and ISID when establishing different 4650 unique sessions with different targets and/or different portal 4651 groups. This behavior is discussed in Section 10.1.1 and is, in 4652 fact, encouraged as conservative reuse of ISIDs. 4654 The ISID RULE in Section 4.4.3 states that there must not be more 4655 than one session with a matching 4-tuple: . While the spirit of the ISID 4657 RULE applies to Discovery sessions the same as it does for Normal 4658 sessions, note that some Discovery sessions differ from the Normal 4659 sessions in two important aspects: 4661 a) Because Appendix C allows a Discovery session to be 4662 established without specifying a TargetName key in the 4663 Login Request PDU (let us call such a session an "Unnamed" 4664 Discovery session), there is no Target Node context to 4665 enforce the ISID RULE. 4667 b) Portal Groups are defined only in the context of a Target 4668 Node. When the TargetName key is NULL-valued (i.e., not 4669 specified), the TargetPortalGroupTag thus cannot be 4670 ascertained to enforce the ISID RULE. 4672 The following two sections describe each of the two scenarios -- 4673 Named Discovery sessions and Unnamed Discovery sessions. 4675 7.4.2.1. Unnamed Discovery Sessions 4677 For Unnamed Discovery sessions, neither the TargetName nor the 4678 TargetPortalGroupTag is available to the targets in order to 4679 enforce the ISID RULE. So the following rule applies. 4681 UNNAMED ISID RULE: Targets MUST enforce the uniqueness of the 4682 following 4-tuple for Unnamed Discovery sessions: . The following semantics are implied by 4684 this uniqueness requirement. 4686 Targets SHOULD allow concurrent establishment of one Discovery 4687 session with each of its Network Portals by the same initiator 4688 port with a given iSCSI Node Name and an ISID. Each of the 4689 concurrent Discovery sessions, if established by the same 4690 initiator port to other Network Portals, MUST be treated as 4691 independent sessions -- i.e., one session MUST NOT reinstate the 4692 other. 4694 A new Unnamed Discovery session that has a matching 4695 to an existing 4696 Discovery session MUST reinstate the existing Unnamed Discovery 4697 session. Note thus that only an Unnamed Discovery session may 4698 reinstate an Unnamed Discovery session. 4700 7.4.2.2. Named Discovery Session 4702 For a Named Discovery session, the TargetName key is specified by 4703 the initiator and thus the target can unambiguously ascertain the 4704 TargetPortalGroupTag as well. Since all the four elements of the 4705 4-tuple are known, the ISID RULE MUST be enforced by targets with 4706 no changes from Section 4.4.3 semantics. A new session with a 4707 matching 4708 thus will reinstate an existing session. Note in this case that 4709 any new iSCSI session (Discovery or Normal) with the matching 4- 4710 tuple may reinstate an existing Named Discovery iSCSI session. 4712 7.4.3. Target PDUs During Discovery 4714 Targets SHOULD NOT send any responses other than a Text Response 4715 and Logout Response on a Discovery session, once in Full Feature 4716 Phase. 4718 Implementation Note: A target may simply drop the connection in a 4719 Discovery session when it would have requested a Logout via an 4720 Async Message on Normal sessions. 4722 7.5. Connection Timeout Management 4724 iSCSI defines two session-global timeout values (in seconds) - 4725 Time2Wait and Time2Retain - that are applicable when an iSCSI Full 4726 Feature Phase connection is taken out of service either 4727 intentionally or by an exception. Time2Wait is the initial 4728 "respite time" before attempting an explicit/implicit Logout for 4729 the CID in question or task reassignment for the affected tasks 4730 (if any). Time2Retain is the maximum time after the initial 4731 respite interval that the task and/or connection state(s) is/are 4732 guaranteed to be maintained on the target to cater to a possible 4733 recovery attempt. Recovery attempts for the connection and/or 4734 task(s) SHOULD NOT be made before Time2Wait seconds, but MUST be 4735 completed within Time2Retain seconds after that initial Time2Wait 4736 waiting period. 4738 7.5.1. Timeouts on Transport Exception Events 4740 A transport connection shutdown or a transport reset without any 4741 preceding iSCSI protocol interactions informing the end-points of 4742 the fact causes a Full Feature Phase iSCSI connection to be 4743 abruptly terminated. The timeout values to be used in this case 4744 are the negotiated values of DefaultTime2Wait (Section 13.15) and 4745 DefaultTime2Retain (Section 13.16) text keys for the session. 4747 7.5.2. Timeouts on Planned Decommissioning 4749 Any planned decommissioning of a Full Feature Phase iSCSI 4750 connection is preceded by either a Logout Response PDU, or an 4751 Async Message PDU. The Time2Wait and Time2Retain field values 4752 (Section 11.15) in a Logout Response PDU, and the Parameter2 and 4753 Parameter3 fields of an Async Message (AsyncEvent types "drop the 4754 connection" or "drop all the connections"; Section 11.9.1) specify 4755 the timeout values to be used in each of these cases. 4757 These timeout values are only applicable for the affected 4758 connection, and the tasks active on that connection. These 4759 timeout values have no bearing on initiator timers (if any) that 4760 are already running on connections or tasks associated with that 4761 session. 4763 7.6. Implicit Termination of Tasks 4765 A target implicitly terminates the active tasks due to iSCSI 4766 protocol dynamics in the following cases: 4768 a) When a connection is implicitly or explicitly logged out 4769 with the reason code of "Close the connection" and there 4770 are active tasks allegiant to that connection. 4772 b) When a connection fails and eventually the connection 4773 state times out (state transition M1 in Section 8.2.2) 4774 and there are active tasks allegiant to that connection. 4776 c) When a successful Logout with the reason code of "remove 4777 the connection for recovery" is performed while there are 4778 active tasks allegiant to that connection, and those 4779 tasks eventually time out after the Time2Wait and 4780 Time2Retain periods without allegiance reassignment. 4782 d) When a connection is implicitly or explicitly logged out 4783 with the reason code of "Close the session" and there are 4784 active tasks in that session. 4786 If the tasks terminated in the above cases a), b), c) and d)are 4787 SCSI tasks, they must be internally terminated as if with CHECK 4788 CONDITION status. This status is only meaningful for appropriately 4789 handling the internal SCSI state and SCSI side effects with 4790 respect to ordering because this status is never communicated back 4791 as a terminating status to the initiator. However additional 4792 actions may have to be taken at SCSI level depending on the SCSI 4793 context as defined by the SCSI standards (e.g., queued commands 4794 and ACA, UA for the next command on the I_T nexus in cases a), b), 4795 and c) etc. - see [SAM2] and [SPC3]). 4797 7.7. Format Errors 4799 The following two explicit violations of PDU layout rules are 4800 format errors: 4802 a) Illegal contents of any PDU header field except the 4803 Opcode (legal values are specified in Section 11). 4804 b) Inconsistent field contents (consistent field contents 4805 are specified in Section 11). 4807 Format errors indicate a major implementation flaw in one of the 4808 parties. 4810 When a target or an initiator receives an iSCSI PDU with a format 4811 error, it MUST immediately terminate all transport connections in 4812 the session either with a connection close or with a connection 4813 reset and escalate the format error to session recovery (see 4814 Section 7.1.4.4). 4816 All initiator-detected PDU construction errors MUST be considered 4817 as format errors. Some examples of such errors are: 4818 - NOP-In with a valid TTT but an invalid LUN 4820 - NOP-In with a valid ITT (i.e., a NOP-In response) and also a 4821 valid TTT 4823 - SCSI Response PDU with Status=CHECK CONDITION, but 4824 DataSegmentLength = 0 4826 7.8. Digest Errors 4828 The discussion of the legal choices in handling digest errors 4829 below excludes session recovery as an explicit option, but either 4830 party detecting a digest error may choose to escalate the error to 4831 session recovery. 4833 When a target or an initiator receives any iSCSI PDU, with a 4834 header digest error, it MUST either discard the header and all 4835 data up to the beginning of a later PDU or close the connection. 4836 Because the digest error indicates that the length field of the 4837 header may have been corrupted, the location of the beginning of a 4838 later PDU needs to be reliably ascertained by other means such as 4839 the operation of a sync and steering layer. 4841 When a target receives any iSCSI PDU with a payload digest error, 4842 it MUST answer with a Reject PDU with a reason code of Data- 4843 Digest-Error and discard the PDU. 4845 - If the discarded PDU is a solicited or unsolicited iSCSI 4846 data PDU (for immediate data in a command PDU, non-data PDU 4847 rule below applies), the target MUST do one of the 4848 following: 4850 i) Request retransmission with a recovery R2T. 4851 ii) Terminate the task with a response PDU with a CHECK 4852 CONDITION Status and an iSCSI Condition of "protocol 4853 service CRC error" (Section 11.4.7.2). If the target 4854 chooses to implement this option, it MUST wait to 4855 receive all the data (signaled by a Data PDU with the 4856 final bit set for all outstanding R2Ts) before sending 4857 the response PDU. A task management command (such as an 4858 abort task) from the initiator during this wait may 4859 also conclude the task. 4860 - No further action is necessary for targets if the discarded 4861 PDU is a non-data PDU. In case of immediate data being 4862 present on a discarded command, the immediate data is 4863 implicitly recovered when the task is retried (see Section 4864 7.2.1) followed by the entire data transfer for the task. 4866 When an initiator receives any iSCSI PDU with a payload digest 4867 error, it MUST discard the PDU. 4869 - If the discarded PDU is an iSCSI data PDU, the initiator 4870 MUST do one of the following: 4872 a) Request the desired data PDU through SNACK. In 4873 response to the SNACK, the target MUST either resend 4874 the data PDU or reject the SNACK with a Reject PDU 4875 with a reason code of "SNACK reject" in which case: 4876 b) If the status has not already been sent for the 4877 command, the target MUST terminate the command with a 4878 CHECK CONDITION Status and an iSCSI Condition of 4879 "SNACK rejected" (Section 11.4.7.2). 4880 c) If the status was already sent, no further action is 4881 necessary for the target. The initiator in this case 4882 MUST wait for the status to be received and then 4883 discard it, so as to internally signal the completion 4884 with CHECK CONDITION Status and an iSCSI Condition of 4885 "protocol service CRC error" (Section 11.4.7.2). 4886 d) Abort the task and terminate the command with an 4887 error. 4889 - If the discarded PDU is a response PDU or an unsolicited PDU 4890 (e.g. Async, Reject), the initiator MUST do one of the 4891 following: 4893 a) Request PDU retransmission with a status SNACK. 4894 b) Logout the connection for recovery and continue the 4895 tasks on a different connection instance as described 4896 in Section 7.2. 4898 c) Logout to close the connection (abort all the 4899 commands associated with the connection). 4901 Note that an unsolicited PDU carries the next StatSN value on 4902 an iSCSI connection, thereby advancing the StatSN. When an 4903 initiator discards one of these PDUs due to a payload digest 4904 error, the entire PDU including the header MUST be discarded. 4905 Consequently, the initiator MUST treat the exception like a 4906 loss of any other solicited response PDU. 4908 7.9. Sequence Errors 4910 When an initiator receives an iSCSI R2T/data PDU with an out of 4911 order R2TSN/DataSN or a SCSI response PDU with an ExpDataSN that 4912 implies missing data PDU(s), it means that the initiator must have 4913 detected a header or payload digest error on one or more earlier 4914 R2T/data PDUs. The initiator MUST address these implied digest 4915 errors as described in Section 7.8. When a target receives a data 4916 PDU with an out of order DataSN, it means that the target must 4917 have hit a header or payload digest error on at least one of the 4918 earlier data PDUs. The target MUST address these implied digest 4919 errors as described in Section 7.8. 4921 When an initiator receives an iSCSI status PDU with an out of 4922 order StatSN that implies missing responses, it MUST address the 4923 one or more missing status PDUs as described in Section 7.8. As a 4924 side effect of receiving the missing responses, the initiator may 4925 discover missing data PDUs. If the initiator wants to recover the 4926 missing data for a command, it MUST NOT acknowledge the received 4927 responses that start from the StatSN of the relevant command, 4928 until it has completed receiving all the data PDUs of the command. 4930 When an initiator receives duplicate R2TSNs (due to proactive 4931 retransmission of R2Ts by the target) or duplicate DataSNs (due to 4932 proactive SNACKs by the initiator), it MUST discard the 4933 duplicates. 4935 7.10. Message Error Checking 4937 In the iSCSI implementations till date, there has been some 4938 uncertainty on the extent to which incoming messages have to be 4939 checked for protocol errors, beyond what is strictly required for 4940 processing the inbound message. This Section addresses this 4941 question. 4943 Unless this document requires it, an iSCSI implementation is not 4944 required to do an exhaustive protocol conformance check on an 4945 incoming iSCSI PDU. The iSCSI implementation especially is not 4946 required to double-check the remote iSCSI implementation's 4947 conformance to protocol requirements. 4949 7.11. SCSI Timeouts 4951 An iSCSI initiator MAY attempt to plug a command sequence gap on 4952 the target end (in the absence of an acknowledgement of the 4953 command by way of ExpCmdSN) before the ULP timeout by retrying the 4954 unacknowledged command, as described in Section 7.2. 4956 On a ULP timeout for a command (that carried a CmdSN of n), if the 4957 iSCSI initiator intends to continue the session it MUST abort the 4958 command by either using an appropriate Task Management function 4959 request for the specific command, or a "close the connection" 4960 Logout. When using an ABORT TASK, if the ExpCmdSN is still less 4961 than (n+1), the target may see the abort request while missing the 4962 original command itself due to one of the following reasons: 4964 - Original command was dropped due to digest error. 4966 - Connection on which the original command was sent was 4967 successfully logged out. On logout, the unacknowledged 4968 commands issued on the connection being logged out are 4969 discarded. 4971 If the abort request is received and the original command is 4972 missing, targets MUST consider the original command with that 4973 RefCmdSN to be received and issue a Task Management response with 4974 the response code: "Function Complete". This response concludes 4975 the task on both ends. If the abort request is received and the 4976 target can determine (based on the Referenced Task Tag) that the 4977 command was received and executed and also that the response was 4978 sent prior to the abort, then the target MUST respond with the 4979 response code of "Task Does Not Exist". 4981 7.12. Negotiation Failures 4983 Text request and response sequences, when used to set/negotiate 4984 operational parameters, constitute the negotiation/parameter 4985 setting. A negotiation failure is considered to be one or more of 4986 the following: 4988 - None of the choices, or the stated value, is acceptable to 4989 one of the sides in the negotiation. 4991 - The text request timed out and possibly terminated. 4993 - The text request was answered with a Reject PDU. 4995 The following two rules should be used to address negotiation 4996 failures: 4998 a) During Login, any failure in negotiation MUST be 4999 considered a login process failure and the Login Phase 5000 MUST be terminated, and with it, the connection. If the 5001 target detects the failure, it must terminate the login 5002 with the appropriate login response code. 5004 b) A failure in negotiation, while in the Full Feature 5005 Phase, will terminate the entire negotiation sequence 5006 that may consist of a series of text requests that use 5007 the same Initiator Task Tag. The operational parameters 5008 of the session or the connection MUST continue to be the 5009 values agreed upon during an earlier successful 5010 negotiation (i.e., any partial results of this 5011 unsuccessful negotiation MUST NOT take effect and MUST be 5012 discarded). 5014 7.13. Protocol Errors 5016 Mapping framed messages over a "stream" connection, such as TCP, 5017 makes the proposed mechanisms vulnerable to simple software 5018 framing errors. On the other hand, the introduction of framing 5019 mechanisms to limit the effects of these errors may be onerous on 5020 performance for simple implementations. Command Sequence Numbers 5021 and the above mechanisms for connection drop and reestablishment 5022 help handle this type of mapping errors. 5024 All violations of iSCSI PDU exchange sequences specified in this 5025 draft are also protocol errors. This category of errors can only 5026 be 5027 addressed by fixing the implementations; iSCSI defines Reject and 5028 response codes to enable this. 5030 7.14. Connection Failures 5032 iSCSI can keep a session in operation if it is able to 5033 keep/establish at least one TCP connection between the initiator 5034 and the target in a timely fashion. Targets and/or initiators may 5035 recognize a failing connection by either transport level means 5036 (TCP), a gap in the command sequence number, a response stream 5037 that is not filled for a long time, or by a failing iSCSI NOP 5038 (acting as a ping). The latter MAY be used periodically to 5039 increase the speed and likelihood of detecting connection 5040 failures. Initiators and targets MAY also use the keep-alive 5041 option on the TCP connection to enable early link failure 5042 detection on otherwise idle links. 5044 On connection failure, the initiator and target MUST do one of the 5045 following: 5047 a) Attempt connection recovery within the session 5048 (Connection Recovery). 5050 b) Logout the connection with the reason code "closes the 5051 connection" (Section 10.14.5), re-issue missing commands, 5052 and implicitly terminate all active commands. This option 5053 requires support for the within-connection recovery class 5054 (Recovery Within-connection). 5056 c) Perform session recovery (Session Recovery). 5058 Either side may choose to escalate to session recovery (via the 5059 initiator dropping all the connections, or via an Async Message 5060 that announces the similar intent from a target), and the other 5061 side MUST give it precedence. On a connection failure, a target 5062 MUST terminate and/or discard all of the active immediate commands 5063 regardless of which of the above options is used (i.e., immediate 5064 commands are not recoverable across connection failures). 5066 7.15. Session Errors 5068 If all of the connections of a session fail and cannot be 5069 reestablished in a short time, or if initiators detect protocol 5070 errors repeatedly, an initiator may choose to terminate a session 5071 and establish a new session. 5073 In this case, the initiator takes the following actions: 5075 - Resets or closes all the transport connections. 5077 - Terminates all outstanding requests with an appropriate 5078 response before initiating a new session. If the same I_T 5079 nexus is intended to be reestablished, the initiator MUST 5080 employ session reinstatement (see Section 6.3.5). 5082 When the session timeout (the connection state timeout for the 5083 last failed connection) happens on the target, it takes the 5084 following actions: 5086 - Resets or closes the TCP connections (closes the session). 5088 - Terminates all active tasks that were allegiant to the 5089 connection(s) that constituted the session. 5091 A target MUST also be prepared to handle a session reinstatement 5092 request from the initiator that may be addressing session errors. 5094 8. State Transitions 5096 iSCSI connections and iSCSI sessions go through several well- 5097 defined states from the time they are created to the time they are 5098 cleared. 5100 The connection state transitions are described in two separate but 5101 dependent state diagrams for ease in understanding. The first 5102 diagram, "standard connection state diagram", describes the 5103 connection state transitions when the iSCSI connection is not 5104 waiting for, or undergoing, a cleanup by way of an explicit or 5105 implicit Logout. The second diagram, "connection cleanup state 5106 diagram", describes the connection state transitions while 5107 performing the iSCSI connection cleanup. 5109 The "session state diagram" describes the state transitions an 5110 iSCSI session would go through during its lifetime, and it depends 5111 on the states of possibly multiple iSCSI connections that 5112 participate in the session. 5114 States and transitions are described in text, tables and diagrams. 5115 The diagrams are used for illustration. The text and the tables 5116 are the governing specification. 5118 8.1. Standard Connection State Diagrams 5120 8.1.1. State Descriptions for Initiators and Targets 5122 State descriptions for the standard connection state diagram are 5123 as follows: 5124 -S1: FREE 5125 -initiator: State on instantiation, or after successful 5126 connection closure. 5127 -target: State on instantiation, or after successful 5128 connection closure. 5129 -S2: XPT_WAIT 5130 -initiator: Waiting for a response to its transport 5131 connection establishment request. 5132 -target: Illegal 5133 -S3: XPT_UP 5134 -initiator: Illegal 5135 -target: Waiting for the Login process to commence. 5137 -S4: IN_LOGIN 5138 -initiator: Waiting for the Login process to conclude, 5139 possibly involving several PDU exchanges. 5140 -target: Waiting for the Login process to conclude, 5141 possibly involving several PDU exchanges. 5142 -S5: LOGGED_IN 5143 -initiator: In Full Feature Phase, waiting for all 5144 internal, iSCSI, and transport events. 5145 -target: In Full Feature Phase, waiting for all internal, 5146 iSCSI, and transport events. 5147 -S6: IN_LOGOUT 5148 -initiator: Waiting for a Logout response. 5149 -target: Waiting for an internal event signaling completion 5150 of logout processing. 5151 -S7: LOGOUT_REQUESTED 5152 -initiator: Waiting for an internal event signaling 5153 readiness to proceed with Logout. 5154 -target: Waiting for the Logout process to start after 5155 having requested a Logout via an Async Message. 5156 -S8: CLEANUP_WAIT 5157 -initiator: Waiting for the context and/or resources to 5158 initiate the cleanup processing for this CSM. 5159 -target: Waiting for the cleanup process to start for this 5160 CSM. 5161 8.1.2. State Transition Descriptions for Initiators and Targets 5163 -T1: 5164 -initiator: Transport connect request was made (e.g., TCP 5165 SYN sent). 5166 -target: Illegal 5167 -T2: 5168 -initiator: Transport connection request timed out, a 5169 transport reset was received, or an internal event of 5170 receiving a Logout response (success) on another connection 5171 for a "close the session" Logout request was received. 5172 -target:Illegal 5173 -T3: 5174 -initiator: Illegal 5175 -target: Received a valid transport connection request that 5176 establishes the transport connection. 5177 -T4: 5179 -initiator: Transport connection established, thus 5180 prompting the initiator to start the iSCSI Login. 5181 -target: Initial iSCSI Login request was received. 5182 -T5: 5183 -initiator: The final iSCSI Login response with a Status- 5184 Class of zero was received. 5185 -target: The final iSCSI Login request to conclude the 5186 Login Phase was received, thus prompting the target to send 5187 the final iSCSI Login response with a Status-Class of zero. 5188 -T6: 5189 -initiator: Illegal 5190 -target: Timed out waiting for an iSCSI Login, transport 5191 disconnect indication was received, transport reset was 5192 received, or an internal event indicating a transport 5193 timeout was received. In all these cases, the connection is 5194 to be closed. 5195 -T7: 5196 -initiator - one of the following events caused the 5197 transition: 5198 a) The final iSCSI Login response was received with a 5199 non-zero Status-Class. 5200 b) Login timed out. 5201 c) A transport disconnect indication was received. 5202 d) A transport reset was received. 5203 e) An internal event indicating a transport timeout was 5204 received. 5205 f) An internal event of receiving a Logout response 5206 (success) on another connection for a "close the 5207 session" Logout request was received. 5209 In all these cases, the transport connection is closed. 5211 -target - one of the following events caused the 5212 transition: 5213 a) The final iSCSI Login request to conclude the Login 5214 Phase was received, prompting the target to send the 5215 final iSCSI Login response with a non-zero Status- 5216 Class. 5217 b) Login timed out. 5218 c) Transport disconnect indication was received. 5220 d) Transport reset was received. 5221 e) An internal event indicating a transport timeout was 5222 received. 5223 f) On another connection, a "close the session" Logout 5224 request was received. 5226 In all these cases, the connection is to be closed. 5227 -T8: 5228 -initiator: An internal event of receiving a Logout 5229 response (success) on another connection for a "close the 5230 session" Logout request was received, thus closing this 5231 connection requiring no further cleanup. 5232 -target: An internal event of sending a Logout response 5233 (success) on another connection for a "close the session" 5234 Logout request was received, or an internal event of a 5235 successful connection/session reinstatement is received, 5236 thus prompting the target to close this connection cleanly. 5237 -T9, T10: 5238 -initiator: An internal event that indicates the readiness 5239 to start the Logout process was received, thus prompting an 5240 iSCSI Logout to be sent by the initiator. 5241 -target: An iSCSI Logout request was received. 5242 -T11, T12: 5243 -initiator: Async PDU with AsyncEvent "Request Logout" was 5244 received. 5245 -target: An internal event that requires the 5246 decommissioning of the connection is received, thus causing 5247 an Async PDU with an AsyncEvent "Request Logout" to be 5248 sent. 5249 -T13: 5250 -initiator: An iSCSI Logout response (success) was 5251 received, or an internal event of receiving a Logout 5252 response (success) on another connection for a "close the 5253 session" Logout request was received. 5254 -target: An internal event was received that indicates 5255 successful processing of the Logout, which prompts an iSCSI 5256 Logout response (success) to be sent; an internal event of 5257 sending a Logout response (success) on another connection 5258 for a "close the session" Logout request was received; or 5259 an internal event of a successful connection/session 5260 reinstatement is received. In all these cases, the 5261 transport connection is closed. 5263 -T14: 5264 -initiator: Async PDU with AsyncEvent "Request Logout" was 5265 received again. 5266 -target: Illegal 5267 -T15, T16: 5268 -initiator: One or more of the following events caused this 5269 transition: 5270 a) Internal event that indicates a transport connection 5271 timeout was received thus prompting transport RESET 5272 or transport connection closure. 5273 b) A transport RESET. 5274 c) A transport disconnect indication. 5275 d) Async PDU with AsyncEvent "Drop connection" (for 5276 this CID). 5277 e) Async PDU with AsyncEvent "Drop all connections". 5278 -target: One or more of the following events caused this 5279 transition: 5280 a) Internal event that indicates a transport connection 5281 timeout was received, thus prompting transport RESET 5282 or transport connection closure. 5283 b) An internal event of a failed connection/session 5284 reinstatement is received. 5285 c) A transport RESET. 5286 d) A transport disconnect indication. 5287 e) Internal emergency cleanup event was received which 5288 prompts an Async PDU with AsyncEvent "Drop 5289 connection" (for this CID), or event "Drop all 5290 connections". 5292 -T17: 5293 -initiator: One or more of the following events caused this 5294 transition: 5295 a) Logout response, (failure i.e., a non-zero status) 5296 was received, or Logout timed out. 5297 b) Any of the events specified for T15 and T16. 5298 -target: One or more of the following events caused this 5299 transition: 5301 a) Internal event that indicates a failure of the 5302 Logout processing was received, which prompts a 5303 Logout response (failure, i.e., a non-zero status) 5304 to be sent. 5305 b) Any of the events specified for T15 and T16. 5306 -T18: 5307 -initiator: An internal event of receiving a Logout 5308 response (success) on another connection for a "close the 5309 session" Logout request was received. 5311 -target: An internal event of sending a Logout response 5312 (success) on another connection for a "close the session" 5313 Logout request was received, or an internal event of a 5314 successful connection/session reinstatement is received. 5315 In both these cases, the connection is closed. 5317 The CLEANUP_WAIT state (S8) implies that there are possible iSCSI 5318 tasks that have not reached conclusion and are still considered 5319 busy. 5321 8.1.3. Standard Connection State Diagram for an Initiator 5323 Symbolic names for States: 5325 S1: FREE 5327 S2: XPT_WAIT 5329 S4: IN_LOGIN 5331 S5: LOGGED_IN 5333 S6: IN_LOGOUT 5335 S7: LOGOUT_REQUESTED 5337 S8: CLEANUP_WAIT 5339 States S5, S6, and S7 constitute the Full Feature Phase operation 5340 of the connection. 5342 The state diagram is as follows: 5344 -------<-------------+ 5345 +--------->/ S1 \<----+ | 5346 T13| +->\ /<-+ \ | 5347 | / ---+--- \ \ | 5348 | / | T2 \ | | 5349 | T8 | |T1 | | | 5350 | | | / |T7 | 5351 | | | / | | 5352 | | | / | | 5353 | | V / / | 5354 | | ------- / / | 5355 | | / S2 \ / | 5356 | | \ / / | 5357 | | ---+--- / | 5358 | | |T4 / | 5359 | | V / | T18 5360 | | ------- / | 5361 | | / S4 \ | 5362 | | \ / | 5363 | | ---+--- | T15 5364 | | |T5 +--------+---------+ 5365 | | | /T16+-----+------+ | 5366 | | | / -+-----+--+ | | 5367 | | | / / S7 \ |T12| | 5368 | | | / +->\ /<-+ V V 5369 | | | / / -+----- ------- 5370 | | | / /T11 |T10 / S8 \ 5371 | | V / / V +----+ \ / 5372 | | ---+-+- ----+-- | ------- 5373 | | / S5 \T9 / S6 \<+ ^ 5374 | +-----\ /--->\ / T14 | 5375 | ------- --+----+------+T17 5376 +---------------------------+ 5377 The following state transition table represents the above diagram. 5378 Each row represents the starting state for a given transition, 5379 which after taking a transition marked in a table cell would end 5380 in the state represented by the column of the cell. For example, 5381 from state S1, the connection takes the T1 transition to arrive at 5382 state S2. The fields marked "-" correspond to undefined 5383 transitions. 5385 +----+---+---+---+---+----+---+ 5386 |S1 |S2 |S4 |S5 |S6 |S7 |S8 | 5387 ---+----+---+---+---+---+----+---+ 5388 S1| - |T1 | - | - | - | - | - | 5389 ---+----+---+---+---+---+----+---+ 5390 S2|T2 |- |T4 | - | - | - | - | 5391 ---+----+---+---+---+---+----+---+ 5392 S4|T7 |- |- |T5 | - | - | - | 5393 ---+----+---+---+---+---+----+---+ 5394 S5|T8 |- |- | - |T9 |T11 |T15| 5395 ---+----+---+---+---+---+----+---+ 5396 S6|T13 |- |- | - |T14|- |T17| 5397 ---+----+---+---+---+---+----+---+ 5398 S7|T18 |- |- | - |T10|T12 |T16| 5399 ---+----+---+---+---+---+----+---+ 5400 S8| - |- |- | - | - | - | - | 5401 ---+----+---+---+---+---+----+---+ 5403 8.1.4. Standard Connection State Diagram for a Target 5405 Symbolic names for States: 5406 S1: FREE 5408 S3: XPT_UP 5410 S4: IN_LOGIN 5412 S5: LOGGED_IN 5414 S6: IN_LOGOUT 5416 S7: LOGOUT_REQUESTED 5418 S8: CLEANUP_WAIT 5420 States S5, S6, and S7 constitute the Full Feature Phase operation 5421 of the connection. 5423 The state diagram is as follows: 5425 -------<-------------+ 5426 +--------->/ S1 \<----+ | 5427 T13| +->\ /<-+ \ | 5428 | / ---+--- \ \ | 5429 | / | T6 \ | | 5430 | T8 | |T3 | | | 5431 | | | / |T7 | 5432 | | | / | | 5433 | | | / | | 5434 | | V / / | 5435 | | ------- / / | 5436 | | / S3 \ / | 5437 | | \ / / | T18 5438 | | ---+--- / | 5439 | | |T4 / | 5440 | | V / | 5441 | | ------- / | 5442 | | / S4 \ | 5443 | | \ / | 5444 | | ---+--- T15 | 5445 | | |T5 +--------+---------+ 5446 | | | /T16+-----+------+ | 5447 | | | / -+-----+---+ | | 5448 | | | / / S7 \ |T12| | 5449 | | | / +->\ /<-+ V V 5450 | | | / / -+----- ------- 5451 | | | / /T11 |T10 / S8 \ 5452 | | V / / V \ / 5453 | | ---+-+- ------- ------- 5454 | | / S5 \T9 / S6 \ ^ 5455 | +-----\ /--->\ / | 5456 | ------- --+----+--------+T17 5457 +---------------------------+ 5459 The following state transition table represents the above diagram, 5460 and follows the conventions described for the initiator diagram. 5462 +----+---+---+---+---+----+---+ 5463 |S1 |S3 |S4 |S5 |S6 |S7 |S8 | 5464 ---+----+---+---+---+---+----+---+ 5465 S1| - |T3 | - | - | - | - | - | 5466 ---+----+---+---+---+---+----+---+ 5467 S3|T6 |- |T4 | - | - | - | - | 5468 ---+----+---+---+---+---+----+---+ 5469 S4|T7 |- |- |T5 | - | - | - | 5470 ---+----+---+---+---+---+----+---+ 5471 S5|T8 |- |- | - |T9 |T11 |T15| 5472 ---+----+---+---+---+---+----+---+ 5473 S6|T13 |- |- | - |- |- |T17| 5474 ---+----+---+---+---+---+----+---+ 5475 S7|T18 |- |- | - |T10|T12 |T16| 5476 ---+----+---+---+---+---+----+---+ 5477 S8| - |- |- | - | - | - | - | 5478 ---+----+---+---+---+---+----+---+ 5480 8.2. Connection Cleanup State Diagram for Initiators and Targets 5482 Symbolic names for states: 5484 R1: CLEANUP_WAIT (same as S8) 5486 R2: IN_CLEANUP 5488 R3: FREE (same as S1) 5490 Whenever a connection state machine in cleanup (let's call it CSM- 5491 C) enters the CLEANUP_WAIT state (S8), it must go through the 5492 state transitions described in the connection cleanup state 5493 diagram either a) using a separate full-feature phase connection 5494 (let's call it CSM-E, for explicit) in the LOGGED_IN state in the 5495 same session, or b) using a new transport connection (let's call 5496 it CSM-I, for implicit) in the FREE state that is to be added to 5497 the same session. In the CSM-E case, an explicit logout for the 5498 CID that corresponds to CSM-C (either as a connection or session 5499 logout) needs to be performed to complete the cleanup. In the CSM- 5500 I case, an implicit logout for the CID that corresponds to CSM-C 5501 needs to be performed by way of connection reinstatement (Section 5502 6.3.4) for that CID. In either case, the protocol exchanges on 5503 CSM-E or CSM-I determine the state transitions for CSM-C. 5504 Therefore, this cleanup state diagram is only applicable to the 5505 instance of the connection in cleanup (i.e., CSM-C). In the case 5506 of an implicit logout for example, CSM-C reaches FREE (R3) at the 5507 time CSM-I reaches LOGGED_IN. In the case of an explicit logout, 5508 CSM-C reaches FREE (R3) when CSM-E receives a successful logout 5509 response while continuing to be in the LOGGED_IN state. 5511 An initiator must initiate an explicit or implicit connection 5512 logout for a connection in the CLEANUP_WAIT state, if the 5513 initiator intends to continue using the associated iSCSI session. 5515 The following state diagram applies to both initiators and 5516 targets. 5518 ------- 5519 / R1 \ 5520 +--\ /<-+ 5521 / ---+--- \ 5522 / | \ M3 5523 M1 | |M2 | 5524 | | / 5525 | | / 5526 | | / 5527 | V / 5528 | ------- / 5529 | / R2 \ 5530 | \ / 5531 | ------- 5532 | | 5533 | |M4 5534 | | 5535 | | 5536 | | 5537 | V 5538 | ------- 5539 | / R3 \ 5540 +---->\ / 5541 ------- 5543 The following state transition table represents the above diagram, 5544 and follows the same conventions as in earlier sections. 5546 +----+----+----+ 5547 |R1 |R2 |R3 | 5548 -----+----+----+----+ 5549 R1 | - |M2 |M1 | 5550 -----+----+----+----+ 5551 R2 |M3 | - |M4 | 5552 -----+----+----+----+ 5553 R3 | - | - | - | 5554 -----+----+----+----+ 5556 8.2.1. State Descriptions for Initiators and Targets 5558 -R1: CLEANUP_WAIT (Same as S8) 5559 -initiator: Waiting for the internal event to initiate the 5560 cleanup processing for CSM-C. 5561 -target: Waiting for the cleanup process to start for CSM- 5562 C. 5563 -R2: IN_CLEANUP 5564 -initiator: Waiting for the connection cleanup process to 5565 conclude for CSM-C. 5566 -target: Waiting for the connection cleanup process to 5567 conclude for CSM-C. 5568 -R3: FREE (Same as S1) 5569 -initiator: End state for CSM-C. 5570 -target: End state for CSM-C. 5572 8.2.2. State Transition Descriptions for Initiators and Targets 5574 -M1: One or more of the following events was received: 5575 -initiator: 5576 -An internal event that indicates connection state 5577 timeout. 5578 -An internal event of receiving a successful Logout 5579 response on a different connection for a "close the 5580 session" Logout. 5581 -target: 5582 -An internal event that indicates connection state 5583 timeout. 5584 -An internal event of sending a Logout response 5585 (success) on a different connection for a "close the 5586 session" Logout request. 5588 -M2: An implicit/explicit logout process was initiated by the 5589 initiator. 5590 -In CSM-I usage: 5591 -initiator: An internal event requesting the connection 5592 (or session) reinstatement was received, thus prompting 5593 a connection (or session) reinstatement Login to be 5594 sent transitioning CSM-I to state IN_LOGIN. 5595 -target: A connection/session reinstatement Login was 5596 received while in state XPT_UP. 5597 -In CSM-E usage: 5599 -initiator: An internal event that indicates that an 5600 explicit logout was sent for this CID in state 5601 LOGGED_IN. 5602 -target: An explicit logout was received for this CID 5603 in state LOGGED_IN. 5604 -M3: Logout failure detected 5605 -In CSM-I usage: 5606 -initiator: CSM-I failed to reach LOGGED_IN and arrived 5607 into FREE instead. 5608 -target: CSM-I failed to reach LOGGED_IN and arrived 5609 into FREE instead. 5610 -In CSM-E usage: 5611 -initiator: CSM-E either moved out of LOGGED_IN, or 5612 Logout timed out and/or aborted, or Logout response 5613 (failure) was received. 5614 -target: CSM-E either moved out of LOGGED_IN, Logout 5615 timed out and/or aborted, or an internal event that 5616 indicates a failed Logout processing was received. A 5617 Logout response (failure) was sent in the last case. 5619 -M4: Successful implicit/explicit logout was performed. 5620 - In CSM-I usage: 5621 -initiator: CSM-I reached state LOGGED_IN, or an 5622 internal event of receiving a Logout response (success) 5623 on another connection for a "close the session" Logout 5624 request was received. 5625 -target: CSM-I reached state LOGGED_IN, or an internal 5626 event of sending a Logout response (success) on a 5627 different connection for a "close the session" Logout 5628 request was received. 5629 - In CSM-E usage: 5630 -initiator: CSM-E stayed in LOGGED_IN and received a 5631 Logout response (success), or an internal event of 5632 receiving a Logout response (success) on another 5633 connection for a "close the session" Logout request was 5634 received. 5635 -target: CSM-E stayed in LOGGED_IN and an internal 5636 event indicating a successful Logout processing was 5637 received, or an internal event of sending a Logout 5638 response (success) on a different connection for a 5639 "close the session" Logout request was received. 5641 8.3. Session State Diagrams 5643 8.3.1. Session State Diagram for an Initiator 5645 Symbolic Names for States: 5647 Q1: FREE 5649 Q3: LOGGED_IN 5651 Q4: FAILED 5653 State Q3 represents the Full Feature Phase operation of the 5654 session. 5656 The state diagram is as follows: 5658 ------- 5659 / Q1 \ 5660 +------>\ /<-+ 5661 / ---+--- | 5662 / | |N3 5663 N6 | |N1 | 5664 | | | 5665 | N4 | | 5666 | +----------+ | / 5667 | | | | / 5668 | | | | / 5669 | | V V / 5670 -+--+-- -----+- 5671 / Q4 \ N5 / Q3 \ 5672 \ /<------\ / 5673 ------- ------- 5675 The state transition table is as follows: 5677 +---+---+---+ 5678 |Q1 |Q3 |Q4 | 5679 -----+---+---+---+ 5680 Q1 | - |N1 | - | 5681 -----+---+---+---+ 5682 Q3 |N3 | - |N5 | 5683 -----+---+---+---+ 5684 Q4 |N6 |N4 | - | 5685 -----+---+---+---+ 5687 8.3.2. Session State Diagram for a Target 5689 Symbolic Names for States: 5691 Q1: FREE 5693 Q2: ACTIVE 5695 Q3: LOGGED_IN 5697 Q4: FAILED 5699 Q5: IN_CONTINUE 5701 State Q3 represents the Full Feature Phase operation of the 5702 session. 5704 The state diagram is as follows: 5706 ------- 5707 +------------------>/ Q1 \ 5708 / +-------------->\ /<-+ 5709 | | ---+--- | 5710 | | ^ | |N3 5711 N 6 | |N11 N9| V N1 | 5712 | | +------ | 5713 | | / Q2 \ | 5714 | | \ / | 5715 | --+---- +--+--- | 5716 | / Q5 \ | | 5717 | \ / N10 | | 5718 | +-+---+------------+ | N2 / 5719 | ^ | | | / 5720 | N7| |N8 | | / 5721 | | | | V / 5722 -+---+-V V------+- 5723 / Q4 \ N5 / Q3 \ 5724 \ /<-------------\ / 5725 ------- ------- 5727 The state transition table is as follows: 5729 +----+----+----+----+----+ 5730 |Q1 |Q2 |Q3 |Q4 |Q5 | 5731 -----+----+----+----+----+----+ 5732 Q1 | - |N1 | - | - | - | 5733 -----+----+----+----+----+----+ 5734 Q2 |N9 | - |N2 | - | - | 5735 -----+----+----+----+----+----+ 5736 Q3 |N3 | - | - |N5 | - | 5737 -----+----+----+----+----+----+ 5738 Q4 |N6 | - | - | - |N7 | 5739 -----+----+----+----+----+----+ 5740 Q5 |N11 | - |N10 |N8 | - | 5741 -----+----+----+----+----+----+ 5743 8.3.3. State Descriptions for Initiators and Targets 5745 -Q1: FREE 5746 -initiator: State on instantiation or after cleanup. 5748 -target: State on instantiation or after cleanup. 5749 -Q2: ACTIVE 5750 -initiator: Illegal. 5751 -target: The first iSCSI connection in the session 5752 transitioned to IN_LOGIN, waiting for it to complete the 5753 login process. 5754 -Q3: LOGGED_IN 5755 -initiator: Waiting for all session events. 5756 -target: Waiting for all session events. 5757 -Q4: FAILED 5758 -initiator: Waiting for session recovery or session 5759 continuation. 5760 -target: Waiting for session recovery or session 5761 continuation. 5762 -Q5: IN_CONTINUE 5763 -initiator: Illegal. 5764 -target: Waiting for session continuation attempt to reach 5765 a conclusion. 5767 8.3.4. State Transition Descriptions for Initiators and Targets 5769 -N1: 5770 -initiator: At least one transport connection reached the 5771 LOGGED_IN state. 5772 -target: The first iSCSI connection in the session had 5773 reached the IN_LOGIN state. 5774 -N2: 5775 -initiator: Illegal. 5776 -target: At least one iSCSI connection reached the 5777 LOGGED_IN state. 5778 -N3: 5779 -initiator: Graceful closing of the session via session 5780 closure (Section 6.3.6). 5781 -target: Graceful closing of the session via session 5782 closure (Section 6.3.6) or a successful session 5783 reinstatement cleanly closed the session. 5784 -N4: 5785 -initiator: A session continuation attempt succeeded. 5786 -target: Illegal. 5787 -N5: 5789 -initiator: Session failure (Section 6.3.6) occurred. 5790 -target: Session failure (Section 6.3.6) occurred. 5791 -N6: 5792 -initiator: Session state timeout occurred, or a session 5793 reinstatement cleared this session instance. This results 5794 in the freeing of all associated resources and the session 5795 state is discarded. 5796 -target: Session state timeout occurred, or a session 5797 reinstatement cleared this session instance. This results 5798 in the freeing of all associated resources and the session 5799 state is discarded. 5800 -N7: 5801 -initiator: Illegal. 5802 -target: A session continuation attempt is initiated. 5803 -N8: 5804 -initiator: Illegal. 5805 -target: The last session continuation attempt failed. 5806 -N9: 5807 -initiator: Illegal. 5808 -target: Login attempt on the leading connection failed. 5809 -N10: 5810 -initiator: Illegal. 5811 -target: A session continuation attempt succeeded. 5812 -N11: 5813 -initiator: Illegal. 5814 -target: A successful session reinstatement cleanly closed 5815 the session. 5817 9. Security Considerations 5819 Historically, native storage systems have not had to consider 5820 security because their environments offered minimal security 5821 risks. That is, these environments consisted of storage devices 5822 either directly attached to hosts or connected via a Storage Area 5823 Network (SAN) distinctly separate from the communications network. 5824 The use of storage protocols, such as SCSI, over IP-networks 5825 requires that security concerns be addressed. iSCSI 5826 implementations must provide means of protection against active 5827 attacks (e.g., pretending to be another identity, message 5828 insertion, deletion, modification, and replaying) and passive 5829 attacks (e.g.,eavesdropping, gaining advantage by analyzing the 5830 data sent over the line). 5832 Although technically possible, iSCSI SHOULD NOT be configured 5833 without security. iSCSI configured without security should be 5834 confined, in extreme cases, to closed environments without any 5835 security risk. [RFC3723] specifies the mechanisms that must be 5836 used in order to mitigate risks fully described in that document. 5838 The following Section describes the security mechanisms provided 5839 by an iSCSI implementation. 5841 9.1. iSCSI Security Mechanisms 5843 The entities involved in iSCSI security are the initiator, target, 5844 and the IP communication end points. iSCSI scenarios in which 5845 multiple initiators or targets share a single communication end 5846 point are expected. To accommodate such scenarios, iSCSI uses two 5847 separate security mechanisms: In-band authentication between the 5848 initiator and the target at the iSCSI connection level (carried 5849 out by exchange of iSCSI Login PDUs), and packet protection 5850 (integrity, authentication, and confidentiality) by IPsec at the 5851 IP level. The two security mechanisms complement each other. The 5852 in-band authentication provides end-to-end trust (at login time) 5853 between the iSCSI initiator and the target while IPsec provides a 5854 secure channel between the IP communication end points. 5856 Further details on typical iSCSI scenarios and the relation 5857 between the initiators, targets, and the communication end points 5858 can be found in [RFC3723]. 5860 9.2. In-band Initiator-Target Authentication 5862 During login, the target MAY authenticate the initiator and the 5863 initiator MAY authenticate the target. The authentication is 5864 performed on every new iSCSI connection by an exchange of iSCSI 5865 Login PDUs using a negotiated authentication method. 5867 The authentication method cannot assume an underlying IPsec 5868 protection, because IPsec is optional to use. An attacker should 5869 gain as little advantage as possible by inspecting the 5870 authentication phase PDUs. Therefore, a method using clear text 5871 (or equivalent) passwords MUST NOT be used; on the other hand, 5872 identity protection is not strictly required. 5874 The authentication mechanism protects against an unauthorized 5875 login to storage resources by using a false identity (spoofing). 5876 Once the authentication phase is completed, if the underlying 5877 IPsec is not used, all PDUs are sent and received in clear. The 5878 authentication mechanism alone (without underlying IPsec) should 5879 only be used when there is no risk of eavesdropping, message 5880 insertion, deletion, modification, and replaying. 5882 Section 11 defines several authentication methods and the exact 5883 steps that must be followed in each of them, including the iSCSI- 5884 text-keys and their allowed values in each step. Whenever an iSCSI 5885 initiator gets a response whose keys, or their values, are not 5886 according to the step definition, it MUST abort the connection. 5887 Whenever an iSCSI target gets a response whose keys, or their 5888 values, are not according to the step definition, it MUST answer 5889 with a Login reject with the "Initiator Error" or "Missing 5890 Parameter" status. These statuses are not intended for 5891 cryptographically incorrect values such as the CHAP response, for 5892 which "Authentication Failure" status MUST be specified. The 5893 importance of this rule can be illustrated in CHAP with target 5894 authentication (see Section 12.1.3) where the initiator would have 5895 been able to conduct a reflection attack by omitting his response 5896 key (CHAP_R) using the same CHAP challenge as the target and 5897 reflecting the target's response back to the target. In CHAP, this 5898 is prevented because the target must answer the missing CHAP_R key 5899 with a Login reject with the "Missing Parameter" status. 5901 For some of the authentication methods, a key specifies the 5902 identity of the iSCSI initiator or target for authentication 5903 purposes. The value associated with that key MAY be different from 5904 the iSCSI name and SHOULD be configurable. (CHAP_N, see Section 5905 12.1.3 and SRP_U, see Section 12.1.2). 5907 9.2.1. CHAP Considerations 5909 Compliant iSCSI initiators and targets MUST implement the CHAP 5910 authentication method [RFC1994] (according to Section 12.1.3 5911 including the target authentication option). 5913 When CHAP is performed over a non-encrypted channel, it is 5914 vulnerable to an off-line dictionary attack. Implementations MUST 5915 support use of up to 128 bit random CHAP secrets, including the 5916 means to generate such secrets and to accept them from an external 5917 generation source. Implementations MUST NOT provide secret 5918 generation (or expansion) means other than random generation. 5920 An administrative entity of an environment in which CHAP is used 5921 with a secret that has less than 96 random bits MUST enforce IPsec 5922 encryption (according to the implementation requirements in 5923 Confidentiality) to protect the connection. Moreover, in this case 5924 IKE authentication with group pre-shared cryptographic keys SHOULD 5925 NOT be used unless it is not essential to protect group members 5926 against off-line dictionary attacks by other members. 5928 CHAP secrets MUST be an integral number of bytes (octets). A 5929 compliant implementation SHOULD NOT continue with the login step 5930 in which it should send a CHAP response (CHAP_R, Section 12.1.3) 5931 unless it can verify that the CHAP secret is at least 96 bits, or 5932 that IPsec encryption is being used to protect the connection. 5934 Any CHAP secret used for initiator authentication MUST NOT be 5935 configured for authentication of any target, and any CHAP secret 5936 used for target authentication MUST NOT be configured for 5937 authentication of any initiator. If the CHAP response received by 5938 one end of an iSCSI connection is the same as the CHAP response 5939 that the receiving endpoint would have generated for the same CHAP 5940 challenge, the response MUST be treated as an authentication 5941 failure and cause the connection to close (this ensures that the 5942 same CHAP secret is not used for authentication in both 5943 directions). Also, if an iSCSI implementation can function as 5944 both initiator and target, different CHAP secrets and identities 5945 MUST be configured for these two roles. The following is an 5946 example of the attacks prevented by the above requirements: 5948 a) Rogue wants to impersonate Storage to Alice, and knows 5949 that a single secret is used for both directions of 5950 Storage-Alice authentication. 5952 b) Rogue convinces Alice to open two connections to Rogue, 5953 and Rogue identifies itself as Storage on both 5954 connections. 5956 c) Rogue issues a CHAP challenge on connection 1, waits for 5957 Alice to respond, and then reflects Alice's challenge as 5958 the initial challenge to Alice on connection 2. 5960 d) If Alice doesn't check for the reflection across 5961 connections, Alice's response on connection 2 enables 5962 Rogue to impersonate Storage on connection 1, even though 5963 Rogue does not know the Alice-Storage CHAP secret. 5965 Originators MUST NOT reuse the CHAP challenge sent by the 5966 Responder for the other direction of a bidirectional 5967 authentication. Responders MUST check for this condition and close 5968 the iSCSI TCP connection if it occurs. 5970 The same CHAP secret SHOULD NOT be configured for authentication 5971 of multiple initiators or multiple targets, as this enables any of 5972 them to impersonate any other one of them, and compromising one of 5973 them enables the attacker to impersonate any of them. It is 5974 recommended that iSCSI implementations check for use of identical 5975 CHAP secrets by different peers when this check is feasible, and 5976 take appropriate measures to warn users and/or administrators when 5977 this is detected. 5979 When an iSCSI initiator or target authenticates itself to 5980 counterparts in multiple administrative domains, it SHOULD use a 5981 different CHAP secret for each administrative domain to avoid 5982 propagating security compromises across domains. 5984 Within a single administrative domain: 5985 - A single CHAP secret MAY be used for authentication of an 5986 initiator to multiple targets. 5988 - A single CHAP secret MAY be used for an authentication of a 5989 target to multiple initiators when the initiators use an 5990 external server (e.g., RADIUS) to verify the target's CHAP 5991 responses and do not know the target's CHAP secret. 5993 If an external response verification server (e.g., RADIUS) is not 5994 used, employing a single CHAP secret for authentication of a 5995 target to multiple initiators requires that all such initiators 5996 know that target secret. Any of these initiators can impersonate 5997 the target to any other such initiator, and compromise of such an 5998 initiator enables an attacker to impersonate the target to all 5999 such initiators. Targets SHOULD use separate CHAP secrets for 6000 authentication to each initiator when such risks are of concern; 6001 in this situation it may be useful to configure a separate logical 6002 iSCSI target with its own iSCSI Node Name for each initiator or 6003 group of initiators among which such separation is desired. 6005 9.2.2. SRP Considerations 6007 The strength of the SRP authentication method (specified in 6008 [RFC2945]) is dependent on the characteristics of the group being 6009 used (i.e., the prime modulus N and generator g). As described in 6010 [RFC2945], N is required to be a Sophie-German prime (of the form 6011 N = 2q + 1, where q is also prime) and the generator g is a 6012 primitive root of GF(n). In iSCSI authentication, the prime 6013 modulus N MUST be at least 768 bits. 6015 The list of allowed SRP groups is provided in [RFC3723]. 6017 9.3. IPsec 6019 iSCSI uses the IPsec mechanism for packet protection 6020 (cryptographic integrity, authentication, and confidentiality) at 6021 the IP level between the iSCSI communicating end points. The 6022 following sections describe the IPsec protocols that must be 6023 implemented for data integrity and authentication, 6024 confidentiality, and cryptographic key management. 6026 An iSCSI initiator or target may provide the required IPsec 6027 support fully integrated or in conjunction with an IPsec front-end 6028 device. In the latter case, the compliance requirements with 6029 regard to IPsec support apply to the "combined device". Only the 6030 "combined device" is to be considered an iSCSI device. 6032 Detailed considerations and recommendations for using IPsec for 6033 iSCSI are provided in [RFC3723]. 6035 This document updates RFC 3723 to add requirements for IPsec v3 6036 as specified in [RFC4301] and related RFCs. The IPsec v2 "MUST 6037 implement" requirements from [RFC3723] are left unchanged by this 6038 document; this document adds requirements that IPsec v3, as 6039 specified in [RFC4301] and related RFCs (e.g., IKEv2 [RFC5996]), 6040 SHOULD be implemented. The mandatory requirement for IPsec v2 6041 preserves interoperability with existing implementations, and the 6042 strong recommendation for IPsec v3 encourages implementers to move 6043 forward to that newer version of IPsec. 6045 9.3.1. Data Integrity and Authentication 6047 Data authentication and integrity is provided by a cryptographic 6048 keyed Message Authentication Code in every sent packet. This code 6049 protects against message insertion, deletion, and modification. 6050 Protection against message replay is realized by using a sequence 6051 counter. 6053 An iSCSI-compliant initiator or target MUST provide data integrity 6054 and authentication by implementing IPsec v2 [RFC2401] with ESPv2 6055 [RFC2406] in tunnel mode, SHOULD provide data integrity and 6056 authentication by implementing IPsec v3 [RFC4301] with ESPv3 6057 [RFC4303] in tunnel mode, and MAY provide data integrity and 6058 authentication by implementing either IPsec v2 or v3 with the 6060 appropriate version of ESP in transport mode. The IPsec 6061 implementation MUST fulfill the following iSCSI specific 6062 requirements: 6064 - HMAC-SHA1 MUST be implemented [RFC2404]. 6066 - AES CBC MAC with XCBC extensions SHOULD be implemented 6067 [RFC3566]. 6069 - Implementations that support IKEv2 [RFC5996] SHOULD also 6070 implement AES GMAC [RFC4543] 6072 The ESP anti-replay service MUST also be implemented. 6074 At the high speeds iSCSI is expected to operate, a single IPsec SA 6075 could rapidly cycle through the ESP 32-bit sequence number space. 6076 In view of this, an iSCSI implementation that is capable of 6077 operating at speeds of 1 Gbps and that implements both IKEv2 6078 [RFC5996] and ESPv3 [RFC4303] MUST also implement extended (64- 6079 bit) sequence numbers for ESPv3 and SHOULD use ESPv3 extended 6080 sequence numbers for all security associations that use ESPv3 to 6081 protect iSCSI connections. 6083 9.3.2. Confidentiality 6085 Confidentiality is provided by encrypting the data in every 6086 packet. When confidentiality is used it MUST be accompanied by 6087 data integrity and authentication to provide comprehensive 6088 protection against eavesdropping, message insertion, deletion, 6089 modification, and replaying. 6091 An iSCSI compliant initiator or target MUST provide 6092 confidentiality by implementing IPsec v2 [RFC2401] with ESPv2 6093 [RFC2406] in tunnel mode, SHOULD provide confidentiality by 6094 implementing IPsec v3 [RFC4301] with ESPv3 [RFC4303] in tunnel 6095 mode and MAY provide confidentiality by implementing either IPsec 6096 v2 or v3 with the appropriate version of ESP in transport mode, 6097 with the following iSCSI specific requirements that apply to IPsec 6098 v2 and IPsec v3: 6099 - 3DES in CBC mode MUST be implemented [RFC2451]. 6101 - AES in Counter mode SHOULD be implemented [RFC3686]. 6103 - Implementations that support IKEv2 [RFC5996] SHOULD also 6104 implement AES GCM [RFC4106] 6106 DES in CBC mode MUST NOT be used due to its inherent weakness. 6108 The NULL encryption algorithm MUST also be implemented. 6110 9.3.3. Policy, Security Associations, and Cryptographic Key 6111 Management 6113 A compliant iSCSI implementation MUST meet the cryptographic key 6114 management requirements of the IPsec protocol suite. 6115 Authentication, security association negotiation, and 6116 cryptographic key management MUST be provided by implementing IKE 6117 [RFC2409] using the IPsec DOI [RFC2407], and SHOULD be provided by 6118 implementing IKEv2 [RFC5996], with the following iSCSI-specific 6119 requirements: 6121 a) Peer authentication using a pre-shared cryptographic key MUST 6122 be supported. Certificate-based peer authentication using 6123 digital signatures MAY be supported. For IKEv1 ([RFC2409]), 6124 peer authentication using the public key encryption methods 6125 outlined in IKE sections 5.2 and 5.3 of [RFC2409] SHOULD NOT 6126 be used. 6127 b) When digital signatures are used to achieve authentication, 6128 an IKE negotiator SHOULD use IKE Certificate Request 6129 Payload(s) to specify the certificate authority. IKE 6130 negotiators SHOULD check the pertinent Certificate Revocation 6131 List (CRL) before accepting a PKI certificate for use in IKE 6132 authentication procedures. 6133 c) Conformant iSCSI implementations of IKEv1 MUST support Main 6134 Mode and SHOULD support Aggressive Mode. Main Mode with pre- 6135 shared key authentication method SHOULD NOT be used when 6136 either the initiator or the target uses dynamically assigned 6137 addresses. While in many cases pre-shared keys offer good 6138 security, situations in which dynamically assigned addresses 6139 are used force the use of a group pre-shared key, which 6140 creates vulnerability to a man-in-the-middle attack. 6142 d) In the IKEv1 Phase 2 Quick Mode, exchanges for creating the 6143 Phase 2 SA, the Identification Payload MUST be present. 6144 e) The following identification type requirements apply to 6145 IKEv1. ID_IPV4_ADDR, ID_IPV6_ADDR (if the protocol stack 6146 supports IPv6) and ID_FQDN Identification Types MUST be 6147 supported; ID_USER_FQDN SHOULD be supported. The IP Subnet, 6148 IP Address Range, ID_DER_ASN1_DN, and ID_DER_ASN1_GN 6149 Identification Types SHOULD NOT be used. The ID_KEY_ID 6150 Identification Type MUST NOT be used. 6151 f) If IKEv2 is supported, the following identification 6152 requirements apply. ID_IPV4_ADDR, ID_IPV6_ADDR (if the 6153 protocol stack supports IPv6) and ID_FQDN Identification 6154 Types MUST be supported; ID_RFC822_ADDR SHOULD be supported. 6155 The ID_DER_ASN1_DN, and ID_DER_ASN1_GN Identification Types 6156 SHOULD NOT be used. The ID_KEY_ID Identification Type MUST 6157 NOT be used. 6159 Manual cryptographic keying MUST NOT be used because it does not 6160 provide the necessary re-keying support. 6162 When DH groups are used, a DH group of at least 2048 bits SHOULD 6163 be offered as a part of all proposals to create IPsec Security 6164 Associations to protect iSCSI traffic. 6166 When IPsec is used, the receipt of an IKEv1 Phase 2 delete message 6167 or an IKEv2 INFORMATIONAL exchange that deletes the SA SHOULD NOT 6168 be interpreted as a reason for tearing down the iSCSI TCP 6169 connection. If additional traffic is sent on it, a new IKE SA will 6170 be created to protect it. 6172 The method used by the initiator to determine whether the target 6173 should be connected using IPsec is regarded as an issue of IPsec 6174 policy administration, and thus not defined in the iSCSI standard. 6176 The method used by an initiator that supports both IPsec v2 and v3 6177 to determine which versions of IPsec are supported by the target 6178 is also regarded as an issue of IPsec policy administration, and 6179 thus not defined in the iSCSI standard. If both IPsec v2 and v3 6180 are supported by both the initiator and target, use of IPsec v3 is 6181 recommended. 6183 If an iSCSI target is discovered via a SendTargets request in a 6184 discovery session not using IPsec, the initiator should assume 6185 that it does not need IPsec to establish a session to that target. 6186 If an iSCSI target is discovered using a discovery session that 6187 does use IPsec, the initiator SHOULD use IPsec when establishing a 6188 session to that target. 6190 9.4. Security Considerations for the X#NodeArchitecture Key 6192 The security considerations in this Section are specific to the 6193 X#NodeArchitecture discussed in Section 13.26. 6195 This extension key transmits specific implementation details about 6196 the node that sends it; such details may be considered sensitive 6197 in some environments. For example, if a certain software or 6198 firmware version is known to contain security weaknesses, 6199 announcing the presence of that version via this key may not be 6200 desirable. The countermeasures for this security concern are: 6202 a) sending less detailed information in the key values, 6203 b) not sending the extension key, or 6204 c) using IPsec ([RFC4303]) to provide confidentiality for the 6205 iSCSI connection on which the key is sent 6206 To support the first and second countermeasures, all 6207 implementations of this extension key MUST provide an 6208 administrative mechanism to disable sending the key. In addition, 6209 all implementations SHOULD provide an administrative mechanism to 6210 configure a verbosity level of the key value, thereby controlling 6211 the amount of information sent. 6213 For example, a lower verbosity might enable transmission of node 6214 architecture component names only, but no version numbers. The 6215 choice of which countermeasure is most appropriate depends on the 6216 environment. However, sending less detailed information in the key 6217 values may be an acceptable countermeasure in many environments, 6218 since it provides a compromise between sending too much 6219 information and the other more complete countermeasures of not 6220 sending the key at all or using IPsec. 6222 In addition to security considerations involving transmission of 6223 the key contents, any logging method(s) used for the key values 6224 MUST keep the information secure from intruders. For all 6225 implementations, the requirements to address this security concern 6226 are: 6228 a) Display of the log MUST only be possible with administrative 6229 rights to the node. 6230 b) Options to disable logging to disk and to keep logs for a 6231 fixed duration SHOULD be provided. 6233 Finally, it is important to note that different nodes may have 6234 different levels of risk, and these differences may affect the 6235 implementation. The components of risk include assets, threats, 6236 and vulnerabilities. Consider the following example iSCSI nodes, 6237 which demonstrate differences in assets and vulnerabilities of the 6238 nodes, and as a result, differences in implementation: 6240 a) One iSCSI target based on a special-purpose operating 6241 system: Since the iSCSI target controls access to the 6242 data storage containing company assets, the asset level 6243 is seen as very high. Also, because of the special- 6244 purpose operating system, in which vulnerabilities are 6245 less well-known, the vulnerability level is viewed as 6246 low. 6248 b) Multiple iSCSI initiators in a blade farm, each running a 6249 general purpose operating system: The asset level of each 6250 node is viewed as low, since blades are replaceable and 6251 low cost. However, the vulnerability level is viewed as 6252 high, since there may be many well-known vulnerabilities 6253 to that general-purpose operating system. For this 6254 target, an appropriate implementation might be logging of 6255 received key values, but no transmission of the key. For 6256 this initiator, an appropriate implementation might be 6257 transmission of the key, but no logging of received key 6258 values. 6260 10. Notes to Implementers 6262 This Section notes some of the performance and reliability 6263 considerations of the iSCSI protocol. This protocol was designed 6264 to allow efficient silicon and software implementations. The iSCSI 6265 task tag mechanism was designed to enable Direct Data Placement 6266 (DDP - a DMA form) at the iSCSI level or lower. 6268 The guiding assumption made throughout the design of this protocol 6269 is that targets are resource constrained relative to initiators. 6271 Implementers are also advised to consider the implementation 6272 consequences of the iSCSI to SCSI mapping model as outlined in 6273 Section 4.4.3. 6275 10.1. Multiple Network Adapters 6277 The iSCSI protocol allows multiple connections, not all of which 6278 need to go over the same network adapter. If multiple network 6279 connections are to be utilized with hardware support, the iSCSI 6280 protocol command-data-status allegiance to one TCP connection 6281 ensures that there is no need to replicate information across 6282 network adapters or otherwise require them to cooperate. 6284 However, some task management commands may require some loose form 6285 of cooperation or replication at least on the target. 6287 10.1.1. Conservative Reuse of ISIDs 6289 Historically, the SCSI model (and implementations and applications 6290 based on that model) has assumed that SCSI ports are static, 6291 physical entities. Recent extensions to the SCSI model have taken 6292 advantage of persistent worldwide unique names for these ports. In 6293 iSCSI however, the SCSI initiator ports are the endpoints of 6294 dynamically created sessions, so the presumptions of "static and 6295 physical" do not apply. In any case, the model clauses 6296 (particularly, Section 4.4.1) provide for persistent, reusable 6297 names for the iSCSI-type SCSI initiator ports even though there 6298 does not need to be any physical entity bound to these names. 6300 To both minimize the disruption of legacy applications and to 6301 better facilitate the SCSI features that rely on persistent names 6302 for SCSI ports, iSCSI implementations SHOULD attempt to provide a 6303 stable presentation of SCSI Initiator Ports (both to the upper OS- 6304 layers and to the targets to which they connect). This can be 6305 achieved in an initiator implementation by conservatively reusing 6306 ISIDs. In other words, the same ISID should be used in the Login 6307 process to multiple target portal groups (of the same iSCSI Target 6308 or different iSCSI Targets). The ISID RULE (Section 4.4.3) only 6309 prohibits reuse to the same target portal group. It does not 6310 "preclude" reuse to other target portal groups. 6311 The principle of conservative reuse "encourages" reuse to other 6312 target portal groups. When a SCSI target device sees the same 6313 (InitiatorName, ISID) pair in different sessions to different 6314 target portal groups, it can identify the underlying SCSI 6315 Initiator Port on each session as the same SCSI port. In effect, 6316 it can recognize multiple paths from the same source. 6318 10.1.2. iSCSI Name, ISID, and TPGT Use 6320 The designers of the iSCSI protocol are aware that legacy SCSI 6321 transports rely on initiator identity to assign access to storage 6322 resources. Although newer techniques are available and simplify 6323 access control, support for configuration and authentication 6324 schemes that are based on initiator identity is deemed important 6325 in order to support legacy systems and administration software. 6326 iSCSI thus supports the notion that it should be possible to 6327 assign access to storage resources based on "initiator device" 6328 identity. 6330 When there are multiple hardware or software components 6331 coordinated as a single iSCSI Node, there must be some (logical) 6332 entity that represents the iSCSI Node that makes the iSCSI Node 6333 Name available to all components involved in session creation and 6334 login. Similarly, this entity that represents the iSCSI Node must 6335 be able to coordinate session identifier resources (ISID for 6336 initiators) to enforce both the ISID and TSIH RULES (see Section 6337 4.4.3). 6339 For targets, because of the closed environment, implementation of 6340 this entity should be straightforward. However, vendors of iSCSI 6341 hardware (e.g., NICs or HBAs) intended for targets, SHOULD provide 6342 mechanisms for configuration of the iSCSI Node Name across the 6343 portal groups instantiated by multiple instances of these 6344 components within a target. 6346 However, complex targets making use of multiple Target Portal 6347 Group Tags may reconfigure them to achieve various quality goals. 6348 The initiators have two mechanisms at their disposal to discover 6349 and/or check reconfiguring targets - the discovery session type 6350 and a key returned by the target during login to confirm the TPGT. 6351 An initiator should attempt to "rediscover" the target 6352 configuration anytime a session is terminated unexpectedly. 6354 For initiators, in the long term, it is expected that operating 6355 system vendors will take on the role of this entity and provide 6356 standard APIs that can inform components of their iSCSI Node Name 6357 and can configure and/or coordinate ISID allocation, use, and 6358 reuse. 6360 Recognizing that such initiator APIs are not available today, 6361 other implementations of the role of this entity are possible. For 6362 example, a human may instantiate the (common) Node name as part of 6363 the installation process of each iSCSI component involved in 6364 session creation and login. This may be done either by pointing 6365 the component to a vendor-specific location for this datum or to a 6366 system-wide location. The structure of the ISID namespace (see 6367 Section 11.12.5 and [RFC3721]) facilitates implementation of the 6368 ISID coordination by allowing each component vendor to 6369 independently (of other vendor's components) coordinate 6370 allocation, use, and reuse of its own partition of the ISID 6371 namespace in a vendor-specific manner. Partitioning of the ISID 6372 namespace within initiator portal groups managed by that vendor 6373 allows each such initiator portal group to act independently of 6374 all other portal groups when selecting an ISID for a login; this 6375 facilitates enforcement of the ISID RULE (see Section 4.4.3) at 6376 the initiator. 6378 A vendor of iSCSI hardware (e.g., NICs or HBAs) intended for use 6379 in initiators MUST implement a mechanism for configuring the iSCSI 6380 Node Name. Vendors, and administrators must ensure that iSCSI Node 6381 Names are unique worldwide. It is therefore important that when 6382 one chooses to reuse the iSCSI Node Name of a disabled unit, not 6383 to re-assign that name to the original unit unless its worldwide 6384 uniqueness can be ascertained again. 6386 In addition, a vendor of iSCSI hardware must implement a mechanism 6387 to configure and/or coordinate ISIDs for all sessions managed by 6388 multiple instances of that hardware within a given iSCSI Node. 6389 Such configuration might be either permanently pre-assigned at the 6390 factory (in a necessarily globally unique way), statically 6391 assigned (e.g., partitioned across all the NICs at initialization 6392 in a locally unique way), or dynamically assigned (e.g., on-line 6393 allocator, also in a locally unique way). In the latter two cases, 6394 the configuration may be via public APIs (perhaps driven by an 6395 independent vendor's software, such as the OS vendor) or via 6396 private APIs driven by the vendor's own software. 6398 The process of name assignment and coordination has to be as 6399 encompassing and automated as possible as years of legacy usage 6400 have shown it to be highly error-prone. It is to be mentioned 6401 that SCSI has today alternative schemes of access control that can 6402 be used by all transports and their security is not dependent on 6403 strict naming coordination. 6405 10.2. Autosense and Auto Contingent Allegiance (ACA) 6407 Autosense refers to the automatic return of sense data to the 6408 initiator in case a command did not complete successfully. iSCSI 6409 initiators and targets MUST support and use autosense. 6411 ACA helps preserve ordered command execution in the presence of 6412 errors. As there can be many commands in-flight between an 6413 initiator and a target, SCSI initiator functionality in some 6414 operating systems depends on ACA to enforce ordered command 6415 execution during error recovery, and hence iSCSI initiator 6416 implementations for those operating systems need to support ACA. 6417 In order to support error recovery for these operating systems and 6418 iSCSI initiators, iSCSI targets SHOULD support ACA. 6420 10.3. iSCSI Timeouts 6422 iSCSI recovery actions are often dependent on iSCSI time-outs 6423 being recognized and acted upon before SCSI time-outs. Determining 6424 the right time-outs to use for various iSCSI actions (command 6425 acknowledgements expected, status acknowledgements, etc.) is very 6426 much dependent on infrastructure (hardware, links, TCP/IP stack, 6427 iSCSI driver). As a guide, the implementer may use an average Nop- 6428 Out/Nop-In turnaround delay multiplied by a "safety factor" (e.g., 6429 4) as a good estimate for the basic delay of the iSCSI stack for a 6430 given connection. The safety factor should account for the network 6431 load variability. For connection teardown the implementer may 6432 want to consider also TCP common practice for the given 6433 infrastructure. 6435 Text negotiations MAY also be subject to either time-limits or 6436 limits in the number of exchanges. Those SHOULD be generous enough 6437 to avoid affecting interoperability (e.g., allowing each key to be 6438 negotiated on a separate exchange). 6440 The relation between iSCSI timeouts and SCSI timeouts should also 6441 be considered. SCSI timeouts should be longer than iSCSI timeouts 6442 plus the time required for iSCSI recovery whenever iSCSI recovery 6443 is planned. Alternatively, an implementer may choose to interlock 6444 iSCSI timeouts and recovery with SCSI timeouts so that SCSI 6445 recovery will become active only where iSCSI is not planned to, or 6446 failed to, recover. 6448 The implementer may also want to consider the interaction between 6449 various iSCSI exception events - such as a digest failure - and 6450 subsequent timeouts. When iSCSI error recovery is active, a digest 6451 failure is likely to result in discovering a missing command or 6452 data PDU. In these cases, an implementer may want to lower the 6453 timeout values to enable faster initiation for recovery 6454 procedures. 6456 10.4. Command Retry and Cleaning Old Command Instances 6458 To avoid having old, retried command instances appear in a valid 6459 command window after a command sequence number wrap around, the 6460 protocol requires (see Section 4.2.2.1) that on every connection 6461 on which a retry has been issued, a non-immediate command be 6462 issued and acknowledged within a 2**31-1 commands interval from 6463 the CmdSN of the retried command. This requirement can be 6464 fulfilled by an implementation in several ways. 6466 The simplest technique to use is to send a (non-retry) non- 6467 immediate SCSI command (or a NOP if no SCSI command is available 6468 for a while) after every command retry on the connection on which 6469 the retry was attempted. As errors are deemed rare events, this 6470 technique is probably the most effective, as it does not involve 6471 additional checks at the initiator when issuing commands. 6473 10.5. Synch and Steering Layer and Performance 6475 While a synch and steering layer is optional, an initiator/target 6476 that does not have it working against a target/initiator that 6477 demands synch and steering may experience performance degradation 6478 caused by packet reordering and loss. Providing a synch and 6479 steering mechanism is recommended for all high-speed 6480 implementations. 6482 10.6. Considerations for State-dependent Devices and Long-lasting 6483 SCSI Operations 6485 Sequential access devices operate on the principle that the 6486 position of the device is based on the last command processed. As 6487 such, command processing order and knowledge of whether or not the 6488 previous command was processed is of the utmost importance to 6489 maintain data integrity. For example, inadvertent retries of SCSI 6490 commands when it is not known if the previous SCSI command was 6491 processed is a potential data integrity risk. 6493 For a sequential access device, consider the scenario in which a 6494 SCSI SPACE command to backspace one filemark is issued and then 6495 re-issued due to no status received for the command. If the first 6496 SPACE command was actually processed, the re-issued SPACE command, 6497 if processed, will cause the position to change. Thus, a 6498 subsequent write operation will write data to the wrong position 6499 and any previous data at that position will be overwritten. 6501 For a medium changer device, consider the scenario in which an 6502 EXCHANGE MEDIUM command (the SOURCE ADDRESS and DESTINATION 6503 ADDRESS are the same thus performing a swap) is issued and then 6504 re-issued due to no status received for the command. If the first 6505 EXCHANGE MEDIUM command was actually processed, the re-issued 6506 EXCHANGE MEDIUM command, if processed, will perform the swap 6507 again. The net effect is no swap was performed thus leaving a data 6508 integrity exposure. 6510 All commands that change the state of the device (as in SPACE 6511 commands for sequential access devices, and EXCHANGE MEDIUM for 6512 medium changer device), MUST be issued as non-immediate commands 6513 for deterministic and in order delivery to iSCSI targets. 6515 For many of those state changing commands, the execution model 6516 also assumes that the command is executed exactly once. Devices 6517 implementing READ POSITION and LOCATE provide a means for SCSI 6518 level command recovery and new tape-class devices should support 6519 those commands. In their absence a retry at SCSI level is 6520 difficult and error recovery at iSCSI level is advisable. 6522 Devices operating on long latency delivery subsystems and 6523 performing long lasting SCSI operations may need mechanisms that 6524 enable connection replacement while commands are running (e.g., 6525 during an extended copy operation). 6527 10.6.1. Determining the Proper ErrorRecoveryLevel 6529 The implementation and use of a specific ErrorRecoveryLevel should 6530 be determined based on the deployment scenarios of a given iSCSI 6531 implementation. Generally, the following factors must be 6532 considered before deciding on the proper level of recovery: 6534 a) Application resilience to I/O failures. 6535 b) Required level of availability in the face of transport 6536 connection failures. 6537 c) Probability of transport layer "checksum escape". This in 6538 turn decides the iSCSI digest failure frequency, and thus 6539 the criticality of iSCSI-level error recovery. The 6540 details of estimating this probability are outside the 6541 scope of this document. 6543 A consideration of the above factors for SCSI tape devices as an 6544 example suggests that implementations SHOULD use 6545 ErrorRecoveryLevel=1 when transport connection failure is not a 6546 concern and SCSI level recovery is unavailable, and 6547 ErrorRecoveryLevel=2 when the connection failure is also of high 6548 likelihood during a backup/retrieval. 6550 For extended copy operations, implementations SHOULD use 6551 ErrorRecoveryLevel=2 whenever there is a relatively high 6552 likelihood of connection failure. 6554 10.7. Multi-task Abort Implementation Considerations 6556 Multi-task abort operations are typically issued in emergencies - 6557 such as clearing a device lock-up, HA failover/failback etc. In 6558 these circumstances, it is desirable to rapidly go through the 6559 error handling process as opposed to the target waiting on 6560 multiple third-party initiators who may not even be functional 6561 anymore - especially if this emergency is triggered because of one 6562 such initiator failure. Therefore, both iSCSI target and 6563 initiator implementations SHOULD support FastAbort multi-task 6564 abort semantics (Section 4.2.3.4). 6566 Note that both in standard semantics (Section 4.2.3.3) and 6567 FastAbort semantics (Section 4.2.3.4), there may be outstanding 6568 data transfers even after the TMF completion is reported on the 6569 issuing session. In the case of iSCSI/iSER [iSER], these would be 6570 tagged data transfers for STags not owned by any active tasks. 6571 Whether or not real buffers support these data transfers is 6572 implementation-dependent. However, the data transfers logically 6573 MUST be silently discarded by the target iSCSI layer in all cases. 6574 A target MAY, on an implementation-defined internal timeout, also 6575 choose to drop the connections on which it did not receive the 6576 expected Data-Out sequences (Section 4.2.3.3) or NOP-Out 6577 acknowledgements (Section 4.2.3.4) so as to reclaim the associated 6578 buffer, STag, and TTT resources as appropriate. 6580 11. iSCSI PDU Formats 6582 All multi-byte integers that are specified in formats defined in 6583 this document are to be represented in network byte order (i.e., 6584 big endian). Any field that appears in this document assumes that 6585 the most significant byte is the lowest numbered byte and the most 6586 significant bit (within byte or field) is the lowest numbered bit 6587 unless specified otherwise. 6589 Any compliant sender MUST set all bits not defined and all 6590 reserved fields to zero unless specified otherwise. Any compliant 6591 receiver MUST ignore any bit not defined and all reserved fields 6592 unless specified otherwise. Receipt of reserved code values in 6593 defined fields MUST be reported as a protocol error. 6595 Reserved fields are marked by the word "reserved", some 6596 abbreviation of "reserved", or by "." for individual bits when no 6597 other form of marking is technically feasible. 6599 11.1. iSCSI PDU Length and Padding 6601 iSCSI PDUs are padded to the closest integer number of four byte 6602 words. The padding bytes SHOULD be sent as 0. 6604 11.2. PDU Template, Header, and Opcodes 6606 All iSCSI PDUs have one or more header segments and, optionally, a 6607 data segment. After the entire header segment group a header- 6608 digest MAY follow. The data segment MAY also be followed by a 6609 data-digest. 6611 The Basic Header Segment (BHS) is the first segment in all of the 6612 iSCSI PDUs. The BHS is a fixed-length 48-byte header segment. It 6613 MAY be followed by Additional Header Segments (AHS), a Header- 6614 Digest, a Data Segment, and/or a Data-Digest. 6616 The overall structure of an iSCSI PDU is as follows: 6618 Byte/ 0 | 1 | 2 | 3 | 6619 / | | | | 6620 |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| 6621 +---------------+---------------+---------------+--------------+ 6622 0/ Basic Header Segment (BHS) / 6623 +/ / 6624 +---------------+---------------+---------------+--------------+ 6625 48/ Additional Header Segment 1 (AHS) (optional) / 6626 +/ / 6627 +---------------+---------------+---------------+--------------+ 6628 / Additional Header Segment 2 (AHS) (optional) / 6629 +/ / 6630 +---------------+---------------+---------------+--------------+ 6631 +---------------+---------------+---------------+--------------+ 6632 / Additional Header Segment n (AHS) (optional) / 6633 +/ / 6634 +---------------+---------------+---------------+--------------+ 6635 k/ Header-Digest (optional) / 6636 +/ / 6637 +---------------+---------------+---------------+--------------+ 6638 l/ Data Segment(optional) / 6639 +/ / 6640 +---------------+---------------+---------------+--------------+ 6641 m/ Data-Digest (optional) / 6642 +/ / 6643 +---------------+---------------+---------------+--------------+ 6645 All PDU segments and digests are padded to the closest integer 6646 number of four byte words. For example, all PDU segments and 6647 digests start at a four byte word boundary and the padding ranges 6648 from 0 to 3 bytes. The padding bytes SHOULD be sent as 0. 6650 iSCSI response PDUs do not have AH Segments. 6652 11.2.1. Basic Header Segment (BHS) 6654 The BHS is 48 bytes long. The Opcode and DataSegmentLength fields 6655 appear in all iSCSI PDUs. In addition, when used, the Initiator 6656 Task Tag and Logical Unit Number always appear in the same 6657 location in the header. 6659 The format of the BHS is: 6661 Byte/ 0 | 1 | 2 | 3 | 6662 / | | | | 6663 |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| 6664 +---------------+---------------+---------------+--------------+ 6665 0|.|I| Opcode |F| Opcode-specific fields | 6666 +---------------+---------------+---------------+--------------+ 6667 4|TotalAHSLength | DataSegmentLength | 6668 +---------------+---------------+---------------+--------------+ 6669 8| LUN or Opcode-specific fields | 6670 + + 6671 12| | 6672 +---------------+---------------+---------------+--------------+ 6673 16| Initiator Task Tag | 6674 +---------------+---------------+---------------+--------------+ 6675 20/ Opcode-specific fields / 6676 +/ / 6677 +---------------+---------------+---------------+--------------+ 6678 48 6680 11.2.1.1. I 6682 For request PDUs, the I bit set to 1 is an immediate delivery 6683 marker. 6685 11.2.1.2. Opcode 6687 The Opcode indicates the type of iSCSI PDU the header 6688 encapsulates. 6690 The Opcodes are divided into two categories: initiator opcodes and 6691 target opcodes. Initiator opcodes are in PDUs sent by the 6692 initiator (request PDUs). Target opcodes are in PDUs sent by the 6693 target (response PDUs). 6695 Initiators MUST NOT use target opcodes and targets MUST NOT use 6696 initiator opcodes. 6698 Initiator opcodes defined in this specification are: 6700 0x00 NOP-Out 6702 0x01 SCSI Command (encapsulates a SCSI Command Descriptor 6703 Block) 6705 0x02 SCSI Task Management function request 6707 0x03 Login Request 6709 0x04 Text Request 6711 0x05 SCSI Data-out (for WRITE operations) 6713 0x06 Logout Request 6715 0x10 SNACK Request 6717 0x1c-0x1e Vendor specific codes 6719 Target opcodes are: 6721 0x20 NOP-In 6723 0x21 SCSI Response - contains SCSI status and possibly sense 6724 information or other response information. 6726 0x22 SCSI Task Management function response 6728 0x23 Login Response 6730 0x24 Text Response 6732 0x25 SCSI Data-in - for READ operations. 6734 0x26 Logout Response 6736 0x31 Ready To Transfer (R2T) - sent by target when it is ready 6737 to receive data. 6739 0x32 Asynchronous Message - sent by target to indicate certain 6740 special conditions. 6742 0x3c-0x3e Vendor specific codes 6744 0x3f Reject 6746 All other opcodes are reserved. 6748 11.2.1.3. Final (F) bit 6750 When set to 1 it indicates the final (or only) PDU of a sequence. 6752 11.2.1.4. Opcode-specific Fields 6754 These fields have different meanings for different opcode types. 6756 11.2.1.5. TotalAHSLength 6758 Total length of all AHS header segments in units of four byte 6759 words including padding, if any. 6761 The TotalAHSLength is only used in PDUs that have an AHS and MUST 6762 be 0 in all other PDUs. 6764 11.2.1.6. DataSegmentLength 6766 This is the data segment payload length in bytes (excluding 6767 padding). The DataSegmentLength MUST be 0 whenever the PDU has no 6768 data segment. 6770 11.2.1.7. LUN 6772 Some opcodes operate on a specific Logical Unit. The Logical Unit 6773 Number (LUN) field identifies which Logical Unit. If the opcode 6774 does not relate to a Logical Unit, this field is either ignored or 6775 may be used in an opcode specific way. The LUN field is 64-bits 6776 and should be formatted in accordance with [SAM2]. For example, 6777 LUN[0] from [SAM2] is BHS byte 8 and so on up to LUN[7] from 6778 [SAM2], which is BHS byte 15. 6780 11.2.1.8. Initiator Task Tag 6782 The initiator assigns a Task Tag to each iSCSI task it issues. 6783 While a task exists, this tag MUST uniquely identify the task 6784 session-wide. SCSI may also use the initiator task tag as part of 6785 the SCSI task identifier when the timespan during which an iSCSI 6786 initiator task tag must be unique extends over the timespan during 6787 which a SCSI task tag must be unique. However, the iSCSI Initiator 6788 Task Tag must exist and be unique even for untagged SCSI commands. 6790 An ITT value of 0xffffffff is reserved and MUST NOT be assigned 6791 for a task by the initiator. The only instance in which it may be 6792 seen on the wire is in a target-initiated NOP-In PDU (Section 6793 11.19) and in the initiator response to that PDU, if necessary. 6795 11.2.2. Additional Header Segment (AHS) 6797 The general format of an AHS is: 6799 Byte/ 0 | 1 | 2 | 3 | 6800 / | | | | 6801 |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| 6802 +---------------+---------------+---------------+--------------+ 6803 0| AHSLength | AHSType | AHS-Specific | 6804 +---------------+---------------+---------------+--------------+ 6805 4/ AHS-Specific / 6806 +/ / 6807 +---------------+---------------+---------------+--------------+ 6808 x 6810 11.2.2.1. AHSType 6812 The AHSType field is coded as follows: 6814 bit 0-1 - Reserved 6816 bit 2-7 - AHS code 6818 0 - Reserved 6820 1 - Extended CDB 6821 2 - Expected Bidirectional Read Data Length 6823 3 - 63 Reserved 6825 11.2.2.2. AHSLength 6827 This field contains the effective length in bytes of the AHS 6828 excluding AHSType and AHSLength and padding, if any. The AHS is 6829 padded to the smallest integer number of 4 byte words (i.e., from 6830 0 up to 3 padding bytes). 6832 11.2.2.3. Extended CDB AHS 6834 The format of the Extended CDB AHS is: 6836 Byte/ 0 | 1 | 2 | 3 | 6837 / | | | | 6838 |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| 6839 +---------------+---------------+---------------+--------------+ 6840 0| AHSLength (CDBLength-15) | 0x01 | Reserved | 6841 +---------------+---------------+---------------+--------------+ 6842 4/ ExtendedCDB...+padding / 6843 +/ / 6844 +---------------+---------------+---------------+--------------+ 6845 x 6847 This type of AHS MUST NOT be used if the CDBLength is less than 6848 17. 6849 The length includes the reserved byte 3. 6851 11.2.2.4. Bidirectional Expected Read-Data Length AHS 6853 The format of the Bidirectional Read Expected Data Transfer Length 6854 AHS is: 6856 Byte/ 0 | 1 | 2 | 3 | 6857 / | | | | 6858 |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| 6859 +---------------+---------------+---------------+--------------+ 6860 0| AHSLength (0x0005) | 0x02 | Reserved | 6861 +---------------+---------------+---------------+--------------+ 6862 4| Expected Read-Data Length | 6863 +---------------+---------------+---------------+--------------+ 6864 8 6866 11.2.3. Header Digest and Data Digest 6868 Optional header and data digests protect the integrity of the 6869 header and data, respectively. The digests, if present, are 6870 located, respectively, after the header and PDU-specific data, and 6871 cover respectively the header and the PDU data, each including 6872 the padding bytes, if any. 6874 The existence and type of digests are negotiated during the Login 6875 Phase. 6877 The separation of the header and data digests is useful in iSCSI 6878 routing applications, in which only the header changes when a 6879 message is forwarded. In this case, only the header digest should 6880 be recalculated. 6882 Digests are not included in data or header length fields. 6884 A zero-length Data Segment also implies a zero-length data-digest. 6886 11.2.4. Data Segment 6888 The (optional) Data Segment contains PDU associated data. Its 6889 payload effective length is provided in the BHS field - 6890 DataSegmentLength. The Data Segment is also padded to an integer 6891 number of 4 byte words. 6893 11.3. SCSI Command 6895 The format of the SCSI Command PDU is: 6897 Byte/ 0 | 1 | 2 | 3 | 6898 / | | | | 6899 |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| 6900 +---------------+---------------+---------------+--------------+ 6901 0|.|I| 0x01 |F|R|W|. .|ATTR | Reserved | 6902 +---------------+---------------+---------------+--------------+ 6903 4|TotalAHSLength | DataSegmentLength | 6904 +---------------+---------------+---------------+--------------+ 6905 8| Logical Unit Number (LUN) | 6906 + + 6907 12| | 6908 +---------------+---------------+---------------+--------------+ 6909 16| Initiator Task Tag | 6910 +---------------+---------------+---------------+--------------+ 6911 20| Expected Data Transfer Length | 6912 +---------------+---------------+---------------+--------------+ 6913 24| CmdSN | 6914 +---------------+---------------+---------------+--------------+ 6915 28| ExpStatSN | 6916 +---------------+---------------+---------------+--------------+ 6917 32/ SCSI Command Descriptor Block (CDB) / 6918 +/ / 6919 +---------------+---------------+---------------+--------------+ 6920 48/ AHS (Optional) / 6921 +---------------+---------------+---------------+--------------+ 6922 x/ Header Digest (Optional) / 6923 +---------------+---------------+---------------+--------------+ 6924 y/ (DataSegment, Command Data) (Optional) / 6925 +/ / 6926 +---------------+---------------+---------------+--------------+ 6927 z/ Data Digest (Optional) / 6928 +---------------+---------------+---------------+--------------+ 6930 11.3.1. Flags and Task Attributes (byte 1) 6932 The flags for a SCSI Command are: 6934 bit 0 (F) is set to 1 when no unsolicited SCSI Data-Out PDUs 6935 follow this PDU. When F=1 for a write and if Expected Data 6936 Transfer Length is larger than the DataSegmentLength, the 6937 target may solicit additional data through R2T. 6939 bit 1 (R) is set to 1 when the command is expected to input 6940 data. 6942 bit 2 (W) is set to 1 when the command is expected to output 6943 data. 6945 bit 3-4 Reserved. 6947 bit 5-7 contains Task Attributes. 6949 Task Attributes (ATTR) have one of the following integer values 6950 (see [SAM2] for details): 6952 0 - Untagged 6954 1 - Simple 6956 2 - Ordered 6958 3 - Head of Queue 6960 4 - ACA 6962 5-7 - Reserved 6964 At least one of the W and F bits MUST be set to 1. 6965 Either or both of R and W MAY be 1 when either the Expected Data 6966 Transfer Length and/or Bidirectional Read Expected Data Transfer 6967 Length are 0, but they MUST NOT both be 0 when the Expected Data 6968 Transfer Length and/or Bidirectional Read Expected Data Transfer 6969 Length are not 0 (i.e., when some data transfer is expected the 6970 transfer direction is indicated by the R and/or W bit). 6972 11.3.2. CmdSN - Command Sequence Number 6974 Enables ordered delivery across multiple connections in a single 6975 session. 6977 11.3.3. ExpStatSN 6979 Command responses up to ExpStatSN-1 (mod 2**32) have been received 6980 (acknowledges status) on the connection. 6982 11.3.4. Expected Data Transfer Length 6984 For unidirectional operations, the Expected Data Transfer Length 6985 field contains the number of bytes of data involved in this SCSI 6986 operation. For a unidirectional write operation (W flag set to 1 6987 and R flag set to 0), the initiator uses this field to specify the 6988 number of bytes of data it expects to transfer for this operation. 6989 For a unidirectional read operation (W flag set to 0 and R flag 6990 set to 1), the initiator uses this field to specify the number of 6991 bytes of data it expects the target to transfer to the initiator. 6992 It corresponds to the SAM2 byte count. 6994 For bidirectional operations (both R and W flags are set to 1), 6995 this field contains the number of data bytes involved in the write 6996 transfer. For bidirectional operations, an additional header 6997 segment MUST be present in the header sequence that indicates the 6998 Bidirectional Read Expected Data Transfer Length. The Expected 6999 Data Transfer Length field and the Bidirectional Read Expected 7000 Data Transfer Length field correspond to the SAM2 byte count. 7002 If the Expected Data Transfer Length for a write and the length of 7003 the immediate data part that follows the command (if any) are the 7004 same, then no more data PDUs are expected to follow. In this 7005 case, the F bit MUST be set to 1. 7007 If the Expected Data Transfer Length is higher than the 7008 FirstBurstLength (the negotiated maximum amount of unsolicited 7009 data the target will accept), the initiator MUST send the maximum 7010 amount of unsolicited data OR ONLY the immediate data, if any. 7012 Upon completion of a data transfer, the target informs the 7013 initiator (through residual counts) of how many bytes were 7014 actually processed (sent and/or received) by the target. 7016 11.3.5. CDB - SCSI Command Descriptor Block 7018 There are 16 bytes in the CDB field to accommodate the commonly 7019 used CDBs. Whenever the CDB is larger than 16 bytes, an Extended 7020 CDB AHS MUST be used to contain the CDB spillover. 7022 11.3.6. Data Segment - Command Data 7024 Some SCSI commands require additional parameter data to accompany 7025 the SCSI command. This data may be placed beyond the boundary of 7026 the iSCSI header in a data segment. Alternatively, user data 7027 (e.g., from a WRITE operation) can be placed in the data segment 7028 (both cases are referred to as immediate data). These data are 7029 governed by the rules for solicited vs. unsolicited data outlined 7030 in Section 4.2.5.2. 7032 11.4. SCSI Response 7034 The format of the SCSI Response PDU is: 7036 Byte/ 0 | 1 | 2 | 3 | 7037 / | | | | 7038 |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| 7039 +---------------+---------------+---------------+--------------+ 7040 0|.|.| 0x21 |1|. .|o|u|O|U|.| Response | Status | 7041 +---------------+---------------+---------------+--------------+ 7042 4|TotalAHSLength | DataSegmentLength | 7043 +---------------+---------------+---------------+--------------+ 7044 8| Reserved | 7045 + + 7046 12| | 7047 +---------------+---------------+---------------+--------------+ 7048 16| Initiator Task Tag | 7049 +---------------+---------------+---------------+--------------+ 7050 20| SNACK Tag or Reserved | 7051 +---------------+---------------+---------------+--------------+ 7052 24| StatSN | 7053 +---------------+---------------+---------------+--------------+ 7054 28| ExpCmdSN | 7055 +---------------+---------------+---------------+--------------+ 7056 32| MaxCmdSN | 7057 +---------------+---------------+---------------+--------------+ 7058 36| ExpDataSN or Reserved | 7059 +---------------+---------------+---------------+--------------+ 7060 40| Bidirectional Read Residual Count or Reserved | 7061 +---------------+---------------+---------------+--------------+ 7062 44| Residual Count or Reserved | 7063 +---------------+---------------+---------------+--------------+ 7064 48| Header-Digest (Optional) | 7065 +---------------+---------------+---------------+--------------+ 7066 / Data Segment (Optional) / 7067 +/ / 7068 +---------------+---------------+---------------+--------------+ 7069 | Data-Digest (Optional) | 7070 +---------------+---------------+---------------+--------------+ 7072 11.4.1. Flags (byte 1) 7074 bit 1-2 Reserved. 7076 bit 3 - (o) set for Bidirectional Read Residual Overflow. In 7077 this case, the Bidirectional Read Residual Count indicates 7078 the number of bytes that were not transferred to the 7079 initiator because the initiator's Expected Bidirectional 7080 Read Data Transfer Length was not sufficient. 7082 bit 4 - (u) set for Bidirectional Read Residual Underflow. In 7083 this case, the Bidirectional Read Residual Count indicates 7084 the number of bytes that were not transferred to the 7085 initiator out of the number of bytes expected to be 7086 transferred. 7088 bit 5 - (O) set for Residual Overflow. In this case, the 7089 Residual Count indicates the number of bytes that were not 7090 transferred because the initiator's Expected Data Transfer 7091 Length was not sufficient. For a bidirectional operation, 7092 the Residual Count contains the residual for the write 7093 operation. 7095 bit 6 - (U) set for Residual Underflow. In this case, the 7096 Residual Count indicates the number of bytes that were not 7097 transferred out of the number of bytes that were expected to 7098 be transferred. For a bidirectional operation, the Residual 7099 Count contains the residual for the write operation. 7101 bit 7 - (0) Reserved. 7103 Bits O and U and bits o and u are mutually exclusive (i.e., having 7104 both o and u or O and U set to 1 is a protocol error). 7106 For a response other than "Command Completed at Target", bits 3-6 7107 MUST be 0. 7109 11.4.2. Status 7111 The Status field is used to report the SCSI status of the command 7112 (as specified in [SAM2]) and is only valid if the Response Code is 7113 Command Completed at target. 7115 Some of the status codes defined in [SAM2] are: 7117 0x00 GOOD 7118 0x02 CHECK CONDITION 7120 0x08 BUSY 7122 0x18 RESERVATION CONFLICT 7124 0x28 TASK SET FULL 7126 0x30 ACA ACTIVE 7128 0x40 TASK ABORTED 7130 See [SAM2] for the complete list and definitions. 7132 If a SCSI device error is detected while data from the initiator 7133 is still expected (the command PDU did not contain all the data 7134 and the target has not received a Data PDU with the final bit 7135 Set), the target MUST wait until it receives a Data PDU with the F 7136 bit set in the last expected sequence before sending the Response 7137 PDU. 7139 11.4.3. Response 7141 This field contains the iSCSI service response. 7143 iSCSI service response codes defined in this specification are: 7145 0x00 - Command Completed at Target 7147 0x01 - Target Failure 7149 0x80-0xff - Vendor specific 7151 All other response codes are reserved. 7153 The Response is used to report a Service Response. The mapping of 7154 the response code into a SCSI service response code value, if 7155 needed, is outside the scope of this document. However, in 7156 symbolic terms response value 0x00 maps to the SCSI service 7157 response (see [SAM2] and [SPC3]) of TASK COMPLETE or LINKED 7158 COMMAND COMPLETE. All other Response values map to the SCSI 7159 service response of SERVICE DELIVERY OR TARGET FAILURE. 7161 If a SCSI Response PDU does not arrive before the session is 7162 terminated, the SCSI service response is SERVICE DELIVERY OR 7163 TARGET FAILURE. 7165 A non-zero response field indicates a failure to execute the 7166 command in which case the Status and Flag fields are undefined and 7167 MUST be ignored on reception. 7169 11.4.4. SNACK Tag 7171 This field contains a copy of the SNACK Tag of the last SNACK Tag 7172 accepted by the target on the same connection and for the command 7173 for which the response is issued. Otherwise it is reserved and 7174 should be set to 0. 7176 After issuing a R-Data SNACK the initiator must discard any SCSI 7177 status unless contained in an SCSI Response PDU carrying the same 7178 SNACK Tag as the last issued R-Data SNACK for the SCSI command on 7179 the current connection. 7181 For a detailed discussion on R-Data SNACK see SNACK. 7183 11.4.5. Residual Count 7185 11.4.5.1. Field Semantics 7187 The Residual Count field MUST be valid in the case where either 7188 the U bit or the O bit is set. If neither bit is set, the Residual 7189 Count field MUST be ignored on reception and SHOULD be set to 0 7190 when sending. Targets may set the residual count and initiators 7191 may use it when the response code is "completed at target" (even 7192 if the status returned is not GOOD). If the O bit is set, the 7193 Residual Count indicates the number of bytes that were not 7194 transferred because the initiator's Expected Data Transfer Length 7195 was not sufficient. If the U bit is set, the Residual Count 7196 indicates the number of bytes that were not transferred out of the 7197 number of bytes expected to be transferred. 7199 11.4.5.2. Residuals Concepts Overview 7201 SCSI-Presented Data Transfer Length (SPDTL) is the term this 7202 document uses (see Section 2.1 for definition) to represent the 7203 aggregate data length that the target SCSI layer attempts to 7204 transfer using the local iSCSI layer for a task. Expected Data 7205 Transfer Length (EDTL) is the iSCSI term that represents the 7206 length of data that the iSCSI layer expects to transfer for a 7207 task. EDTL is specified in the SCSI Command PDU. 7209 When SPDTL = EDTL for a task, the target iSCSI layer completes the 7210 task with no residuals. Whenever SPDTL differs from EDTL for a 7211 task, that task is said to have a residual. 7213 If SPDTL > EDTL for a task, iSCSI Overflow MUST be signaled in the 7214 SCSI Response PDU as specified in Section 11.4.5.1. The Residual 7215 Count MUST be set to the numerical value of (SPDTL - EDTL). 7217 If SPDTL < EDTL for a task, iSCSI Underflow MUST be signaled in 7218 the SCSI Response PDU as specified in Section 11.4.5.1. The 7219 Residual Count MUST be set to the numerical value of (EDTL - 7220 SPDTL). 7222 Note that the Overflow and Underflow scenarios are independent of 7223 Data-In and Data-Out. Either scenario is logically possible in 7224 either direction of data transfer. 7226 11.4.5.3. SCSI REPORT LUNS and Residual Overflow 7228 This Section discusses the residual overflow issues citing the 7229 example of the SCSI REPORT LUNS command. Note however that there 7230 are several SCSI commands (e.g., INQUIRY) with ALLOCATION LENGTH 7231 fields following the same underlying rules. The semantics in the 7232 rest of the Section apply to all such SCSI commands. 7234 The specification of the SCSI REPORT LUNS command requires that 7235 the SCSI target limit the amount of data transferred to a maximum 7236 size (ALLOCATION LENGTH) provided by the initiator in the REPORT 7237 LUNS CDB. 7239 If the Expected Data Transfer Length (EDTL) in the iSCSI header of 7240 the SCSI Command PDU for a REPORT LUNS command is set to at least 7241 as large as that ALLOCATION LENGTH, the SCSI layer truncation 7242 prevents an iSCSI Residual Overflow from occurring. A SCSI 7243 initiator can detect that such truncation has occurred via other 7244 information at theS CSI layer. The rest of the Section elaborates 7245 this required behavior. 7247 The SCSI REPORT LUNS command requests a target SCSI layer to 7248 return a logical unit inventory (LUN list) to the initiator SCSI 7249 layer (see Section 6.21 of [SPC3]). The size of this LUN list may 7250 not be known to the initiator SCSI layer when it issues the REPORT 7251 LUNS command; to avoid transferring more LUN list data than the 7252 initiator is prepared for, the REPORT LUNS CDB contains an 7253 ALLOCATION LENGTH field to specify the maximum amount of data to 7254 be transferred to the initiator for this command. If the initiator 7255 SCSI layer has underestimated the number of logical units at the 7256 target, it is possible that the complete logical unit inventory 7257 does not fit in the specified ALLOCATION LENGTH. In this 7258 situation, Section 4.3.3.6 in [SPC3] requires that the target SCSI 7259 layer "shall terminate transfers to the Data-In Buffer" when the 7260 number of bytes specified by the ALLOCATION LENGTH field have been 7261 transferred. 7263 Therefore, in response to a REPORT LUNS command, the SCSI layer at 7264 the target presents at most ALLOCATION LENGTH bytes of data 7265 (logical unit inventory) to iSCSI for transfer to the initiator. 7266 For a REPORT LUNS command, if the iSCSI EDTL is at least as large 7267 as the ALLOCATION LENGTH, the SCSI truncation ensures that the 7268 EDTL will accommodate all of the data to be transferred. If all of 7269 the logical unit inventory data presented to the iSCSI layer -- 7270 i.e., the data remaining after any SCSI truncation -- is 7271 transferred to the initiator by the iSCSI layer, an iSCSI Residual 7272 Overflow has not occurred and the iSCSI (O) bit MUST NOT be set in 7273 the SCSI Response or final SCSI Data-Out PDU. Note that this 7274 behavior is implied by the combination of Section 11.4.5.1 along 7275 with the specification of the REPORT LUNS command in [SPC3]. 7276 However, if the iSCSI EDTL is larger than the ALLOCATION LENGTH in 7277 this scenario, note that the iSCSI Underflow MUST be signaled in 7278 the SCSI Response PDU. An iSCSI Underflow MUST also be signaled 7279 when the iSCSI EDTL is equal to the ALLOCATION LENGTH but the 7280 logical unit inventory data presented to the iSCSI layer is 7281 smaller than the ALLOCATION LENGTH. 7283 The LUN LIST LENGTH field in the logical unit inventory (the first 7284 field in the inventory) is not affected by truncation of the 7285 inventory to fit in ALLOCATION LENGTH; this enables a SCSI 7286 initiator to determine that the received inventory is incomplete 7287 by noticing that the LUN LIST LENGTH in the inventory is larger 7288 than the ALLOCATION LENGTH that was sent in the REPORT LUNS CDB. A 7289 common initiator behavior in this situation is to re-issue the 7290 REPORT LUNS command with a larger ALLOCATION LENGTH. 7292 11.4.6. Bidirectional Read Residual Count 7294 The Bidirectional Read Residual Count field MUST be valid in the 7295 case where either the u bit or the o bit is set. If neither bit is 7296 set, the Bidirectional Read Residual Count field is reserved. 7297 Targets may set the Bidirectional Read Residual Count and 7298 initiators may use it when the response code is "completed at 7299 target". If the o bit is set, the Bidirectional Read Residual 7300 Count indicates the number of bytes that were not transferred to 7301 the initiator because the initiator's Expected Bidirectional Read 7302 Transfer Length was not sufficient. If the u bit is set, the 7303 Bidirectional Read Residual Count indicates the number of bytes 7304 that were not transferred to the initiator out of the number of 7305 bytes expected to be transferred. 7307 11.4.7. Data Segment - Sense and Response Data Segment 7309 iSCSI targets MUST support and enable autosense. If Status is 7310 CHECK CONDITION (0x02), then the Data Segment MUST contain sense 7311 data for the failed command. 7313 For some iSCSI responses, the response data segment MAY contain 7314 some response related information, (e.g., for a target failure, it 7315 may contain a vendor specific detailed description of the 7316 failure). 7318 If the DataSegmentLength is not 0, the format of the Data Segment 7319 is as follows: 7321 Byte/ 0 | 1 | 2 | 3 | 7322 / | | | | 7323 |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| 7324 +---------------+---------------+---------------+--------------+ 7325 0|SenseLength | Sense Data | 7326 +---------------+---------------+---------------+--------------+ 7327 x/ Sense Data / 7328 +---------------+---------------+---------------+--------------+ 7329 y/ Response Data / 7330 / / 7331 +---------------+---------------+---------------+--------------+ 7333 11.4.7.1. SenseLength 7335 Length of Sense Data. 7337 11.4.7.2. Sense Data 7339 The Sense Data contains detailed information about a check 7340 condition and [SPC3] specifies the format and content of the Sense 7341 Data. 7343 Certain iSCSI conditions result in the command being terminated at 7344 the target (response Command Completed at Target) with a SCSI 7345 Check Condition Status as outlined in the next table: 7347 +--------------------------+----------+--------------------------+ 7348 | iSCSI Condition |Sense | Additional Sense Code & | 7349 | |Key | Qualifier | 7350 +--------------------------+----------+--------------------------+ 7351 | Unexpected unsolicited |Aborted | ASC = 0x0c ASCQ = 0x0c | 7352 | data |Command-0B| Write Error | 7353 +--------------------------+----------+--------------------------+ 7354 | Incorrect amount of data |Aborted | ASC = 0x0c ASCQ = 0x0d | 7355 | |Command-0B| Write Error | 7356 +--------------------------+----------+--------------------------+ 7357 | Protocol Service CRC |Aborted | ASC = 0x47 ASCQ = 0x05 | 7358 | error |Command-0B| CRC Error Detected | 7359 +--------------------------+----------+--------------------------+ 7360 | SNACK rejected |Aborted | ASC = 0x11 ASCQ = 0x13 | 7361 | |Command-0B| Read Error | 7362 +--------------------------+----------+--------------------------+ 7364 The target reports the "Incorrect amount of data" condition if 7365 during data output the total data length to output is greater than 7366 FirstBurstLength and the initiator sent unsolicited non-immediate 7367 data but the total amount of unsolicited data is different than 7368 FirstBurstLength. The target reports the same error when the 7369 amount of data sent as a reply to an R2T does not match the amount 7370 requested. 7372 11.4.8. ExpDataSN 7374 The number of Data-In (read) PDUs the target has sent for the 7375 command. 7377 This field MUST be 0 if the response code is not Command Completed 7378 at Target or the target sent no Data-In PDUs for the command. 7380 11.4.9. StatSN - Status Sequence Number 7382 StatSN is a Sequence Number that the target iSCSI layer generates 7383 per connection and that in turn, enables the initiator to 7384 acknowledge status reception. StatSN is incremented by 1 for every 7385 response/status sent on a connection except for responses sent as 7386 a result of a retry or SNACK. In the case of responses sent due to 7387 a retransmission request, the StatSN MUST be the same as the first 7388 time the PDU was sent unless the connection has since been 7389 restarted. 7390 11.4.10. ExpCmdSN - Next Expected CmdSN from this Initiator 7392 ExpCmdSN is a Sequence Number that the target iSCSI returns to the 7393 initiator to acknowledge command reception. It is used to update a 7394 local variable with the same name. An ExpCmdSN equal to MaxCmdSN+1 7395 indicates that the target cannot accept new commands. 7397 11.4.11. MaxCmdSN - Maximum CmdSN from this Initiator 7399 MaxCmdSN is a Sequence Number that the target iSCSI returns to the 7400 initiator to indicate the maximum CmdSN the initiator can send. It 7401 is used to update a local variable with the same name. If MaxCmdSN 7402 is equal to ExpCmdSN-1, this indicates to the initiator that the 7403 target cannot receive any additional commands. When MaxCmdSN 7404 changes at the target while the target has no pending PDUs to 7405 convey this information to the initiator, it MUST generate a NOP- 7406 IN to carry the new MaxCmdSN. 7408 11.5. Task Management Function Request 7410 Byte/ 0 | 1 | 2 | 3 | 7411 / | | | | 7412 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 67| 7413 +---------------+---------------+---------------+--------------+ 7414 0|.|I| 0x02 |1| Function | Reserved | 7415 +---------------+---------------+---------------+--------------+ 7416 4|TotalAHSLength | DataSegmentLength | 7417 +---------------+---------------+---------------+--------------+ 7418 8| Logical Unit Number (LUN) or Reserved | 7419 + + 7420 12| | 7421 +---------------+---------------+---------------+--------------+ 7422 16| Initiator Task Tag | 7423 +---------------+---------------+---------------+--------------+ 7424 20| Referenced Task Tag or 0xffffffff | 7425 +---------------+---------------+---------------+--------------+ 7426 24| CmdSN | 7427 +---------------+---------------+---------------+--------------+ 7428 28| ExpStatSN | 7429 +---------------+---------------+---------------+--------------+ 7430 32| RefCmdSN or Reserved | 7431 +---------------+---------------+---------------+--------------+ 7432 36| ExpDataSN or Reserved | 7433 +---------------+---------------+---------------+--------------+ 7434 40/ Reserved / 7435 +/ / 7436 +---------------+---------------+---------------+--------------+ 7437 48| Header-Digest (Optional) | 7438 +---------------+---------------+---------------+--------------+ 7440 11.5.1. Function 7442 The Task Management functions provide an initiator with a way to 7443 explicitly control the execution of one or more Tasks (SCSI and 7444 iSCSI tasks). The Task Management function codes are listed below. 7445 For a more detailed description of SCSI task management, see 7446 [SAM2]. 7448 1 - ABORT TASK - aborts the task identified by the 7449 Referenced Task Tag field. 7451 2 - ABORT TASK SET - aborts all Tasks issued via this 7452 session on the logical unit. 7454 3 - CLEAR ACA - clears the Auto Contingent Allegiance 7455 condition. 7457 4 - CLEAR TASK SET - aborts all Tasks in the appropriate 7458 task set as defined by the TST field in the Control mode 7459 page (see [SPC3]). 7461 5 - LOGICAL UNIT RESET 7463 6 - TARGET WARM RESET 7465 7 - TARGET COLD RESET 7467 8 - TASK REASSIGN - reassigns connection allegiance for the 7468 task identified by the Initiator Task Tag field to this 7469 connection, thus resuming the iSCSI exchanges for the task. 7471 All other possible values for Function field are reserved. 7473 For all these functions, the Task Management function response 7474 MUST be returned as detailed in Section 11.6. All these functions 7475 apply to the referenced tasks regardless of whether they are 7476 proper SCSI tasks or tagged iSCSI operations. Task management 7477 requests must act on all the commands from the same session having 7478 a CmdSN lower than the task management CmdSN. LOGICAL UNIT RESET, 7479 TARGET WARM RESET and TARGET COLD RESET may affect commands from 7480 other sessions or commands from the same session regardless of 7481 their CmdSN value. 7483 If the task management request is marked for immediate delivery, 7484 it must be considered immediately for execution, but the 7485 operations involved (all or part of them) may be postponed to 7486 allow the target to receive all relevant tasks. According to 7487 [SAM2], for all the tasks covered by the Task Management response 7488 (i.e., with CmdSN lower than the task management command CmdSN) 7489 but except the Task Management response to a TASK REASSIGN, 7490 additional responses MUST NOT be delivered to the SCSI layer after 7491 the Task Management response. The iSCSI initiator MAY deliver to 7492 the SCSI layer all responses received before the Task Management 7493 response (i.e., it is a matter of implementation if the SCSI 7494 responses, received before the Task Management response but after 7495 the task management request was issued, are delivered to the SCSI 7496 layer by the iSCSI layer in the initiator). The iSCSI target MUST 7497 ensure that no responses for the tasks covered by a task 7498 management function are delivered to the iSCSI initiator after the 7499 Task Management response except for a task covered by a TASK 7500 REASSIGN. 7502 For ABORT TASK SET and CLEAR TASK SET, the issuing initiator MUST 7503 continue to respond to all valid target transfer tags (received 7504 via R2T, Text Response, NOP-In, or SCSI Data-in PDUs) related to 7505 the affected task set, even after issuing the task management 7506 request. The issuing initiator SHOULD however terminate (i.e., by 7507 setting the F-bit to 1) these response sequences as quickly as 7508 possible. The target on its part MUST wait for responses on all 7509 affected target transfer tags before acting on either of these two 7510 task management requests. In case all or part of the response 7511 sequence is not received (due to digest errors) for a valid TTT, 7512 the target MAY treat it as a case of within-command error recovery 7513 class (see Section 7.1.4.1) if it is supporting ErrorRecoveryLevel 7514 >= 1, or alternatively may drop the connection to complete the 7515 requested task set function. 7517 If an ABORT TASK is issued for a task created by an immediate 7518 command then RefCmdSN MUST be that of the Task Management request 7519 itself (i.e. CmdSN and RefCmdSN are equal); otherwise RefCmdSN 7520 MUST be set to the CmdSN of the task to be aborted (lower than 7521 CmdSN). 7523 If the connection is still active (it is not undergoing an 7524 implicit or explicit logout), ABORT TASK MUST be issued on the 7525 same connection to which the task to be aborted is allegiant at 7526 the time the Task Management Request is issued. If the connection 7527 is implicitly or explicitly logged out (i.e., no other request 7528 will be issued on the failing connection and no other response 7529 will be received on the failing connection), then an ABORT TASK 7530 function request may be issued on another connection. This Task 7531 Management request will then establish a new allegiance for the 7532 command to be aborted as well as abort it (i.e., the task to be 7533 aborted will not have to be retried or reassigned, and its status, 7534 if sent but not acknowledged, will be resent followed by the Task 7535 Management response). 7537 At the target an ABORT TASK function MUST NOT be executed on a 7538 Task Management request; such a request MUST result in Task 7539 Management response of "Function rejected". 7541 For the LOGICAL UNIT RESET function, the target MUST behave as 7542 dictated by the Logical Unit Reset function in [SAM2]. 7544 The implementation of the TARGET WARM RESET function and the 7545 TARGET COLD RESET function is OPTIONAL and when implemented, 7546 should act as described below. The TARGET WARM RESET is also 7547 subject to SCSI access controls on the requesting initiator as 7548 defined in [SPC3]. When authorization fails at the target, the 7549 appropriate response as described in Section 11.6.1 MUST be 7550 returned by the target. The TARGET COLD RESET function is not 7551 subject to SCSI access controls, but its execution privileges may 7552 be managed by iSCSI mechanisms such as login authentication. 7554 When executing the TARGET WARM RESET and TARGET COLD RESET 7555 functions, the target cancels all pending operations on all 7556 Logical Units known by the issuing initiator. Both functions are 7557 equivalent to the Target Reset function specified by [SAM2]. They 7558 can affect many other initiators logged in with the servicing SCSI 7559 target port. 7561 The target MUST treat the TARGET COLD RESET function additionally 7562 as a power on event, thus terminating all of its TCP connections 7563 to all initiators (all sessions are terminated). For this reason, 7564 the Service Response (defined by [SAM2]) for this SCSI task 7565 management function may not be reliably delivered to the issuing 7566 initiator port. 7568 For the TASK REASSIGN function, the target should reassign the 7569 connection allegiance to this new connection (and thus resume 7570 iSCSI exchanges for the task). TASK REASSIGN MUST ONLY be received 7571 by the target after the connection on which the command was 7572 previously executing has been successfully logged-out. The Task 7573 Management response MUST be issued before the reassignment becomes 7574 effective. 7576 For additional usage semantics see Section 7.2. 7578 At the target a TASK REASSIGN function request MUST NOT be 7579 executed to reassign the connection allegiance of a Task 7580 Management function request, an active text negotiation task, or a 7581 Logout task; such a request MUST result in Task Management 7582 response of "Function rejected". 7584 TASK REASSIGN MUST be issued as an immediate command. 7586 11.5.2. TotalAHSLength and DataSegmentLength 7588 For this PDU, TotalAHSLength and DataSegmentLength MUST be 0. 7590 11.5.3. LUN 7592 This field is required for functions that address a specific LU 7593 (ABORT TASK, CLEAR TASK SET, ABORT TASK SET, CLEAR ACA, LOGICAL 7594 UNIT RESET) and is reserved in all others. 7596 11.5.4. Referenced Task Tag 7598 The Initiator Task Tag of the task to be aborted for the ABORT 7599 TASK function or reassigned for the TASK REASSIGN function. For 7600 all the other functions this field MUST be set to the reserved 7601 value 0xffffffff. 7603 11.5.5. RefCmdSN 7605 If an ABORT TASK is issued for a task created by an immediate 7606 command then RefCmdSN MUST be that of the Task Management request 7607 itself (i.e. CmdSN and RefCmdSN are equal). 7609 For an ABORT TASK of a task created by non-immediate command 7610 RefCmdSN MUST be set to the CmdSN of the task identified by the 7611 Referenced Task Tag field. Targets must use this field as 7612 described in Section 11.6.1 when the task identified by the 7613 Referenced Task Tag field is not with the target. 7615 Otherwise, this field is reserved. 7617 11.5.6. ExpDataSN 7619 For recovery purposes, the iSCSI target and initiator maintain a 7620 data acknowledgement reference number - the first input DataSN 7621 number unacknowledged by the initiator. When issuing a new 7622 command, this number is set to 0. If the function is TASK 7623 REASSIGN, which establishes a new connection allegiance for a 7624 previously issued Read or Bidirectional command, ExpDataSN will 7625 contain an updated data acknowledgement reference number or the 7626 value 0; the latter indicating that the data acknowledgement 7627 reference number is unchanged. The initiator MUST discard any data 7628 PDUs from the previous execution that it did not acknowledge and 7629 the target MUST transmit all Data-in PDUs (if any) starting with 7630 the data acknowledgement reference number. The number of 7631 retransmitted PDUs may or may not be the same as the original 7632 transmission depending on if there was a change in 7633 MaxRecvDataSegmentLength in the reassignment. The target MAY also 7634 send no more Data-In PDUs if all data has been acknowledged. 7636 The value of ExpDataSN MUST be 0 or higher than the DataSN of the 7637 last acknowledged Data-In PDU, but not larger than DataSN+1 of the 7638 last Data-IN PDU sent by the target. Any other value MUST be 7639 ignored by the target. 7641 For other functions this field is reserved. 7643 11.6. Task Management Function Response 7644 Byte/ 0 | 1 | 2 | 3 | 7645 / | | | | 7646 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 67| 7647 +---------------+---------------+---------------+--------------+ 7648 0|.|.| 0x22 |1| Reserved | Response | Reserved | 7649 +---------------+---------------+---------------+--------------+ 7650 4|TotalAHSLength | DataSegmentLength | 7651 +--------------------------------------------------------------+ 7652 8/ Reserved / 7653 / / 7654 +---------------+---------------+---------------+--------------+ 7655 16| Initiator Task Tag | 7656 +---------------+---------------+---------------+--------------+ 7657 20| Reserved | 7658 +---------------+---------------+---------------+--------------+ 7659 24| StatSN | 7660 +---------------+---------------+---------------+--------------+ 7661 28| ExpCmdSN | 7662 +---------------+---------------+---------------+--------------+ 7663 32| MaxCmdSN | 7664 +---------------+---------------+---------------+--------------+ 7665 36/ Reserved / 7666 +/ / 7667 +---------------+---------------+---------------+--------------+ 7668 48| Header-Digest (Optional) | 7669 +---------------+---------------+---------------+--------------+ 7671 For the functions ABORT TASK, ABORT TASK SET, CLEAR ACA, CLEAR 7672 TASK SET, LOGICAL UNIT RESET, TARGET COLD RESET, TARGET WARM RESET 7673 and TASK REASSIGN, the target performs the requested Task 7674 Management function and sends a Task Management response back to 7675 the initiator. For TASK REASSIGN, the new connection allegiance 7676 MUST ONLY become effective at the target after the target issues 7677 the Task Management Response. 7679 11.6.1. Response 7681 The target provides a Response, which may take on the following 7682 values: 7684 0 - Function complete. 7685 1 - Task does not exist. 7687 2 - LUN does not exist. 7688 3 - Task still allegiant. 7689 4 - Task allegiance reassignment not supported. 7690 5 - Task management function not supported. 7691 6 - Function authorization failed. 7692 255 - Function rejected. 7694 All other values are reserved. 7696 For a discussion on usage of response codes 3 and 4, see Section 7697 7.2.2. 7699 For the TARGET COLD RESET and TARGET WARM RESET functions, the 7700 target cancels all pending operations across all Logical Units 7701 known to the issuing initiator. For the TARGET COLD RESET 7702 function, the target MUST then close all of its TCP connections to 7703 all initiators (terminates all sessions). 7705 The mapping of the response code into a SCSI service response code 7706 value, if needed, is outside the scope of this document. However, 7707 in symbolic terms, Response values 0 and 1 map to the SCSI service 7708 response of FUNCTION COMPLETE. Response value 2 maps to SCSI 7709 service response of INCORRECT LOGICAL UNIT NUMBER. All other 7710 Response values map to the SCSI service response of FUNCTION 7711 REJECTED. If a Task Management function response PDU does not 7712 arrive before the session is terminated, the SCSI service response 7713 is SERVICE DELIVERY OR TARGET FAILURE. 7715 The response to ABORT TASK SET and CLEAR TASK SET MUST only be 7716 issued by the target after all of the commands affected have been 7717 received by the target, the corresponding task management 7718 functions have been executed by the SCSI target, and the delivery 7719 of all responses delivered until the task management function 7720 completion have been confirmed (acknowledged through ExpStatSN) by 7721 the initiator on all connections of this session. For the exact 7722 timeline of events, refer to Section 4.2.3.3 and Section 4.2.3.4. 7724 For the ABORT TASK function, 7725 a) If the Referenced Task Tag identifies a valid task leading 7726 to a successful termination, then targets must return the 7727 "Function complete" response. 7728 b) If the Referenced Task Tag does not identify an existing 7729 task, but if the CmdSN indicated by the RefCmdSN field in 7730 the Task Management function request is within the valid 7731 CmdSN window and less than the CmdSN of the Task Management 7732 function request itself, then targets must consider the 7733 CmdSN received and return the "Function complete" response. 7734 c) If the Referenced Task Tag does not identify an existing 7735 task and if the CmdSN indicated by the RefCmdSN field in 7736 the Task Management function request is outside the valid 7737 CmdSN window, then targets must return the "Task does not 7738 exist" response. 7740 For response semantics on function types that can potentially 7741 impact multiple active tasks on the target, see Section 4.2.3. 7743 11.6.2. TotalAHSLength and DataSegmentLength 7745 For this PDU TotalAHSLength and DataSegmentLength MUST be 0. 7747 11.7. SCSI Data-out & SCSI Data-in 7749 The SCSI Data-out PDU for WRITE operations has the following 7750 format: 7752 Byte/ 0 | 1 | 2 | 3 | 7753 / | | | | 7754 |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| 7755 +---------------+---------------+---------------+--------------+ 7756 0|.|.| 0x05 |F| Reserved | 7757 +---------------+---------------+---------------+--------------+ 7758 4|TotalAHSLength | DataSegmentLength | 7759 +---------------+---------------+---------------+--------------+ 7760 8| LUN or Reserved | 7761 + + 7762 12| | 7763 +---------------+---------------+---------------+--------------+ 7764 16| Initiator Task Tag | 7765 +---------------+---------------+---------------+--------------+ 7766 20| Target Transfer Tag or 0xffffffff | 7767 +---------------+---------------+---------------+--------------+ 7768 24| Reserved | 7769 +---------------+---------------+---------------+--------------+ 7770 28| ExpStatSN | 7771 +---------------+---------------+---------------+--------------+ 7772 32| Reserved | 7773 +---------------+---------------+---------------+--------------+ 7774 36| DataSN | 7775 +---------------+---------------+---------------+--------------+ 7776 40| Buffer Offset | 7777 +---------------+---------------+---------------+--------------+ 7778 44| Reserved | 7779 +---------------+---------------+---------------+--------------+ 7780 48| Header-Digest (Optional) | 7781 +---------------+---------------+---------------+--------------+ 7782 / DataSegment / 7783 +/ / 7784 +---------------+---------------+---------------+--------------+ 7785 | Data-Digest (Optional) | 7786 +---------------+---------------+---------------+--------------+ 7788 The SCSI Data-in PDU for READ operations has the following format: 7790 Byte/ 0 | 1 | 2 | 3 | 7791 / | | | | 7792 |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| 7793 +---------------+---------------+---------------+--------------+ 7794 0|.|.| 0x25 |F|A|0 0 0|O|U|S| Reserved |Status or Rsvd| 7795 +---------------+---------------+---------------+--------------+ 7796 4|TotalAHSLength | DataSegmentLength | 7797 +---------------+---------------+---------------+--------------+ 7798 8| LUN or Reserved | 7799 + + 7800 12| | 7801 +---------------+---------------+---------------+--------------+ 7802 16| Initiator Task Tag | 7803 +---------------+---------------+---------------+--------------+ 7804 20| Target Transfer Tag or 0xffffffff | 7805 +---------------+---------------+---------------+--------------+ 7806 24| StatSN or Reserved | 7807 +---------------+---------------+---------------+--------------+ 7808 28| ExpCmdSN | 7809 +---------------+---------------+---------------+--------------+ 7810 32| MaxCmdSN | 7811 +---------------+---------------+---------------+--------------+ 7812 36| DataSN | 7813 +---------------+---------------+---------------+--------------+ 7814 40| Buffer Offset | 7815 +---------------+---------------+---------------+--------------+ 7816 44| Residual Count | 7817 +---------------+---------------+---------------+--------------+ 7818 48| Header-Digest (Optional) | 7819 +---------------+---------------+---------------+--------------+ 7820 / DataSegment / 7821 +/ / 7822 +---------------+---------------+---------------+--------------+ 7823 | Data-Digest (Optional) | 7824 +---------------+---------------+---------------+--------------+ 7826 Status can accompany the last Data-in PDU if the command did not 7827 end with an exception (i.e., the status is "good status" - GOOD, 7828 CONDITION MET or INTERMEDIATE CONDITION MET). The presence of 7829 status (and of a residual count) is signaled though the S flag 7830 bit. Although targets MAY choose to send even non-exception 7831 status in separate responses, initiators MUST support non- 7832 exception status in Data-In PDUs. 7834 11.7.1. F (Final) Bit 7836 For outgoing data, this bit is 1 for the last PDU of unsolicited 7837 data or the last PDU of a sequence that answers an R2T. 7839 For incoming data, this bit is 1 for the last input (read) data 7840 PDU of a sequence. Input can be split into several sequences, 7841 each having its own F bit. Splitting the data stream into 7842 sequences does not affect DataSN counting on Data-In PDUs. It MAY 7843 be used as a "change direction" indication for Bidirectional 7844 operations that need such a change. 7846 DataSegmentLength MUST NOT exceed MaxRecvDataSegmentLength for the 7847 direction it is sent and the total of all the DataSegmentLength of 7848 all PDUs in a sequence MUST NOT exceed MaxBurstLength (or 7849 FirstBurstLength for unsolicited data). However the number of 7850 individual PDUs in a sequence (or in total) may be higher than the 7851 MaxBurstLength (or FirstBurstLength) to MaxRecvDataSegmentLength 7852 ratio (as PDUs may be limited in length by the sender 7853 capabilities). Using DataSegmentLength of 0 may increase beyond 7854 what is reasonable for the number of PDUs and should therefore be 7855 avoided. 7857 For Bidirectional operations, the F bit is 1 for both the end of 7858 the input sequences and the end of the output sequences. 7860 11.7.2. A (Acknowledge) bit 7862 For sessions with ErrorRecoveryLevel 1 or higher, the target sets 7863 this bit to 1 to indicate that it requests a positive 7864 acknowledgement from the initiator for the data received. The 7865 target should use the A bit moderately; it MAY only set the A bit 7866 to 1 once every MaxBurstLength bytes, or on the last Data-In PDU 7867 that concludes the entire requested read data transfer for the 7868 task from the target's perspective, and it MUST NOT do so more 7869 frequently. The target MUST NOT set to 1 the A bit for sessions 7870 with ErrorRecoveryLevel=0. The initiator MUST ignore the A bit set 7871 to 1 for sessions with ErrorRecoveryLevel=0. 7873 On receiving a Data-In PDU with the A bit set to 1 on a session 7874 with ErrorRecoveryLevel greater than 0, if there are no holes in 7875 the read data until that Data-In PDU, the initiator MUST issue a 7876 SNACK of type DataACK except when it is able to acknowledge the 7877 status for the task immediately via ExpStatSN on other outbound 7878 PDUs if the status for the task is also received. In the latter 7879 case (acknowledgement through ExpStatSN), sending a SNACK of type 7880 DataACK in response to the A bit is OPTIONAL, but if it is done, 7881 it must not be sent after the status acknowledgement through 7882 ExpStatSN. If the initiator has detected holes in the read data 7883 prior to that Data-In PDU, it MUST postpone issuing the SNACK of 7884 type DataACK until the holes are filled. An initiator also MUST 7885 NOT acknowledge the status for the task before those holes are 7886 filled. A status acknowledgement for a task that generated the 7887 Data-In PDUs is considered by the target as an implicit 7888 acknowledgement of the Data-In PDUs if such an acknowledgement was 7889 requested by the target. 7891 11.7.3. Flags (byte 1) 7893 The last SCSI Data packet sent from a target to an initiator for a 7894 SCSI command that completed successfully (with a status of GOOD, 7895 CONDITION MET, INTERMEDIATE or INTERMEDIATE CONDITION MET) may 7896 also optionally contain the Status for the data transfer. In this 7897 case, Sense Data cannot be sent together with the Command Status. 7898 If the command is completed with an error, then the response and 7899 sense data MUST be sent in a SCSI Response PDU (i.e., MUST NOT be 7900 sent in a SCSI Data packet). For Bidirectional commands, the 7901 status MUST be sent in a SCSI Response PDU. 7903 bit 2-4 - Reserved. 7905 bit 5-6 - used the same as in a SCSI Response. These bits are 7906 only valid when S is set to 1. For details see SNACK . 7908 bit 7 S (status)- set to indicate that the Command Status 7909 field contains status. If this bit is set to 1, the F bit 7910 MUST also be set to 1. 7912 The fields StatSN, Status, and Residual Count only have meaningful 7913 content if the S bit is set to 1 and their values are defined in 7914 SNACK . 7916 11.7.4. Target Transfer Tag and LUN 7918 On outgoing data, the Target Transfer Tag is provided to the 7919 target if the transfer is honoring an R2T. In this case, the 7920 Target Transfer Tag field is a replica of the Target Transfer Tag 7921 provided with the R2T. 7923 On incoming data, the Target Transfer Tag and LUN MUST be provided 7924 by the target if the A bit is set to 1; otherwise they are 7925 reserved. The Target Transfer Tag and LUN are copied by the 7926 initiator into the SNACK of type DataACK that it issues as a 7927 result of receiving a SCSI Data-in PDU with the A bit set to 1. 7929 The Target Transfer Tag values are not specified by this protocol 7930 except that the value 0xffffffff is reserved and means that the 7931 Target Transfer Tag is not supplied. If the Target Transfer Tag 7932 is provided, then the LUN field MUST hold a valid value and be 7933 consistent with whatever was specified with the command; 7934 otherwise, the LUN field is reserved. 7936 11.7.5. DataSN 7938 For input (read) or bidirectional Data-In PDUs, the DataSN is the 7939 input PDU number within the data transfer for the command 7940 identified by the Initiator Task Tag. 7942 R2T and Data-In PDUs, in the context of bidirectional commands, 7943 share the numbering sequence (see Section 4.2.2.4). 7945 For output (write) data PDUs, the DataSN is the Data-Out PDU 7946 number within the current output sequence. The current output 7947 sequence is either identified by the Initiator Task Tag (for 7948 unsolicited data) or is a data sequence generated for one R2T (for 7949 data solicited through R2T). 7951 11.7.6. Buffer Offset 7953 The Buffer Offset field contains the offset of this PDU payload 7954 data within the complete data transfer. The sum of the buffer 7955 offset and length should not exceed the expected transfer length 7956 for the command. 7958 The order of data PDUs within a sequence is determined by 7959 DataPDUInOrder. When set to Yes, it means that PDUs have to be in 7960 increasing Buffer Offset order and overlays are forbidden. 7962 The ordering between sequences is determined by 7963 DataSequenceInOrder. When set to Yes, it means that sequences have 7964 to be in increasing Buffer Offset order and overlays are 7965 forbidden. 7967 11.7.7. DataSegmentLength 7969 This is the data payload length of a SCSI Data-In or SCSI Data-Out 7970 PDU. The sending of 0 length data segments should be avoided, but 7971 initiators and targets MUST be able to properly receive 0 length 7972 data segments. 7974 The Data Segments of Data-in and Data-out PDUs SHOULD be filled to 7975 the integer number of 4 byte words (real payload) unless the F bit 7976 is set to 1. 7978 11.8. Ready To Transfer (R2T) 7980 Byte/ 0 | 1 | 2 | 3 | 7981 / | | | | 7982 |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| 7983 +---------------+---------------+---------------+--------------+ 7984 0|.|.| 0x31 |1| Reserved | 7985 +---------------+---------------+---------------+--------------+ 7986 4|TotalAHSLength | DataSegmentLength | 7987 +---------------+---------------+---------------+--------------+ 7988 8| LUN | 7989 + + 7990 12| | 7991 +---------------+---------------+---------------+--------------+ 7992 16| Initiator Task Tag | 7993 +---------------+---------------+---------------+--------------+ 7994 20| Target Transfer Tag | 7995 +---------------+---------------+---------------+--------------+ 7996 24| StatSN | 7997 +---------------+---------------+---------------+--------------+ 7998 28| ExpCmdSN | 7999 +---------------+---------------+---------------+--------------+ 8000 32| MaxCmdSN | 8001 +---------------+---------------+---------------+--------------+ 8002 36| R2TSN | 8003 +---------------+---------------+---------------+--------------+ 8004 40| Buffer Offset | 8005 +---------------+---------------+---------------+--------------+ 8006 44| Desired Data Transfer Length | 8007 +--------------------------------------------------------------+ 8008 48| Header-Digest (Optional) | 8009 +---------------+---------------+---------------+--------------+ 8011 When an initiator has submitted a SCSI Command with data that 8012 passes from the initiator to the target (WRITE), the target may 8013 specify which blocks of data it is ready to receive. The target 8014 may request that the data blocks be delivered in whichever order 8015 is convenient for the target at that particular instant. This 8016 information is passed from the target to the initiator in the 8017 Ready To Transfer (R2T) PDU. 8019 In order to allow write operations without an explicit initial 8020 R2T, the initiator and target MUST have negotiated the key 8021 InitialR2T to No during Login. 8023 An R2T MAY be answered with one or more SCSI Data-out PDUs with a 8024 matching Target Transfer Tag. If an R2T is answered with a single 8025 Data-out PDU, the Buffer Offset in the Data PDU MUST be the same 8026 as the one specified by the R2T, and the data length of the Data 8027 PDU MUST be the same as the Desired Data Transfer Length specified 8028 in the R2T. If the R2T is answered with a sequence of Data PDUs, 8029 the Buffer Offset and Length MUST be within the range of those 8030 specified by R2T, and the last PDU MUST have the F bit set to 1. 8031 If the last PDU (marked with the F bit) is received before the 8032 Desired Data Transfer Length is transferred, a target MAY choose 8033 to Reject that PDU with "Protocol error" reason code. 8034 DataPDUInOrder governs the Data-Out PDU ordering. If 8035 DataPDUInOrder is set to Yes, the Buffer Offsets and Lengths for 8036 consecutive PDUs MUST form a continuous non-overlapping range and 8037 the PDUs MUST be sent in increasing offset order. 8039 The target may send several R2T PDUs. It, therefore, can have a 8040 number of pending data transfers. The number of outstanding R2T 8041 PDUs are limited by the value of the negotiated key 8042 MaxOutstandingR2T. Within a task, outstanding R2Ts MUST be 8043 fulfilled by the initiator in the order in which they were 8044 received. 8046 R2T PDUs MAY also be used to recover Data Out PDUs. Such an R2T 8047 (Recovery-R2T) is generated by a target upon detecting the loss of 8048 one or more Data-Out PDUs due to: 8050 - Digest error 8052 - Sequence error 8054 - Sequence reception timeout 8056 A Recovery-R2T carries the next unused R2TSN, but requests part of 8057 or the entire data burst that an earlier R2T (with a lower R2TSN) 8058 had already requested. 8060 DataSequenceInOrder governs the buffer offset ordering in 8061 consecutive R2Ts. If DataSequenceInOrder is Yes, then consecutive 8062 R2Ts MUST refer to continuous non-overlapping ranges except for 8063 Recovery-R2Ts. 8065 11.8.1. TotalAHSLength and DataSegmentLength 8067 For this PDU TotalAHSLength and DataSegmentLength MUST be 0. 8069 11.8.2. R2TSN 8071 R2TSN is the R2T PDU input PDU number within the command 8072 identified by the Initiator Task Tag. 8074 For bidirectional commands R2T and Data-In PDUs share the input 8075 PDU numbering sequence (see Section 4.2.2.4). 8077 11.8.3. StatSN 8079 The StatSN field will contain the next StatSN. The StatSN for this 8080 connection is not advanced after this PDU is sent. 8082 11.8.4. Desired Data Transfer Length and Buffer Offset 8084 The target specifies how many bytes it wants the initiator to send 8085 because of this R2T PDU. The target may request the data from the 8086 initiator in several chunks, not necessarily in the original order 8087 of the data. The target, therefore, also specifies a Buffer Offset 8088 that indicates the point at which the data transfer should begin, 8089 relative to the beginning of the total data transfer. The Desired 8090 Data Transfer Length MUST NOT be 0 and MUST NOT exceed 8091 MaxBurstLength. 8093 11.8.5. Target Transfer Tag 8095 The target assigns its own tag to each R2T request that it sends 8096 to the initiator. This tag can be used by the target to easily 8097 identify the data it receives. The Target Transfer Tag and LUN are 8098 copied in the outgoing data PDUs and are only used by the target. 8099 There is no protocol rule about the Target Transfer Tag except 8100 that the value 0xffffffff is reserved and MUST NOT be sent by a 8101 target in an R2T. 8103 11.9. Asynchronous Message 8105 An Asynchronous Message may be sent from the target to the 8106 initiator without correspondence to a particular command. The 8107 target specifies the reason for the event and sense data. 8109 Byte/ 0 | 1 | 2 | 3 | 8110 / | | | | 8111 |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| 8112 +---------------+---------------+---------------+--------------+ 8113 0|.|.| 0x32 |1| Reserved | 8114 +---------------+---------------+---------------+--------------+ 8115 4|TotalAHSLength | DataSegmentLength | 8116 +---------------+---------------+---------------+--------------+ 8117 8| LUN or Reserved | 8118 + + 8119 12| | 8120 +---------------+---------------+---------------+--------------+ 8121 16| 0xffffffff | 8122 +---------------+---------------+---------------+--------------+ 8123 20| Reserved | 8124 +---------------+---------------+---------------+--------------+ 8125 24| StatSN | 8126 +---------------+---------------+---------------+--------------+ 8127 28| ExpCmdSN | 8128 +---------------+---------------+---------------+--------------+ 8129 32| MaxCmdSN | 8130 +---------------+---------------+---------------+--------------+ 8131 36| AsyncEvent | AsyncVCode | Parameter1 or Reserved | 8132 +---------------+---------------+---------------+--------------+ 8133 40| Parameter2 or Reserved | Parameter3 or Reserved | 8134 +---------------+---------------+---------------+--------------+ 8135 44| Reserved | 8136 +---------------+---------------+---------------+--------------+ 8137 48| Header-Digest (Optional) | 8138 +---------------+---------------+---------------+--------------+ 8139 / DataSegment - Sense Data and iSCSI Event Data / 8140 +/ / 8141 +---------------+---------------+---------------+--------------+ 8142 | Data-Digest (Optional) | 8143 +---------------+---------------+---------------+--------------+ 8145 Some Asynchronous Messages are strictly related to iSCSI while 8146 others are related to SCSI [SAM2]. 8148 StatSN counts this PDU as an acknowledgeable event (StatSN is 8149 advanced), which allows for initiator and target state 8150 synchronization. 8152 11.9.1. AsyncEvent 8154 The codes used for iSCSI Asynchronous Messages (events) are: 8156 0 (SCSI_ASYNC) - a SCSI Asynchronous Event is reported in the 8157 sense data. Sense Data that accompanies the report, in the 8158 data segment, identifies the condition. The sending of a 8159 SCSI Event (Asynchronous Event Reporting in SCSI 8160 terminology) is dependent on the target support for SCSI 8161 asynchronous event reporting (see [SAM2]) as indicated in 8162 the standard INQUIRY data (see [SPC3]). Its use may be 8163 enabled by parameters in the SCSI Control mode page (see 8164 [SPC3]). 8166 1 (REQUEST_LOGOUT) - target requests Logout. This Async 8167 Message MUST be sent on the same connection as the one 8168 requesting to be logged out. The initiator MUST honor this 8169 request by issuing a Logout as early as possible, but no 8170 later than Parameter3 seconds. Initiator MUST send a 8171 Logout with a reason code of "Close the connection" OR 8172 "Close the session" to close all the connections. Once this 8173 message is received, the initiator SHOULD NOT issue new 8174 iSCSI commands on the connection to be logged out. The 8175 target MAY reject any new I/O requests that it receives 8176 after this Message with the reason code "Waiting for 8177 Logout". If the initiator does not Logout in Parameter3 8178 seconds, the target should send an Async PDU with iSCSI 8179 event code "Dropped the connection" if possible, or simply 8180 terminate the transport connection. Parameter1 and 8181 Parameter2 are reserved. 8183 2 (CONNECTION_DROP) - target indicates it will drop the 8184 connection. 8186 The Parameter1 field indicates the CID of the connection 8187 going to be dropped. 8189 The Parameter2 field (Time2Wait) indicates, in seconds, the 8190 minimum time to wait before attempting to reconnect or 8191 reassign. 8193 The Parameter3 field (Time2Retain) indicates the maximum 8194 time allowed to reassign commands after the initial wait (in 8195 Parameter2). 8197 If the initiator does not attempt to reconnect and/or 8198 reassign the outstanding commands within the time specified 8199 by Parameter3, or if Parameter3 is 0, the target will 8200 terminate all outstanding commands on this connection. In 8201 this case, no other responses should be expected from the 8202 target for the outstanding commands on this connection. 8204 A value of 0 for Parameter2 indicates that reconnect can be 8205 attempted immediately. 8207 3 (SESSION_DROP) - target indicates it will drop all the 8208 connections of this session. 8210 Parameter1 field is reserved. 8212 The Parameter2 field (Time2Wait) indicates, in seconds, the 8213 minimum time to wait before attempting to reconnect. 8214 The Parameter3 field (Time2Retain) indicates the maximum 8215 time allowed to reassign commands after the initial wait (in 8216 Parameter2). 8218 If the initiator does not attempt to reconnect and/or 8219 reassign the outstanding commands within the time specified 8220 by Parameter3, or if Parameter3 is 0, the session is 8221 terminated. In this case, the target will terminate all 8222 outstanding commands in this session; no other responses 8223 should be expected from the target for the outstanding 8224 commands in this session. A value of 0 for Parameter2 8225 indicates that reconnect can be attempted immediately. 8227 4 (RENEGOTIATE) - target requests parameter negotiation on 8228 this connection. The initiator MUST honor this request by 8229 issuing a Text Request (that can be empty) on the same 8230 connection as early as possible, but no later than 8231 Parameter3 seconds, unless a Text Request is already pending 8232 on the connection, or by issuing a Logout Request. If the 8233 initiator does not issue a Text Request the target may 8234 reissue the Asynchronous Message requesting parameter 8235 negotiation. 8237 5 (FAST_ABORT) - all active tasks for LU with a matching LUN 8238 field in the Async Message PDU are being terminated. The 8239 receiving initiator iSCSI layer MUST respond to this Message 8240 by taking the following steps in order. 8242 - Stop Data-Out transfers on that connection for all active 8243 TTTs for the affected LUN quoted in the Async Message 8244 PDU. 8245 - Acknowledge the StatSN of the Async Message PDU via a NOP- 8246 Out PDU with ITT=0xffffffff (i.e., non-ping flavor), 8247 while copying the LUN field from the Async Message to 8248 NOP-Out. 8250 This value of AsyncEvent however MUST NOT be used on an 8251 iSCSI session unless the new TaskReporting text key defined 8252 in Section 13.23 was negotiated to FastAbort on the session. 8254 255 - vendor-specific iSCSI Event. The AsyncVCode details the 8255 vendor code, and data MAY accompany the report. 8257 All other event codes are reserved. 8259 11.9.2. AsyncVCode 8261 AsyncVCode is a vendor specific detail code that is only valid if 8262 the AsyncEvent field indicates a vendor specific event. Otherwise, 8263 it is reserved. 8265 11.9.3. LUN 8267 The LUN field MUST be valid if AsyncEvent is 0. Otherwise, this 8268 field is reserved. 8270 11.9.4. Sense Data and iSCSI Event Data 8272 For a SCSI event, this data accompanies the report in the data 8273 segment and identifies the condition. 8275 For an iSCSI event, additional vendor-unique data MAY accompany 8276 the Async event. Initiators MAY ignore the data when not 8277 understood while processing the rest of the PDU. 8279 If the DataSegmentLength is not 0, the format of the DataSegment 8280 is as follows: 8282 Byte/ 0 | 1 | 2 | 3 | 8283 / | | | | 8284 |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| 8285 +---------------+---------------+---------------+--------------+ 8286 0|SenseLength | Sense Data | 8287 +---------------+---------------+---------------+--------------+ 8288 x/ Sense Data / 8289 +---------------+---------------+---------------+--------------+ 8290 y/ iSCSI Event Data / 8291 / / 8292 +---------------+---------------+---------------+--------------+ 8293 z| 8295 11.9.4.1. SenseLength 8297 This is the length of Sense Data. When the Sense Data field is 8298 empty (e.g., the event is not a SCSI event) SenseLength is 0. 8300 11.10. Text Request 8302 The Text Request is provided to allow for the exchange of 8303 information and for future extensions. It permits the initiator to 8304 inform a target of its capabilities or to request some special 8305 operations. 8307 Byte/ 0 | 1 | 2 | 3 | 8308 / | | | | 8309 |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| 8310 +---------------+---------------+---------------+--------------+ 8311 0|.|I| 0x04 |F|C| Reserved | 8312 +---------------+---------------+---------------+--------------+ 8313 4|TotalAHSLength | DataSegmentLength | 8314 +---------------+---------------+---------------+--------------+ 8315 8| LUN or Reserved | 8316 + + 8317 12| | 8318 +---------------+---------------+---------------+--------------+ 8319 16| Initiator Task Tag | 8320 +---------------+---------------+---------------+--------------+ 8321 20| Target Transfer Tag or 0xffffffff | 8322 +---------------+---------------+---------------+--------------+ 8323 24| CmdSN | 8324 +---------------+---------------+---------------+--------------+ 8325 28| ExpStatSN | 8326 +---------------+---------------+---------------+--------------+ 8327 32/ Reserved / 8328 +/ / 8329 +---------------+---------------+---------------+--------------+ 8330 48| Header-Digest (Optional) | 8331 +---------------+---------------+---------------+--------------+ 8332 / DataSegment (Text) / 8333 +/ / 8334 +---------------+---------------+---------------+--------------+ 8335 | Data-Digest (Optional) | 8336 +---------------+---------------+---------------+--------------+ 8338 An initiator MUST NOT have more than one outstanding Text Request 8339 on a connection at any given time. 8341 On a connection failure, an initiator must either explicitly abort 8342 any active allegiant text negotiation task or must cause such a 8343 task to be implicitly terminated by the target. 8345 11.10.1. F (Final) Bit 8347 When set to 1, indicates that this is the last or only text 8348 request in a sequence of Text Requests; otherwise, it indicates 8349 that more Text Requests will follow. 8351 11.10.2. C (Continue) Bit 8353 When set to 1, indicates that the text (set of key=value pairs) in 8354 this Text Request is not complete (it will be continued on 8355 subsequent Text Requests); otherwise, it indicates that this Text 8356 Request ends a set of key=value pairs. A Text Request with the C 8357 bit set to 1 MUST have the F bit set to 0. 8359 11.10.3. Initiator Task Tag 8361 The initiator assigned identifier for this Text Request. If the 8362 command is sent as part of a sequence of text requests and 8363 responses, the Initiator Task Tag MUST be the same for all the 8364 requests within the sequence (similar to linked SCSI commands). 8365 The I bit for all requests in a sequence also MUST be the same. 8367 11.10.4. Target Transfer Tag 8369 When the Target Transfer Tag is set to the reserved value 8370 0xffffffff, it tells the target that this is a new request and the 8371 target resets any internal state associated with the Initiator 8372 Task Tag (resets the current negotiation state). 8374 The target sets the Target Transfer Tag in a text response to a 8375 value other than the reserved value 0xffffffff whenever it 8376 indicates that it has more data to send or more operations to 8377 perform that are associated with the specified Initiator Task Tag. 8378 It MUST do so whenever it sets the F bit to 0 in the response. By 8379 copying the Target Transfer Tag from the response to the next Text 8380 Request, the initiator tells the target to continue the operation 8381 for the specific Initiator Task Tag. The initiator MUST ignore the 8382 Target Transfer Tag in the Text Response when the F bit is set to 8383 1. 8385 This mechanism allows the initiator and target to transfer a large 8386 amount of textual data over a sequence of text-command/text- 8387 response exchanges, or to perform extended negotiation sequences. 8389 If the Target Transfer Tag is not 0xffffffff, the LUN field MUST 8390 be sent by the target in the Text Response. 8392 A target MAY reset its internal negotiation state if an exchange 8393 is stalled by the initiator for a long time or if it is running 8394 out of resources. 8396 Long text responses are handled as in the following example: 8398 I->T Text SendTargets=All (F=1,TTT=0xffffffff) 8400 T->I Text (F=0,TTT=0x12345678) 8402 I->T Text (F=1, TTT=0x12345678) 8404 T->I Text (F=0, TTT=0x12345678) 8406 I->T Text (F=1, TTT=0x12345678) 8408 ... 8410 T->I Text (F=1, TTT=0xffffffff) 8412 11.10.5. Text 8414 The data lengths of a text request MUST NOT exceed the iSCSI 8415 target MaxRecvDataSegmentLength (a per connection and per 8416 direction negotiated parameter). The text format is specified in 8417 Section 6.2. 8419 Section 12 and Section 13 list some basic Text key=value pairs, 8420 some of which can be used in Login Request/Response and some in 8421 Text Request/Response. 8423 A key=value pair can span Text request or response boundaries. A 8424 key=value pair can start in one PDU and continue on the next. In 8426 other words the end of a PDU does not necessarily signal the end 8427 of a key=value pair. 8429 The target responds by sending its response back to the initiator. 8430 The response text format is similar to the request text format. 8431 The text response MAY refer to key=value pairs presented in an 8432 earlier text request and the text in the request may refer to 8433 earlier responses. 8435 Section 6.2 details the rules for the Text Requests and Responses. 8437 Text operations are usually meant for parameter 8438 setting/negotiations, but can also be used to perform some long 8439 lasting operations. 8441 Text operations that take a long time should be placed in their 8442 own Text request. 8444 11.11. Text Response 8446 The Text Response PDU contains the target's responses to the 8447 initiator's Text request. The format of the Text field matches 8448 that of the Text request. 8450 Byte/ 0 | 1 | 2 | 3 | 8451 / | | | | 8452 |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| 8453 +---------------+---------------+---------------+--------------+ 8454 0|.|.| 0x24 |F|C| Reserved | 8455 +---------------+---------------+---------------+--------------+ 8456 4|TotalAHSLength | DataSegmentLength | 8457 +---------------+---------------+---------------+--------------+ 8458 8| LUN or Reserved | 8459 + + 8460 12| | 8461 +---------------+---------------+---------------+--------------+ 8462 16| Initiator Task Tag | 8463 +---------------+---------------+---------------+--------------+ 8464 20| Target Transfer Tag or 0xffffffff | 8465 +---------------+---------------+---------------+--------------+ 8466 24| StatSN | 8467 +---------------+---------------+---------------+--------------+ 8468 28| ExpCmdSN | 8469 +---------------+---------------+---------------+--------------+ 8470 32| MaxCmdSN | 8471 +---------------+---------------+---------------+--------------+ 8472 36/ Reserved / 8473 +/ / 8474 +---------------+---------------+---------------+--------------+ 8475 48| Header-Digest (Optional) | 8476 +---------------+---------------+---------------+--------------+ 8477 / DataSegment (Text) / 8478 +/ / 8479 +---------------+---------------+---------------+--------------+ 8480 | Data-Digest (Optional) | 8481 +---------------+---------------+---------------+--------------+ 8483 11.11.1. F (Final) Bit 8485 When set to 1, in response to a Text Request with the Final bit 8486 set to 1, the F bit indicates that the target has finished the 8487 whole operation. Otherwise, if set to 0 in response to a Text 8488 Request with the Final Bit set to 1, it indicates that the target 8489 has more work to do (invites a follow-on text request). A Text 8490 Response with the F bit set to 1 in response to a Text Request 8491 with the F bit set to 0 is a protocol error. 8493 A Text Response with the F bit set to 1 MUST NOT contain key=value 8494 pairs that may require additional answers from the initiator. 8496 A Text Response with the F bit set to 1 MUST have a Target 8497 Transfer Tag field set to the reserved value of 0xffffffff. 8499 A Text Response with the F bit set to 0 MUST have a Target 8500 Transfer Tag field set to a value other than the reserved 8501 0xffffffff. 8503 11.11.2. C (Continue) Bit 8505 When set to 1, indicates that the text (set of key=value pairs) in 8506 this Text Response is not complete (it will be continued on 8507 subsequent Text Responses); otherwise, it indicates that this Text 8508 Response ends a set of key=value pairs. A Text Response with the C 8509 bit set to 1 MUST have the F bit set to 0. 8511 11.11.3. Initiator Task Tag 8513 The Initiator Task Tag matches the tag used in the initial Text 8514 Request. 8516 11.11.4. Target Transfer Tag 8518 When a target has more work to do (e.g., cannot transfer all the 8519 remaining text data in a single Text Response or has to continue 8520 the negotiation) and has enough resources to proceed, it MUST set 8521 the Target Transfer Tag to a value other than the reserved value 8522 of 0xffffffff. Otherwise, the Target Transfer Tag MUST be set to 8523 0xffffffff. 8525 When the Target Transfer Tag is not 0xffffffff, the LUN field may 8526 be significant. 8528 The initiator MUST copy the Target Transfer Tag and LUN in its 8529 next request to indicate that it wants the rest of the data. 8531 When the target receives a Text Request with the Target Transfer 8532 Tag set to the reserved value of 0xffffffff, it resets its 8533 internal information (resets state) associated with the given 8534 Initiator Task Tag (restarts the negotiation). 8536 When a target cannot finish the operation in a single Text 8537 Response, and does not have enough resources to continue, it 8538 rejects the Text Request with the appropriate Reject code. 8540 A target may reset its internal state associated with an Initiator 8541 Task Tag (the current negotiation state), state expressed through 8542 the Target Transfer Tag if the initiator fails to continue the 8543 exchange for some time. The target may reject subsequent Text 8544 Requests with the Target Transfer Tag set to the "stale" value. 8546 11.11.5. StatSN 8548 The target StatSN variable is advanced by each Text Response sent. 8550 11.11.6. Text Response Data 8552 The data lengths of a text response MUST NOT exceed the iSCSI 8553 initiator MaxRecvDataSegmentLength (a per connection and per 8554 direction negotiated parameter). 8556 The text in the Text Response Data is governed by the same rules 8557 as the text in the Text Request Data (see Section 11.11.2). 8559 Although the initiator is the requesting party and controls the 8560 request-response initiation and termination, the target can offer 8561 key=value pairs of its own as part of a sequence and not only in 8562 response to the initiator. 8564 11.12. Login Request 8566 After establishing a TCP connection between an initiator and a 8567 target, the initiator MUST start a Login Phase to gain further 8568 access to the target's resources. 8570 The Login Phase (see Section 6.3) consists of a sequence of Login 8571 requests and responses that carry the same Initiator Task Tag. 8573 Login requests are always considered as immediate. 8575 Byte/ 0 | 1 | 2 | 3 | 8576 / | | | | 8577 |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| 8578 +---------------+---------------+---------------+--------------+ 8579 0|.|1| 0x03 |T|C|.|.|CSG|NSG| Version-max | Version-min | 8580 +---------------+---------------+---------------+--------------+ 8581 4|TotalAHSLength | DataSegmentLength | 8582 +---------------+---------------+---------------+--------------+ 8583 8| ISID | 8584 + +---------------+--------------+ 8585 12| | TSIH | 8586 +---------------+---------------+---------------+--------------+ 8587 16| Initiator Task Tag | 8588 +---------------+---------------+---------------+--------------+ 8589 20| CID | Reserved | 8590 +---------------+---------------+---------------+--------------+ 8591 24| CmdSN | 8592 +---------------+---------------+---------------+--------------+ 8593 28| ExpStatSN or Reserved | 8594 +---------------+---------------+---------------+--------------+ 8595 32| Reserved | 8596 +---------------+---------------+---------------+--------------+ 8597 36| Reserved | 8598 +---------------+---------------+---------------+--------------+ 8599 40/ Reserved / 8600 +/ / 8601 +---------------+---------------+---------------+--------------+ 8602 48/ DataSegment - Login Parameters in Text request Format / 8603 +/ / 8604 +---------------+---------------+---------------+--------------+ 8606 11.12.1. T (Transit) Bit 8608 If set to 1, indicates that the initiator is ready to transit to 8609 the next stage. 8611 If the T bit is set to 1 and NSG is FullFeaturePhase, then this 8612 also indicates that the initiator is ready for the Final Login 8613 Response (see Section 6.3). 8615 11.12.2. C (Continue) Bit 8617 When set to 1, this bit indicates that the text (set of key=value 8618 pairs) in this Login Request is not complete (it will be continued 8619 on subsequent Login Requests); otherwise, it indicates that this 8620 Login Request ends a set of key=value pairs. A Login Request with 8621 the C bit set to 1 MUST have the T bit set to 0. 8623 11.12.3. CSG and NSG 8625 Through these fields, Current Stage (CSG) and Next Stage (NSG), 8626 the Login negotiation requests and responses are associated with a 8627 specific stage in the session (SecurityNegotiation, 8628 LoginOperationalNegotiation, FullFeaturePhase) and may indicate 8629 the next stage to which they want to move (see Section 6.3). The 8630 next stage value is only valid when the T bit is 1; otherwise, it 8631 is reserved. 8633 The stage codes are: 8635 - 0 - SecurityNegotiation 8637 - 1 - LoginOperationalNegotiation 8639 - 3 - FullFeaturePhase 8641 All other codes are reserved. 8643 11.12.4. Version 8645 The version number of the current draft is 0x00. As such, all 8646 devices MUST carry version 0x00 for both Version-min and Version- 8647 max. 8649 11.12.4.1. Version-max 8651 Maximum Version number supported. 8653 All Login requests within the Login Phase MUST carry the same 8654 Version-max. 8656 The target MUST use the value presented with the first login 8657 request. 8659 11.12.4.2. Version-min 8661 All Login requests within the Login Phase MUST carry the same 8662 Version-min. The target MUST use the value presented with the 8663 first login request. 8665 11.12.5. ISID 8667 This is an initiator-defined component of the session identifier 8668 and is structured as follows (see Section 10.1.1 for details): 8670 Byte/ 0 | 1 | 2 | 3 | 8671 / | | | | 8672 |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| 8673 +---------------+---------------+---------------+--------------+ 8674 8| T | A | B | C | 8675 +---------------+---------------+---------------+--------------+ 8676 12| D | 8677 +---------------+---------------+ 8679 The T field identifies the format and usage of A, B, C, and D as 8680 indicated below: 8682 T 8684 00b OUI-Format 8686 A&B are a 22 bit OUI 8688 (the I/G & U/L bits are omitted) 8690 C&D 24 bit qualifier 8692 01b EN - Format (IANA Enterprise Number) 8694 A - Reserved 8696 B&C EN (IANA Enterprise Number) 8698 D - Qualifier 8700 10b "Random" 8702 A - Reserved 8704 B&C Random 8706 D - Qualifier 8708 11b A,B,C&D Reserved 8710 For the T field values 00b and 01b, a combination of A and B (for 8711 00b) or B and C (for 01b) identifies the vendor or organization 8712 whose component (software or hardware) generates this ISID. A 8713 vendor or organization with one or more OUIs, or one or more 8714 Enterprise Numbers, MUST use at least one of these numbers and 8715 select the appropriate value for the T field when its components 8716 generate ISIDs. An OUI or EN MUST be set in the corresponding 8717 fields in network byte order (byte big-endian). 8719 If the T field is 10b, B and C are set to a random 24-bit unsigned 8720 integer value in network byte order (byte big-endian). See 8721 [RFC3721] for how this affects the principle of "conservative 8722 reuse". 8724 The Qualifier field is a 16 or 24-bit unsigned integer value that 8725 provides a range of possible values for the ISID within the 8726 selected namespace. It may be set to any value within the 8727 constraints specified in the iSCSI protocol (see Section 4.4.3 and 8728 Section 10.1.1). 8730 The T field value of 11b is reserved. 8732 If the ISID is derived from something assigned to a hardware 8733 adapter or interface by a vendor, as a preset default value, it 8734 MUST be configurable to a value assigned according to the SCSI 8735 port behavior desired by the system in which it is installed (see 8736 Section 10.1.1 and Section 10.1.2). The resultant ISID MUST also 8737 be persistent over power cycles, reboot, card swap, etc. 8739 11.12.6. TSIH 8741 TSIH must be set in the first Login Request. The reserved value 0 8742 MUST be used on the first connection for a new session. Otherwise, 8743 the TSIH sent by the target at the conclusion of the successful 8744 login of the first connection for this session MUST be used. The 8745 TSIH identifies to the target the associated existing session for 8746 this new connection. 8748 All Login requests within a Login Phase MUST carry the same TSIH. 8750 The target MUST check the value presented with the first login 8751 request and act as specified in Section 5.3.1. 8753 11.12.7. Connection ID - CID 8755 A unique ID for this connection within the session. 8757 All Login requests within the Login Phase MUST carry the same CID. 8759 The target MUST use the value presented with the first login 8760 request. 8762 A Login request with a non-zero TSIH and a CID equal to that of an 8763 existing connection implies a logout of the connection followed by 8764 a Login (see Section 6.3.4). For the details of the implicit 8765 Logout Request, see Section 11.14. 8767 11.12.8. CmdSN 8769 CmdSN is either the initial command sequence number of a session 8770 (for the first Login request of a session - the "leading" login), 8771 or the command sequence number in the command stream if the login 8772 is for a new connection in an existing session. 8774 Examples: 8776 - Login on a leading connection - if the leading login carries 8777 the CmdSN 123, all other login requests in the same login 8778 phase carry the CmdSN 123 and the first non-immediate 8779 command in FullFeaturePhase also carries the CmdSN 123. 8781 - Login on other than a leading connection - if the current 8782 CmdSN at the time the first login on the connection is 8783 issued is 500, then that PDU carries CmdSN=500. Subsequent 8784 login requests that are needed to complete this login phase 8785 may carry a CmdSN higher than 500 if non-immediate requests 8786 that were issued on other connections in the same session 8787 advance CmdSN. 8789 If the login request is a leading login request, the target MUST 8790 use the value presented in CmdSN as the target value for ExpCmdSN. 8792 11.12.9. ExpStatSN 8794 For the first Login Request on a connection this is ExpStatSN for 8795 the old connection and this field is only valid if the Login 8796 request restarts a connection (see Section 6.3.4). 8798 For subsequent Login Requests it is used to acknowledge the Login 8799 Responses with their increasing StatSN values. 8801 11.12.10. Login Parameters 8803 The initiator MUST provide some basic parameters in order to 8804 enable the target to determine if the initiator may use the 8805 target's resources and the initial text parameters for the 8806 security exchange. 8808 All the rules specified in Section 11.10.5 for text requests also 8809 hold for login requests. Keys and their explanations are listed 8810 in Section 12 (security negotiation keys) and Section 13 8811 (operational parameter negotiation keys). All keys in Section 13, 8812 except for the X extension formats, MUST be supported by iSCSI 8813 initiators and targets. Keys in Section 12 only need to be 8814 supported when the function to which they refer is mandatory to 8815 implement. 8817 11.13. Login Response 8819 The Login Response indicates the progress and/or end of the Login 8820 Phase. 8822 Byte/ 0 | 1 | 2 | 3 | 8823 / | | | | 8824 |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| 8825 +---------------+---------------+---------------+--------------+ 8826 0|.|.| 0x23 |T|C|.|.|CSG|NSG| Version-max |Version-active| 8827 +---------------+---------------+---------------+--------------+ 8828 4|TotalAHSLength | DataSegmentLength | 8829 +---------------+---------------+---------------+--------------+ 8830 8| ISID | 8831 + +---------------+--------------+ 8832 12| | TSIH | 8833 +---------------+---------------+---------------+--------------+ 8834 16| Initiator Task Tag | 8835 +---------------+---------------+---------------+--------------+ 8836 20| Reserved | 8837 +---------------+---------------+---------------+--------------+ 8838 24| StatSN | 8839 +---------------+---------------+---------------+--------------+ 8840 28| ExpCmdSN | 8841 +---------------+---------------+---------------+--------------+ 8842 32| MaxCmdSN | 8843 +---------------+---------------+---------------+--------------+ 8844 36| Status-Class | Status-Detail | Reserved | 8845 +---------------+---------------+---------------+--------------+ 8846 40/ Reserved / 8847 +/ / 8848 +---------------+---------------+---------------+--------------+ 8849 48/ DataSegment - Login Parameters in Text request Format / 8850 +/ / 8851 +---------------+---------------+---------------+--------------+ 8853 11.13.1. Version-max 8855 This is the highest version number supported by the target. 8857 All Login responses within the Login Phase MUST carry the same 8858 Version-max. 8860 The initiator MUST use the value presented as a response to the 8861 first login request. 8863 11.13.2. Version-active 8865 Indicates the highest version supported by the target and 8866 initiator. If the target does not support a version within the 8867 range specified by the initiator, the target rejects the login and 8868 this field indicates the lowest version supported by the target. 8870 All Login responses within the Login Phase MUST carry the same 8871 Version-active. 8873 The initiator MUST use the value presented as a response to the 8874 first login request. 8876 11.13.3. TSIH 8878 The TSIH is the target assigned session identifying handle. Its 8879 internal format and content are not defined by this protocol 8880 except for the value 0 that is reserved. With the exception of the 8881 Login Final-Response in a new session, this field should be set to 8882 the TSIH provided by the initiator in the Login Request. For a 8883 new session, the target MUST generate a non-zero TSIH and ONLY 8884 return it in the Login Final-Response (see Section 6.3). 8886 11.13.4. StatSN 8888 For the first Login Response (the response to the first Login 8889 Request), this is the starting status Sequence Number for the 8890 connection. The next response of any kind, including the next 8891 login response, if any, in the same Login Phase, will carry this 8892 number + 1. This field is only valid if the Status-Class is 0. 8894 11.13.5. Status-Class and Status-Detail 8896 The Status returned in a Login Response indicates the execution 8897 status of the Login Phase. The status includes: 8899 Status-Class 8901 Status-Detail 8903 0 Status-Class indicates success. 8905 A non-zero Status-Class indicates an exception. In this case, 8906 Status-Class is sufficient for a simple initiator to use when 8907 handling exceptions, without having to look at the Status-Detail. 8908 The Status-Detail allows finer-grained exception handling for more 8909 sophisticated initiators and for better information for logging. 8911 The status classes are as follows: 8913 0 - Success - indicates that the iSCSI target successfully 8914 received, understood, and accepted the request. The 8915 numbering fields (StatSN, ExpCmdSN, MaxCmdSN) are only valid 8916 if Status-Class is 0. 8918 1 - Redirection - indicates that the initiator must take 8919 further action to complete the request. This is usually due 8920 to the target moving to a different address. All of the 8921 redirection status class responses MUST return one or more 8922 text key parameters of the type "TargetAddress", which 8923 indicates the target's new address. A redirection response 8924 MAY be issued by a target prior or after completing a 8925 security negotiation if a security negotiation is required. 8926 A redirection SHOULD be accepted by an initiator even 8927 without having the target complete a security negotiation if 8928 any security negotiation is required, and MUST be accepted 8929 by the initiator after the completion of the security 8930 negotiation if any security negotiation is required. 8932 2 - Initiator Error (not a format error) - indicates that the 8933 initiator most likely caused the error. This MAY be due to a 8934 request for a resource for which the initiator does not have 8935 permission. The request should not be tried again. 8937 3 - Target Error - indicates that the target sees no errors in 8938 the initiator's login request, but is currently incapable of 8939 fulfilling the request. The initiator may re-try the same 8940 login request later. 8942 The table below shows all of the currently allocated status codes. 8943 The codes are in hexadecimal; the first byte is the status class 8944 and the second byte is the status detail. 8946 ----------------------------------------------------------------- 8947 Status | Code | Description 8948 |(hex) | 8949 ----------------------------------------------------------------- 8950 Success | 0000 | Login is proceeding OK (*1). 8951 ----------------------------------------------------------------- 8952 Target moved | 0101 | The requested iSCSI Target Name (ITN) 8953 temporarily | | has temporarily moved 8954 | | to the address provided. 8955 ----------------------------------------------------------------- 8956 Target moved | 0102 | The requested ITN has permanently moved 8957 permanently | | to the address provided. 8958 ----------------------------------------------------------------- 8959 Initiator | 0200 | Miscellaneous iSCSI initiator 8960 error | | errors. 8961 ---------------------------------------------------------------- 8962 Authentication| 0201 | The initiator could not be 8963 failure | | successfully authenticated or target 8964 | | authentication is not supported. 8965 ----------------------------------------------------------------- 8966 Authorization | 0202 | The initiator is not allowed access 8967 failure | | to the given target. 8968 ----------------------------------------------------------------- 8969 Not found | 0203 | The requested ITN does not 8970 | | exist at this address. 8971 ----------------------------------------------------------------- 8972 Target removed| 0204 | The requested ITN has been removed and 8973 | | no forwarding address is provided. 8974 ----------------------------------------------------------------- 8975 Unsupported | 0205 | The requested iSCSI version range is 8976 version | | not supported by the target. 8977 ----------------------------------------------------------------- 8978 Too many | 0206 | Too many connections on this SSID. 8979 connections | | 8980 ----------------------------------------------------------------- 8981 Missing | 0207 | Missing parameters (e.g., iSCSI 8982 parameter | | Initiator and/or Target Name). 8983 ----------------------------------------------------------------- 8984 Can't include | 0208 | Target does not support session 8985 in session | | spanning to this connection (address). 8986 ----------------------------------------------------------------- 8987 Session type | 0209 | Target does not support this type of 8988 not supported | | of session or not from this Initiator. 8989 ----------------------------------------------------------------- 8990 Session does | 020a | Attempt to add a connection 8991 not exist | | to a non-existent session. 8992 ----------------------------------------------------------------- 8993 Invalid during| 020b | Invalid Request type during Login. 8994 login | | 8995 ----------------------------------------------------------------- 8996 Target error | 0300 | Target hardware or software error. 8997 ----------------------------------------------------------------- 8998 Service | 0301 | The iSCSI service or target is not 8999 unavailable | | currently operational. 9000 ----------------------------------------------------------------- 9001 Out of | 0302 | The target has insufficient session, 9002 resources | | connection, or other resources. 9003 ----------------------------------------------------------------- 9005 (*1)If the response T bit is 1 in both the request and the 9006 matching response, and the NSG is FullFeaturePhase in both the 9007 request and the matching response, the Login Phase is finished and 9008 the initiator may proceed to issue SCSI commands. 9010 If the Status Class is not 0, the initiator and target MUST close 9011 the TCP connection. 9013 If the target wishes to reject the login request for more than one 9014 reason, it should return the primary reason for the rejection. 9016 11.13.6. T (Transit) bit 9018 The T bit is set to 1 as an indicator of the end of the stage. If 9019 the T bit is set to 1 and NSG is FullFeaturePhase, then this is 9020 also the Final Login Response (see Section 6.3). A T bit of 0 9021 indicates a "partial" response, which means "more negotiation 9022 needed". 9024 A login response with a T bit set to 1 MUST NOT contain key=value 9025 pairs that may require additional answers from the initiator 9026 within the same stage. 9028 If the status class is 0, the T bit MUST NOT be set to 1 if the T 9029 bit in the request was set to 0. 9031 11.13.7. C (Continue) Bit 9033 When set to 1, indicates that the text (set of key=value pairs) in 9034 this Login Response is not complete (it will be continued on 9035 subsequent Login Responses); otherwise, it indicates that this 9036 Login Response ends a set of key=value pairs. A Login Response 9037 with the C bit set to 1 MUST have the T bit set to 0. 9039 11.13.8. Login Parameters 9041 The target MUST provide some basic parameters in order to enable 9042 the initiator to determine if it is connected to the correct port 9043 and the initial text parameters for the security exchange. 9045 All the rules specified in Section 11.11.6 for text responses also 9046 hold for login responses. Keys and their explanations are listed 9047 in Section 12(security negotiation keys) and Section 13 9048 (operational parameter negotiation keys). All keys in Section 13, 9049 except for the X extension formats, MUST be supported by iSCSI 9050 initiators and targets. Keys in Section 12, only need to be 9051 supported when the function to which they refer is mandatory to 9052 implement. 9054 11.14. Logout Request 9056 The Logout request is used to perform a controlled closing of a 9057 connection. 9059 An initiator MAY use a logout request to remove a connection from 9060 a session or to close an entire session. 9062 After sending the Logout request PDU, an initiator MUST NOT send 9063 any new iSCSI requests on the closing connection. If the Logout 9064 request is intended to close the session, new iSCSI requests MUST 9065 NOT be sent on any of the connections participating in the 9066 session. 9068 When receiving a Logout request with the reason code of "close the 9069 connection" or "close the session", the target MUST terminate all 9070 pending commands, whether acknowledged via ExpCmdSN or not, on 9071 that connection or session respectively. 9073 When receiving a Logout request with the reason code "remove 9074 connection for recovery", the target MUST discard all requests not 9075 yet acknowledged via ExpCmdSN that were issued on the specified 9076 connection, and suspend all data/status/R2T transfers on behalf of 9077 pending commands on the specified connection. 9079 The target then issues the Logout response and half-closes the TCP 9080 connection (sends FIN). After receiving the Logout response and 9081 attempting to receive the FIN (if still possible), the initiator 9082 MUST completely close the logging-out connection. For the 9083 terminated commands, no additional responses should be expected. 9085 A Logout for a CID may be performed on a different transport 9086 connection when the TCP connection for the CID has already been 9087 terminated. In such a case, only a logical "closing" of the iSCSI 9088 connection for the CID is implied with a Logout. 9090 All commands that were not terminated or not completed (with 9091 status) and acknowledged when the connection is closed completely 9092 can be reassigned to a new connection if the target supports 9093 connection recovery. 9095 If an initiator intends to start recovery for a failing 9096 connection, it MUST use the Logout request to "clean-up" the 9097 target end of a failing connection and enable recovery to start, 9098 or the Login request with a non-zero TSIH and the same CID on a 9099 new connection for the same effect. In sessions with a single 9100 connection, the connection can be closed and then a new connection 9101 reopened. A connection reinstatement login can be used for 9102 recovery (see Section 6.3.4). 9104 A successful completion of a logout request with the reason code 9105 of "close the connection" or "remove the connection for recovery" 9106 results at the target in the discarding of unacknowledged commands 9107 received on the connection being logged out. These are commands 9108 that have arrived on the connection being logged out, but have not 9109 been delivered to SCSI because one or more commands with a smaller 9110 CmdSN has not been received by iSCSI. See Section 4.2.2.1. The 9111 resulting holes in the command sequence numbers will have to be 9112 handled by appropriate recovery (see Section 7) unless the session 9113 is also closed. 9115 The entire logout discussion in this Section is also applicable 9116 for an implicit Logout realized by way of a connection 9117 reinstatement or session reinstatement. When a Login Request 9118 performs an implicit Logout, the implicit Logout is performed as 9119 if having the reason codes specified below: 9121 Reason code Type of implicit Logout 9123 ------------------------------------------- 9125 0 session reinstatement 9127 1 connection reinstatement when the operational 9128 ErrorRecoveryLevel < 2 9130 2 connection reinstatement when the operational 9131 ErrorRecoveryLevel = 2 9133 Byte/ 0 | 1 | 2 | 3 | 9134 / | | | | 9135 |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| 9136 +---------------+---------------+---------------+--------------+ 9137 0|.|I| 0x06 |1| Reason Code | Reserved | 9138 +---------------+---------------+---------------+--------------+ 9139 4|TotalAHSLength | DataSegmentLength | 9140 +--------------------------------------------------------------+ 9141 8/ Reserved / 9142 +/ / 9143 +---------------+---------------+---------------+--------------+ 9144 16| Initiator Task Tag | 9145 +---------------+---------------+---------------+--------------+ 9146 20| CID or Reserved | Reserved | 9147 +---------------+---------------+---------------+--------------+ 9148 24| CmdSN | 9149 +---------------+---------------+---------------+--------------+ 9150 28| ExpStatSN | 9151 +---------------+---------------+---------------+--------------+ 9152 32/ Reserved / 9153 +/ / 9154 +---------------+---------------+---------------+--------------+ 9155 48| Header-Digest (Optional) | 9156 +---------------+---------------+---------------+--------------+ 9158 11.14.1. Reason Code 9160 Reason Code indicates the reason for Logout as follows: 9162 0 - close the session. All commands associated with the 9163 session (if any) are terminated. 9165 1 - close the connection. All commands associated with 9166 connection (if any) are terminated. 9168 2 - remove the connection for recovery. Connection is closed 9169 and all commands associated with it, if any, are to be 9170 prepared for a new allegiance. 9172 All other values are reserved. 9174 11.14.2. TotalAHSLength and DataSegmentLength 9176 For this PDU TotalAHSLength and DataSegmentLength MUST be 0. 9178 11.14.3. CID 9180 This is the connection ID of the connection to be closed 9181 (including closing the TCP stream). This field is only valid if 9182 the reason code is not "close the session". 9184 11.14.4. ExpStatSN 9186 This is the last ExpStatSN value for the connection to be closed. 9188 11.14.5. Implicit termination of tasks 9190 A target implicitly terminates the active tasks due to the iSCSI 9191 protocol in the following cases: 9193 a) When a connection is implicitly or explicitly logged out 9194 with the reason code of "Close the connection" and there 9195 are active tasks allegiant to that connection. 9197 b) When a connection fails and eventually the connection state 9198 times out (state transition M1 in Section 8.2.2) and there 9199 are active tasks allegiant to that connection. 9201 c) When a successful recovery Logout is performed while there 9202 are active tasks allegiant to that connection, and those 9203 tasks eventually time out after the Time2Wait and 9204 Time2Retain periods without allegiance reassignment. 9206 d) When a connection is implicitly or explicitly logged out 9207 with the reason code of "Close the session" and there are 9208 active tasks in that session. 9210 If the tasks terminated in any of the above cases are SCSI tasks, 9211 they must be internally terminated as if with CHECK CONDITION 9212 status. This status is only meaningful for appropriately handling 9214 the internal SCSI state and SCSI side effects with respect to 9215 ordering because this status is never communicated back as a 9216 terminating status to the initiator. However additional actions 9217 may have to be taken at SCSI level depending on the SCSI context 9218 as defined by the SCSI standards (e.g., queued commands and ACA, 9219 UA for the next command on the I_T nexus in cases a), b), and c), 9220 after the tasks are terminated, the target MUST report a Unit 9221 Attention condition on the next command processed on any 9222 connection for each affected I_T_L nexus with the status of CHECK 9223 CONDITION, and the ASC/ASCQ value of 47h/7Fh - "SOME COMMANDS 9224 CLEARED BY ISCSI PROTOCOL EVENT" - etc. - see [SPC3]). 9226 11.15. Logout Response 9228 The logout response is used by the target to indicate if the 9229 cleanup operation for the connection(s) has completed. 9231 After Logout, the TCP connection referred by the CID MUST be 9232 closed at both ends (or all connections must be closed if the 9233 logout reason was session close). 9235 Byte/ 0 | 1 | 2 | 3 | 9236 / | | | | 9237 |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| 9238 +---------------+---------------+---------------+--------------+ 9239 0|.|.| 0x26 |1| Reserved | Response | Reserved | 9240 +---------------+---------------+---------------+--------------+ 9241 4|TotalAHSLength | DataSegmentLength | 9242 +--------------------------------------------------------------+ 9243 8/ Reserved / 9244 +/ / 9245 +---------------+---------------+---------------+--------------+ 9246 16| Initiator Task Tag | 9247 +---------------+---------------+---------------+--------------+ 9248 20| Reserved | 9249 +---------------+---------------+---------------+--------------+ 9250 24| StatSN | 9251 +---------------+---------------+---------------+--------------+ 9252 28| ExpCmdSN | 9253 +---------------+---------------+---------------+--------------+ 9254 32| MaxCmdSN | 9255 +---------------+---------------+---------------+--------------+ 9256 36| Reserved | 9257 +--------------------------------------------------------------+ 9258 40| Time2Wait | Time2Retain | 9259 +---------------+---------------+---------------+--------------+ 9260 44| Reserved | 9261 +---------------+---------------+---------------+--------------+ 9262 48| Header-Digest (Optional) | 9263 +---------------+---------------+---------------+--------------+ 9265 11.15.1. Response 9267 Logout response: 9269 0 - connection or session closed successfully. 9271 1 - CID not found. 9273 2 - connection recovery is not supported. If Logout reason 9274 code was recovery and target does not support it as 9275 indicated by the ErrorRecoveryLevel. 9276 3 - cleanup failed for various reasons. 9278 11.15.2. TotalAHSLength and DataSegmentLength 9280 For this PDU TotalAHSLength and DataSegmentLength MUST be 0. 9282 11.15.3. Time2Wait 9284 If the Logout response code is 0 and if the operational 9285 ErrorRecoveryLevel is 2, this is the minimum amount of time, in 9286 seconds, to wait before attempting task reassignment. If the 9287 Logout response code is 0 and if the operational 9288 ErrorRecoveryLevel is less than 2, this field is to be ignored. 9290 This field is invalid if the Logout response code is 1. 9292 If the Logout response code is 2 or 3, this field specifies the 9293 minimum time to wait before attempting a new implicit or explicit 9294 logout. 9296 If Time2Wait is 0, the reassignment or a new Logout may be 9297 attempted immediately. 9299 11.15.4. Time2Retain 9301 If the Logout response code is 0 and if the operational 9302 ErrorRecoveryLevel is 2, this is the maximum amount of time, in 9303 seconds, after the initial wait (Time2Wait), the target waits for 9304 the allegiance reassignment for any active task after which the 9305 task state is discarded. If the Logout response code is 0 and if 9306 the operational ErrorRecoveryLevel is less than 2, this field is 9307 to be ignored. 9309 This field is invalid if the Logout response code is 1. 9311 If the Logout response code is 2 or 3, this field specifies the 9312 maximum amount of time, in seconds, after the initial wait 9313 (Time2Wait), the target waits for a new implicit or explicit 9314 logout. 9316 If it is the last connection of a session, the whole session state 9317 is discarded after Time2Retain. 9319 If Time2Retain is 0, the target has already discarded the 9320 connection (and possibly the session) state along with the task 9321 states. No reassignment or Logout is required in this case. 9323 11.16. SNACK Request 9325 Byte/ 0 | 1 | 2 | 3 | 9326 / | | | | 9327 |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| 9328 +---------------+---------------+---------------+--------------+ 9329 0|.|.| 0x10 |1|.|.|.| Type | Reserved | 9330 +---------------+---------------+---------------+--------------+ 9331 4|TotalAHSLength | DataSegmentLength | 9332 +---------------+---------------+---------------+--------------+ 9333 8| LUN or Reserved | 9334 + + 9335 12| | 9336 +---------------+---------------+---------------+--------------+ 9337 16| Initiator Task Tag or 0xffffffff | 9338 +---------------+---------------+---------------+--------------+ 9339 20| Target Transfer Tag or SNACK Tag or 0xffffffff | 9340 +---------------+---------------+---------------+--------------+ 9341 24| Reserved | 9342 +---------------+---------------+---------------+--------------+ 9343 28| ExpStatSN | 9344 +---------------+---------------+---------------+--------------+ 9345 32/ Reserved / 9346 +/ / 9347 +---------------+---------------+---------------+--------------+ 9348 40| BegRun | 9349 +--------------------------------------------------------------+ 9350 44| RunLength | 9351 +--------------------------------------------------------------+ 9352 48| Header-Digest (Optional) | 9353 +---------------+---------------+---------------+--------------+ 9355 If the implementation supports ErrorRecoveryLevel greater than 9356 zero, it MUST support all SNACK types. 9358 The SNACK is used by the initiator to request the retransmission 9359 of numbered-responses, data, or R2T PDUs from the target. The 9360 SNACK request indicates the numbered-responses or data "runs" 9361 whose retransmission is requested by the target, where the run 9362 starts with the first StatSN, DataSN, or R2TSN whose 9363 retransmission is requested and indicates the number of Status, 9364 Data, or R2T PDUs requested including the first. 0 has special 9365 meaning when used as a starting number and length: 9367 - When used in RunLength, it means all PDUs starting with the 9368 initial. 9370 - When used in both BegRun and RunLength, it means all 9371 unacknowledged PDUs. 9373 The numbered-response(s) or R2T(s), requested by a SNACK, MUST be 9374 delivered as exact replicas of the ones that the target 9375 transmitted originally except for the fields ExpCmdSN, MaxCmdSN, 9376 and ExpDataSN, which MUST carry the current values. 9377 R2T(s)requested by SNACK MUST also carry the current value of 9378 StatSN. 9380 The numbered Data-In PDUs, requested by a Data SNACK MUST be 9381 delivered as exact replicas of the ones that the target 9382 transmitted originally except for the fields ExpCmdSN and 9383 MaxCmdSN, which MUST carry the current values and except for 9384 resegmentation (see Section 11.16.3). 9386 Any SNACK that requests a numbered-response, Data, or R2T that was 9387 not sent by the target or was already acknowledged by the 9388 initiator, MUST be rejected with a reason code of "Protocol 9389 error". 9391 11.16.1. Type 9393 This field encodes the SNACK function as follows: 9395 0-Data/R2T SNACK - requesting retransmission of one or more 9396 Data-In or R2T PDUs. 9398 1-Status SNACK - requesting retransmission of one or more 9399 numbered responses. 9401 2-DataACK - positively acknowledges Data-In PDUs. 9403 3-R-Data SNACK - requesting retransmission of Data-In PDUs 9404 with possible resegmentation and status tagging. 9406 All other values are reserved. 9408 Data/R2T SNACK, Status SNACK, or R-Data SNACK for a command MUST 9409 precede status acknowledgement for the given command. 9411 11.16.2. Data Acknowledgement 9413 If an initiator operates at ErrorRecoveryLevel 1 or higher, it 9414 MUST issue a SNACK of type DataACK after receiving a Data-In PDU 9415 with the A bit set to 1. However, if the initiator has detected 9416 holes in the input sequence, it MUST postpone issuing the SNACK of 9417 type DataACK until the holes are filled. An initiator MAY ignore 9418 the A bit if it deems that the bit is being set aggressively by 9419 the target (i.e., before the MaxBurstLength limit is 9420 reached). 9422 The DataACK is used to free resources at the target and not to 9423 request or imply data retransmission. 9425 An initiator MUST NOT request retransmission for any data it had 9426 already acknowledged. 9428 11.16.3. Resegmentation 9430 If the initiator MaxRecvDataSegmentLength changed between the 9431 original transmission and the time the initiator requests 9432 retransmission, the initiator MUST issue a R-Data SNACK (see 9433 Section 11.16.1). With R-Data SNACK, the initiator indicates that 9434 it discards all the unacknowledged data and expects the target to 9435 resend it. It also expects resegmentation. In this case, the 9436 retransmitted Data-In PDUs MAY be different from the ones 9437 originally sent in order to reflect changes in 9438 MaxRecvDataSegmentLength. Their DataSN starts with the BegRun of 9439 the last DataACK received by the target if any was received; 9440 otherwise it starts with 0 and is increased by 1 for each resent 9441 Data-In PDU. 9443 A target that has received a R-Data SNACK MUST return a SCSI 9444 Response that contains a copy of the SNACK Tag field from the R- 9445 Data SNACK in the SCSI Response SNACK Tag field as its last or 9446 only Response. For example, if it has already sent a response 9447 containing another value in the SNACK Tag field or had the status 9448 included in the last Data-In PDU, it must send a new SCSI Response 9449 PDU. If a target sends more than one SCSI Response PDU due to this 9450 rule, all SCSI responses must carry the same StatSN (see Section 9451 11.4.4). If an initiator attempts to recover a lost SCSI Response 9452 (with a Status-SNACK, see Section 11.16.1) when more than one 9453 response has been sent, the target will send the SCSI Response 9454 with the latest content known to the target, including the last 9455 SNACK Tag for the command. 9457 For considerations in allegiance reassignment of a task to a 9458 connection with a different MaxRecvDataSegmentLength, refer to 9459 Section 7.2.2. 9461 11.16.4. Initiator Task Tag 9463 For Status SNACK and DataACK, the Initiator Task Tag MUST be set 9464 to the reserved value 0xffffffff. In all other cases, the 9465 Initiator Task Tag field MUST be set to the Initiator Task Tag of 9466 the referenced command. 9468 11.16.5. Target Transfer Tag or SNACK Tag 9470 For an R-Data SNACK, this field MUST contain a value that is 9471 different from 0 or 0xffffffff and is unique for the task 9472 (identified by the Initiator Task Tag). This value MUST be copied 9473 by the iSCSI target in the last or only SCSI Response PDU it 9474 issues for the command. 9476 For DataACK, the Target Transfer Tag MUST contain a copy of the 9477 Target Transfer Tag and LUN provided with the SCSI Data-In PDU 9478 with the A bit set to 1. 9480 In all other cases, the Target Transfer Tag field MUST be set to 9481 the reserved value of 0xffffffff. 9483 11.16.6. BegRun 9485 The DataSN, R2TSN, or StatSN of the first PDU whose retransmission 9486 is requested (Data/R2T and Status SNACK), or the next expected 9487 DataSN (DataACK SNACK). 9489 BegRun 0 when used in conjunction with RunLength 0 means resend 9490 all unacknowledged Data-In, R2T or Response PDUs. 9492 BegRun MUST be 0 for a R-Data SNACK. 9494 11.16.7. RunLength 9496 The number of PDUs whose retransmission is requested. 9498 RunLength 0 signals that all Data-In, R2T, or Response PDUs 9499 carrying the numbers equal to or greater than BegRun have to be 9500 resent. 9502 The RunLength MUST also be 0 for a DataACK SNACK in addition to R- 9503 Data SNACK. 9505 11.17. Reject 9507 Byte/ 0 | 1 | 2 | 3 | 9508 / | | | | 9509 |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| 9510 +---------------+---------------+---------------+--------------+ 9511 0|.|.| 0x3f |1| Reserved | Reason | Reserved | 9512 +---------------+---------------+---------------+--------------+ 9513 4|TotalAHSLength | DataSegmentLength | 9514 +---------------+---------------+---------------+--------------+ 9515 8/ Reserved / 9516 +/ / 9517 +---------------+---------------+---------------+--------------+ 9518 16| 0xffffffff | 9519 +---------------+---------------+---------------+--------------+ 9520 20| Reserved | 9521 +---------------+---------------+---------------+--------------+ 9522 24| StatSN | 9523 +---------------+---------------+---------------+--------------+ 9524 28| ExpCmdSN | 9525 +---------------+---------------+---------------+--------------+ 9526 32| MaxCmdSN | 9527 +---------------+---------------+---------------+--------------+ 9528 36| DataSN/R2TSN or Reserved | 9529 +---------------+---------------+---------------+--------------+ 9530 40| Reserved | 9531 +---------------+---------------+---------------+--------------+ 9532 44| Reserved | 9533 +---------------+---------------+---------------+--------------+ 9534 48| Header-Digest (Optional) | 9535 +---------------+---------------+---------------+--------------+ 9536 xx/ Complete Header of Bad PDU / 9537 +/ / 9538 +---------------+---------------+---------------+--------------+ 9539 yy/Vendor specific data (if any) / 9540 / / 9541 +---------------+---------------+---------------+--------------+ 9542 zz| Data-Digest (Optional) | 9543 +---------------+---------------+---------------+--------------+ 9545 Reject is used to indicate an iSCSI error condition (protocol, 9546 unsupported option, etc.). 9548 11.17.1. Reason 9550 The reject Reason is coded as follows: 9552 +------+----------------------------------------+----------------+ 9553 | Code | Explanation |Can the original| 9554 | (hex)| |PDU be re-sent? | 9555 +------+----------------------------------------+----------------+ 9556 | 0x01 | Reserved | no | 9557 | | | | 9558 | 0x02 | Data (payload) Digest Error | yes (Note 1) | 9559 | | | | 9560 | 0x03 | SNACK Reject | yes | 9561 | | | | 9562 | 0x04 | Protocol Error (e.g., SNACK request for| no | 9563 | | a status that was already acknowledged)| | 9564 | | | | 9565 | 0x05 | Command not supported | no | 9566 | | | | 9567 | 0x06 | Immediate Command Reject - too many | yes | 9568 | | immediate commands | | 9569 | | | | 9570 | 0x07 | Task in progress | no | 9571 | | | | 9572 | 0x08 | Invalid Data ACK | no | 9573 | | | | 9574 | 0x09 | Invalid PDU field | no (Note 2) | 9575 | | | | 9576 | 0x0a | Long Operation Reject - Can't generate | yes | 9577 | | Target Transfer Tag - out of resources | | 9578 | | | | 9579 | 0x0c | Waiting for Logout | no | 9580 +------+----------------------------------------+----------------+ 9582 Note 1: For iSCSI, Data-Out PDU retransmission is only done if the 9583 target requests retransmission with a recovery R2T. However, if 9584 this is the data digest error on immediate data, the initiator may 9585 choose to retransmit the whole PDU including the immediate data. 9587 Note 2: A target should use this reason code for all invalid 9588 values of PDU fields that are meant to describe a task, a 9589 response, or a data transfer. Some examples are invalid TTT/ITT, 9590 buffer offset, LUN qualifying a TTT, and an invalid sequence 9591 number in a SNACK. 9593 Note 3: Reason code 0x0b ("Negotiation reset") defined in 9594 [RFC3720] is deprecated and MUST NOT be used by implementations. 9595 An implementation receiving reason code 0x0b MUST treat it as a 9596 negotiation failure that terminates the Login Phase and the TCP 9597 connection, as specified in Section 7.12. 9599 All other values for Reason are reserved. 9601 In all the cases in which a pre-instantiated SCSI task is 9602 terminated because of the reject, the target MUST issue a proper 9603 SCSI command response with CHECK CONDITION as described in Section 9604 11.4.3. In these cases in which a status for the SCSI task was 9605 already sent before the reject, no additional status is required. 9606 If the error is detected while data from the initiator is still 9607 expected (i.e., the command PDU did not contain all the data and 9608 the target has not received a Data-out PDU with the Final bit set 9609 to 1 for the unsolicited data, if any, and all outstanding R2Ts, 9610 if any), the target MUST wait until it receives the last expected 9611 Data-out PDUs with the F bit set to 1 before sending the Response 9612 PDU. 9614 For additional usage semantics of Reject PDU, see Section 7.3. 9616 11.17.2. DataSN/R2TSN 9618 This field is only valid if the rejected PDU is a Data/R2T SNACK 9619 and the Reject reason code is "Protocol error" (see Section 9620 11.16). The DataSN/R2TSN is the next Data/R2T sequence number 9621 that the target would send for the task, if any. 9623 11.17.3. StatSN, ExpCmdSN and MaxCmdSN 9625 These fields carry their usual values and are not related to the 9626 rejected command. StatSN is advanced after a Reject. 9628 11.17.4. Complete Header of Bad PDU 9630 The target returns the header (not including digest) of the PDU in 9631 error as the data of the response. 9633 11.18. NOP-Out 9635 Byte/ 0 | 1 | 2 | 3 | 9636 / | | | | 9637 |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| 9638 +---------------+---------------+---------------+--------------+ 9639 0|.|I| 0x00 |1| Reserved | 9640 +---------------+---------------+---------------+--------------+ 9641 4|TotalAHSLength | DataSegmentLength | 9642 +---------------+---------------+---------------+--------------+ 9643 8| LUN or Reserved | 9644 + + 9645 12| | 9646 +---------------+---------------+---------------+--------------+ 9647 16| Initiator Task Tag or 0xffffffff | 9648 +---------------+---------------+---------------+--------------+ 9649 20| Target Transfer Tag or 0xffffffff | 9650 +---------------+---------------+---------------+--------------+ 9651 24| CmdSN | 9652 +---------------+---------------+---------------+--------------+ 9653 28| ExpStatSN | 9654 +---------------+---------------+---------------+--------------+ 9655 32/ Reserved / 9656 +/ / 9657 +---------------+---------------+---------------+--------------+ 9658 48| Header-Digest (Optional) | 9659 +---------------+---------------+---------------+--------------+ 9660 / DataSegment - Ping Data (optional) / 9661 +/ / 9662 +---------------+---------------+---------------+--------------+ 9663 | Data-Digest (Optional) | 9664 +---------------+---------------+---------------+--------------+ 9666 A NOP-Out may be used by an initiator as a "ping request" to 9667 verify that a connection/session is still active and all its 9668 components are operational. The NOP-In response is the "ping 9669 echo". 9671 A NOP-Out is also sent by an initiator in response to a NOP-In. 9673 A NOP-Out may also be used to confirm a changed ExpStatSN if 9674 another PDU will not be available for a long time. 9676 Upon receipt of a NOP-In with the Target Transfer Tag set to a 9677 valid value (not the reserved 0xffffffff), the initiator MUST 9678 respond with a NOP-Out. In this case, the NOP-Out Target Transfer 9679 Tag MUST contain a copy of the NOP-In Target Transfer Tag. The 9680 initiator SHOULD NOT send a NOP-Out in response to any other 9681 received NOP-In in order to avoid lengthy sequences of NOP-In and 9682 NOP-Out PDUs sent in response to each other. 9684 11.18.1. Initiator Task Tag 9686 The NOP-Out MUST have the Initiator Task Tag set to a valid value 9687 only if a response in the form of NOP-In is requested (i.e., the 9688 NOP-Out is used as a ping request). Otherwise, the Initiator Task 9689 Tag MUST be set to 0xffffffff. 9691 When a target receives the NOP-Out with a valid Initiator Task 9692 Tag, it MUST respond with a Nop-In Response (see Section 6). 9694 If the Initiator Task Tag contains 0xffffffff, the I bit MUST be 9695 set to 1 and the CmdSN is not advanced after this PDU is sent. 9697 11.18.2. Target Transfer Tag 9699 A target assigned identifier for the operation. 9701 The NOP-Out MUST only have the Target Transfer Tag set if it is 9702 issued in response to a NOP-In with a valid Target Transfer Tag. 9703 In this case, it copies the Target Transfer Tag from the NOP-In 9704 PDU. Otherwise, the Target Transfer Tag MUST be set to 0xffffffff. 9706 When the Target Transfer Tag is set to a value other than 9707 0xffffffff, the LUN field MUST also be copied from the NOP-In. 9709 11.18.3. Ping Data 9711 Ping data is reflected in the NOP-In Response. The length of the 9712 reflected data is limited to MaxRecvDataSegmentLength. The length 9713 of ping data is indicated by the DataSegmentLength. 0 is a valid 9714 value for the DataSegmentLength and indicates the absence of ping 9715 data. 9717 11.19. NOP-In 9719 Byte/ 0 | 1 | 2 | 3 | 9720 / | | | | 9721 |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| 9722 +---------------+---------------+---------------+--------------+ 9723 0|.|.| 0x20 |1| Reserved | 9724 +---------------+---------------+---------------+--------------+ 9725 4|TotalAHSLength | DataSegmentLength | 9726 +---------------+---------------+---------------+--------------+ 9727 8| LUN or Reserved | 9728 + + 9729 12| | 9730 +---------------+---------------+---------------+--------------+ 9731 16| Initiator Task Tag or 0xffffffff | 9732 +---------------+---------------+---------------+--------------+ 9733 20| Target Transfer Tag or 0xffffffff | 9734 +---------------+---------------+---------------+--------------+ 9735 24| StatSN | 9736 +---------------+---------------+---------------+--------------+ 9737 28| ExpCmdSN | 9738 +---------------+---------------+---------------+--------------+ 9739 32| MaxCmdSN | 9740 +---------------+---------------+---------------+--------------+ 9741 36/ Reserved / 9742 +/ / 9743 +---------------+---------------+---------------+--------------+ 9744 48| Header-Digest (Optional) | 9745 +---------------+---------------+---------------+--------------+ 9746 / DataSegment - Return Ping Data / 9747 +/ / 9748 +---------------+---------------+---------------+--------------+ 9749 | Data-Digest (Optional) | 9750 +---------------+---------------+---------------+--------------+ 9752 NOP-In is either sent by a target as a response to a NOP-Out, as a 9753 "ping" to an initiator, or as a means to carry a changed ExpCmdSN 9754 and/or MaxCmdSN if another PDU will not be available for a long 9755 time (as determined by the target). 9757 When a target receives the NOP-Out with a valid Initiator Task Tag 9758 (not the reserved value 0xffffffff), it MUST respond with a NOP-In 9759 with the same Initiator Task Tag that was provided in the NOP-Out 9760 request. It MUST also duplicate up to the first 9761 MaxRecvDataSegmentLength bytes of the initiator provided Ping 9762 Data. For such a response, the Target Transfer Tag MUST be 9763 0xffffffff. The target SHOULD NOT send a NOP-In in response to any 9764 other received NOP-Out in order to avoid lengthy sequences of NOP- 9765 In and NOP-Out PDUs sent in response to each other. 9767 Otherwise, when a target sends a NOP-In that is not a response to 9768 a Nop-Out received from the initiator, the Initiator Task Tag MUST 9769 be set to 0xffffffff and the Data Segment MUST NOT contain any 9770 data (DataSegmentLength MUST be 0). 9772 11.19.1. Target Transfer Tag 9774 If the target is responding to a NOP-Out, this is set to the 9775 reserved value 0xffffffff. 9777 If the target is sending a NOP-In as a Ping (intending to receive 9778 a corresponding NOP-Out), this field is set to a valid value (not 9779 the reserved 0xffffffff). 9781 If the target is initiating a NOP-In without wanting to receive a 9782 corresponding NOP-Out, this field MUST hold the reserved value of 9783 0xffffffff. 9785 11.19.2. StatSN 9787 The StatSN field will always contain the next StatSN. However, 9788 when the Initiator Task Tag is set to 0xffffffff StatSN for the 9789 connection is not advanced after this PDU is sent. 9791 11.19.3. LUN 9793 A LUN MUST be set to a correct value when the Target Transfer Tag 9794 is valid (not the reserved value 0xffffffff). 9796 12. iSCSI Security Text Keys and Authentication Methods 9798 Only the following keys are used during the SecurityNegotiation 9799 stage of the Login Phase: 9801 SessionType 9803 InitiatorName 9805 TargetName 9807 TargetAddress 9809 InitiatorAlias 9811 TargetAlias 9813 TargetPortalGroupTag 9815 AuthMethod and the keys used by the authentication methods 9816 specified under Section 12.1 along with all of their 9817 associated keys as well as Vendor Specific Authentication 9818 Methods. 9820 Other keys MUST NOT be used. 9822 SessionType, InitiatorName, TargetName, InitiatorAlias, 9823 TargetAlias, and TargetPortalGroupTag are described in Section 13 9824 as they can be used also in the OperationalNegotiation stage. 9826 All security keys have connection-wide applicability. 9828 12.1. AuthMethod 9830 Use: During Login - Security Negotiation 9831 Senders: Initiator and Target 9832 Scope: connection 9834 AuthMethod = 9836 The main item of security negotiation is the authentication method 9837 (AuthMethod). 9839 The authentication methods that can be used (appear in the list- 9840 of-values) are either those listed in the following table or are 9841 vendor-unique methods: 9843 +------------------------------------------------------------+ 9844 | Name | Description | 9845 +------------------------------------------------------------+ 9846 | KRB5 | Kerberos V5 - defined in [RFC4120] | 9847 +------------------------------------------------------------+ 9848 | SRP | Secure Remote Password | 9849 | | defined in [RFC2945] | 9850 +------------------------------------------------------------+ 9851 | CHAP | Challenge Handshake Authentication Protocol| 9852 | | defined in [RFC1994] | 9853 +------------------------------------------------------------+ 9854 | None | No authentication | 9855 +------------------------------------------------------------+ 9857 The AuthMethod selection is followed by an "authentication 9858 exchange" specific to the authentication method selected. 9860 The authentication method proposal may be made by either the 9861 initiator or the target. However the initiator MUST make the first 9862 step specific to the selected authentication method as soon as it 9863 is selected. It follows that if the target makes the 9864 authentication method proposal the initiator sends the first 9865 key(s) of the exchange together with its authentication method 9866 selection. 9868 The authentication exchange authenticates the initiator to the 9869 target, and optionally, the target to the initiator. 9870 Authentication is OPTIONAL to use but MUST be supported by the 9871 target and initiator. 9873 The initiator and target MUST implement CHAP. All other 9874 authentication methods are OPTIONAL. 9876 Private or public extension algorithms MAY also be negotiated for 9877 authentication methods. Whenever a private or public extension 9878 algorithm is part of the default offer (the offer made in absence 9879 of explicit administrative action) the implementer MUST ensure 9880 that CHAP is listed as an alternative in the default offer and 9881 "None" is not part of the default offer. 9883 Extension authentication methods MUST be named using one of the 9884 following two formats: 9886 i) Z-reversed.vendor.dns_name.do_something= 9887 ii) New public key with no name prefix constraints 9889 Authentication methods named using the Z- format are used as 9890 private extensions. New public keys must be registered with IANA 9891 using IETF Review process ([RFC5226]). New public extensions for 9892 authentication methods MUST NOT use the Z# name prefix. 9894 For all of the public or private extension authentication methods, 9895 the method specific keys MUST conform to the format specified in 9896 Section 6.1 for standard-label. 9898 To identify the vendor for private extension authentication 9899 methods, we suggest you use the reversed DNS-name as a prefix to 9900 the proper digest names. 9902 The part of digest-name following Z- MUST conform to the format 9903 for standard-label specified in Section 6.1. 9905 Support for public or private extension authentication methods is 9906 OPTIONAL. 9908 The following subsections define the specific exchanges for each 9909 of the standardized authentication methods. As mentioned earlier 9910 the first step is always done by the initiator. 9912 12.1.1. Kerberos 9914 For KRB5 (Kerberos V5) [RFC4120] and [RFC1964], the initiator MUST 9915 use: 9917 KRB_AP_REQ= 9919 where KRB_AP_REQ is the client message as defined in [RFC4120]. 9921 The default principal name assumed by an iSCSI initiator or target 9922 (prior to any administrative configuration action) MUST be the 9923 iSCSI Initiator Name or iSCSI Target Name respectively, prefixed 9924 by the string "iscsi/". 9926 If the initiator authentication fails, the target MUST respond 9927 with a Login reject with "Authentication Failure" status. 9928 Otherwise, if the initiator has selected the mutual authentication 9929 option (by setting MUTUAL-REQUIRED in the ap-options field of the 9930 KRB_AP_REQ), the target MUST reply with: 9932 KRB_AP_REP= 9934 where KRB_AP_REP is the server's response message as defined in 9935 [RFC4120]. 9937 If mutual authentication was selected and target authentication 9938 fails, the initiator MUST close the connection. 9940 KRB_AP_REQ and KRB_AP_REP are binary-values and their binary 9941 length (not the length of the character string that represents 9942 them in encoded form) MUST NOT exceed 65536 bytes. 9944 12.1.2. Secure Remote Password (SRP) 9946 For SRP [RFC2945], the initiator MUST use: 9948 SRP_U= TargetAuth=Yes /* or TargetAuth=No */ 9950 The target MUST answer with a Login reject with the "Authorization 9951 Failure" status or reply with: 9953 SRP_GROUP= SRP_s= 9955 Where G1,G2... are proposed groups, in order of preference. 9957 The initiator MUST either close the connection or continue with: 9959 SRP_A= SRP_GROUP= 9960 Where G is one of G1,G2... that were proposed by the target. 9962 The target MUST answer with a Login reject with the 9963 "Authentication Failure" status or reply with: 9965 SRP_B= 9967 The initiator MUST close the connection or continue with: 9969 SRP_M= 9971 If the initiator authentication fails, the target MUST answer with 9972 a Login reject with "Authentication Failure" status. Otherwise, if 9973 the initiator sent TargetAuth=Yes in the first message (requiring 9974 target authentication), the target MUST reply with: 9976 SRP_HM= 9978 If the target authentication fails, the initiator MUST close the 9979 connection. 9981 Where U, s, A, B, M, and H(A | M | K) are defined in [RFC2945] 9982 (using the SHA1 hash function, such as SRP-SHA1) and G,Gn (Gn 9983 stands for G1,G2...) are identifiers of SRP groups specified in 9984 [RFC3723]. G, Gn, and U are text strings, s,A,B,M, and H(A | M | 9985 K) are binary-values. The length of s,A,B,M and H(A | M | K) in 9986 binary form (not the length of the character string that 9987 represents them in encoded form) MUST NOT exceed 1024 bytes. 9989 For the SRP_GROUP, all the groups specified in [RFC3723] up to 9990 1536 bits (i.e., SRP-768, SRP-1024, SRP-1280, SRP-1536) must be 9991 supported by initiators and targets. To guarantee 9992 interoperability, targets MUST always offer "SRP-1536" as one of 9993 the proposed groups. 9995 12.1.3. Challenge Handshake Authentication Protocol (CHAP) 9997 For CHAP [RFC1994], the initiator MUST use: 9999 CHAP_A= 10001 Where A1,A2... are proposed algorithms, in order of preference. 10003 The target MUST answer with a Login reject with the 10004 "Authentication Failure" status or reply with: 10006 CHAP_A= CHAP_I= CHAP_C= 10008 Where A is one of A1,A2... that were proposed by the initiator. 10010 The initiator MUST continue with: 10012 CHAP_N= CHAP_R= 10014 or, if it requires target authentication, with: 10016 CHAP_N= CHAP_R= CHAP_I= CHAP_C= 10018 If the initiator authentication fails, the target MUST answer with 10019 a Login reject with "Authentication Failure" status. Otherwise, if 10020 the initiator required target authentication, the target MUST 10021 either answer with a Login reject with "Authentication Failure" or 10022 reply with: 10024 CHAP_N= CHAP_R= 10026 If target authentication fails, the initiator MUST close the 10027 connection. 10029 Where N, (A,A1,A2), I, C, and R are (correspondingly) the Name, 10030 Algorithm, Identifier, Challenge, and Response as defined in 10031 [RFC1994], N is a text string, A,A1,A2, and I are numbers, and C 10032 and R are binary-values and their binary length (not the length of 10033 the character string that represents them in encoded form) MUST 10034 NOT exceed 1024 bytes. 10036 For the Algorithm, as stated in [RFC1994], one value is required 10037 to be implemented: 10039 5 (CHAP with MD5) 10041 To guarantee interoperability, initiators MUST always offer it as 10042 one of the proposed algorithms. 10044 13. Login/Text Operational Text Keys 10046 Some session specific parameters MUST only be carried on the 10047 leading connection and cannot be changed after the leading 10048 connection login (e.g., MaxConnections, the maximum number of 10049 connections). This holds for a single connection session with 10050 regard to connection restart. The keys that fall into this 10051 category have the use: LO (Leading Only). 10053 Keys that can only be used during login have the use: IO 10054 (initialize only), while those that can be used in both the Login 10055 Phase and Full Feature Phase have the use: ALL. 10057 Keys that can only be used during Full Feature Phase use FFPO 10058 (Full Feature Phase only). 10060 Keys marked as Any-Stage may also appear in the 10061 SecurityNegotiation stage while all other keys described in this 10062 Section are operational keys. 10064 Keys that do not require an answer are marked as Declarative. 10066 Key scope is indicated as session-wide (SW) or connection-only 10067 (CO). 10069 Result function, wherever mentioned, states the function that can 10070 be applied to check the validity of the responder selection. 10071 Minimum means that the selected value cannot exceed the offered 10072 value. Maximum means that the selected value cannot be lower than 10073 the offered value. AND means that the selected value must be a 10074 possible result of a Boolean "and" function with an arbitrary 10075 Boolean value (e.g., if the offered value is No the selected value 10076 must be No). OR means that the selected value must be a possible 10077 result of a Boolean "or" function with an arbitrary Boolean value 10078 (e.g., if the offered value is Yes the selected value must be 10079 Yes). 10081 13.1. HeaderDigest and DataDigest 10083 Use: IO 10084 Senders: Initiator and Target 10085 Scope: CO 10086 HeaderDigest = 10087 DataDigest = 10089 Default is None for both HeaderDigest and DataDigest. 10091 Digests enable the checking of end-to-end, non-cryptographic data 10092 integrity beyond the integrity checks provided by the link layers 10093 and the covering of the whole communication path including all 10094 elements that may change the network level PDUs such as routers, 10095 switches, and proxies. 10097 The following table lists cyclic integrity checksums that can be 10098 negotiated for the digests and that MUST be implemented by every 10099 iSCSI initiator and target. These digest options only have error 10100 detection significance. 10102 +---------------------------------------------+ 10103 | Name | Description | Generator | 10104 +---------------------------------------------+ 10105 | CRC32C | 32 bit CRC |0x11edc6f41| 10106 +---------------------------------------------+ 10107 | None | no digest | 10108 +---------------------------------------------+ 10110 The generator polynomial for this digest is given in hex-notation 10111 (e.g., 0x3b stands for 0011 1011 and the polynomial is 10112 x**5+X**4+x**3+x+1). 10114 When the Initiator and Target agree on a digest, this digest MUST 10115 be used for every PDU in Full Feature Phase. 10117 Padding bytes, when present in a segment covered by a CRC, SHOULD 10118 be set to 0 and are included in the CRC. 10120 The CRC MUST be calculated by a method that produces the same 10121 results as the following process: 10123 - The PDU bits are considered as the coefficients of a 10124 polynomial M(x) of degree n-1; bit 7 of the lowest numbered 10125 byte is considered the most significant bit (x^n-1), 10127 followed by bit 6 of the lowest numbered byte through bit 0 10128 of the highest numbered byte (x^0). 10130 - The most significant 32 bits are complemented. 10132 - The polynomial is multiplied by x^32 then divided by G(x). 10133 The generator polynomial produces a remainder R(x) of degree 10134 <= 31. 10136 - The coefficients of R(x) are considered a 32 bit sequence. 10138 - The bit sequence is complemented and the result is the CRC. 10140 - The CRC bits are mapped into the digest word. The x^31 10141 coefficient in bit 7 of the lowest numbered byte of the 10142 digest continuing through to the byte up to the x^24 10143 coefficient in bit 0 of the lowest numbered byte, continuing 10144 with the x^23 coefficient in bit 7 of next byte through x^0 10145 in bit 0 of the highest numbered byte. 10147 - Computing the CRC over any segment (data or header) extended 10148 to include the CRC built using the generator 0x11edc6f41 10149 will always get the value 0x1c2d19ed as its final remainder 10150 (R(x)). This value is given here in its polynomial form 10151 (i.e., not mapped as the digest word). 10153 For a discussion about selection criteria for the CRC, see 10154 [RFC3385]. For a detailed analysis of the iSCSI polynomial, see 10155 [Castagnoli93]. 10157 Private or public extension algorithms MAY also be negotiated for 10158 digests. Whenever a private or public digest extension algorithm 10159 is part of the default offer (the offer made in absence of 10160 explicit administrative action) the implementer MUST ensure that 10161 CRC32C is listed as an alternative in the default offer and "None" 10162 is not part of the default offer. 10164 Extension digest algorithms MUST be named using one of the 10165 following two formats: 10167 i) Y-reversed.vendor.dns_name.do_something= 10168 ii) New public key with no name prefix constraints 10170 Digests named using the Y- format are used for private purposes 10171 (unregistered). New public keys must be registered with IANA using 10172 IETF Review process ([RFC5226]). New public extensions for digests 10173 MUST NOT use the Y# name prefix. 10175 For private extension digests, to identify the vendor, we suggest 10176 you use the reversed DNS-name as a prefix to the proper digest 10177 names. 10179 The part of digest-name following Y- MUST conform to the format 10180 for standard-label specified in Section 6.1. 10182 Support for public or private extension digests is OPTIONAL. 10184 13.2. MaxConnections 10186 Use: LO 10187 Senders: Initiator and Target 10188 Scope: SW 10189 Irrelevant when: SessionType=Discovery 10191 MaxConnections= 10193 Default is 1. 10194 Result function is Minimum. 10196 Initiator and target negotiate the maximum number of connections 10197 requested/acceptable. 10199 13.3. SendTargets 10201 Use: FFPO 10202 Senders: Initiator 10203 Scope: SW 10205 For a complete description, see Appendix C. 10207 13.4. TargetName 10209 Use: IO by initiator, FFPO by target - only as response to a 10210 SendTargets, Declarative, Any-Stage 10211 Senders: Initiator and Target 10212 Scope: SW 10214 TargetName= 10216 Examples: 10218 TargetName=iqn.1993-11.com.disk-vendor:diskarrays.sn.45678 10220 TargetName=eui.020000023B040506 10222 TargetName=naa.62004567BA64678D0123456789ABCDEF 10224 The initiator of the TCP connection MUST provide this key to the 10225 remote endpoint in the first login request if the initiator is not 10226 establishing a discovery session. The iSCSI Target Name specifies 10227 the worldwide unique name of the target. 10229 The TargetName key may also be returned by the "SendTargets" text 10230 request (which is its only use when issued by a target). 10232 TargetName MUST NOT be redeclared within the login phase. 10234 13.5. InitiatorName 10236 Use: IO, Declarative, Any-Stage 10237 Senders: Initiator 10238 Scope: SW 10240 InitiatorName= 10242 Examples: 10244 InitiatorName=iqn.1992-04.com.os-vendor.plan9:cdrom.12345 10246 InitiatorName=iqn.2001-02.com.ssp.users:customer235.host90 10248 InitiatorName=naa.52004567BA64678D 10250 The initiator of the TCP connection MUST provide this key to the 10251 remote endpoint at the first Login of the Login Phase for every 10252 connection. The InitiatorName key enables the initiator to 10253 identify itself to the remote endpoint. 10255 InitiatorName MUST NOT be redeclared within the login phase. 10257 13.6. TargetAlias 10259 Use: ALL, Declarative, Any-Stage 10260 Senders: Target 10261 Scope: SW 10263 TargetAlias= 10265 Examples: 10267 TargetAlias=Bob-s Disk 10269 TargetAlias=Database Server 1 Log Disk 10271 TargetAlias=Web Server 3 Disk 20 10273 If a target has been configured with a human-readable name or 10274 description, this name SHOULD be communicated to the initiator 10275 during a Login Response PDU if SessionType=Normal (see 13.21). 10276 This string is not used as an identifier, nor is it meant to be 10277 used for authentication or authorization decisions. It can be 10278 displayed by the initiator's user interface in a list of targets 10279 to which it is connected. 10281 13.7. InitiatorAlias 10283 Use: ALL, Declarative, Any-Stage 10284 Senders: Initiator 10285 Scope: SW 10287 InitiatorAlias= 10289 Examples: 10291 InitiatorAlias=Web Server 4 10293 InitiatorAlias=spyalley.nsa.gov 10295 InitiatorAlias=Exchange Server 10297 If an initiator has been configured with a human-readable name or 10298 description, it SHOULD be communicated to the target during a 10299 Login Request PDU. If not, the host name can be used instead. This 10300 string is not used as an identifier, nor is meant to be used for 10301 authentication or authorization decisions. It can be displayed by 10302 the target's user interface in a list of initiators to which it is 10303 connected. 10305 13.8. TargetAddress 10307 Use: ALL, Declarative, Any-Stage 10308 Senders: Target 10309 Scope: SW 10311 TargetAddress=domainname[:port][,portal-group-tag] 10313 The domainname can be specified as either a DNS host name, a 10314 dotted-decimal IPv4 address, or a bracketed IPv6 address as 10315 specified in [RFC3986]. 10317 If the TCP port is not specified, it is assumed to be the IANA- 10318 assigned default port for iSCSI (see Section 14). 10320 If the TargetAddress is returned as the result of a redirect 10321 status in a login response, the comma and portal group tag MUST be 10322 omitted. 10324 If the TargetAddress is returned within a SendTargets response, 10325 the portal group tag MUST be included. 10327 Examples: 10329 TargetAddress=10.0.0.1:5003,1 10331 TargetAddress=[1080:0:0:0:8:800:200C:417A],65 10332 TargetAddress=[1080::8:800:200C:417A]:5003,1 10334 TargetAddress=computingcenter.example.com,23 10336 Use of the portal-group-tag is described in Appendix C. The 10337 formats for the port and portal-group-tag are the same as the one 10338 specified in TargetPortalGroupTag. 10340 13.9. TargetPortalGroupTag 10342 Use: IO by target, Declarative, Any-Stage 10343 Senders: Target 10344 Scope: SW 10346 TargetPortalGroupTag=<16-bit-binary-value> 10348 Examples: 10349 TargetPortalGroupTag=1 10351 The target portal group tag is a 16-bit binary-value that uniquely 10352 identifies a portal group within an iSCSI target node. This key 10353 carries the value of the tag of the portal group that is servicing 10354 the Login request. The iSCSI target returns this key to the 10355 initiator in the Login Response PDU to the first Login Request PDU 10356 that has the C bit set to 0 when TargetName is given by the 10357 initiator. 10359 [SAM2] notes in its informative text that TPGT value should be 10360 non-zero, note that it is incorrect. A zero value is allowed as a 10361 legal value for TPGT. This discrepancy currently stands corrected 10362 in [SAM4]. 10364 For the complete usage expectations of this key see Section 6.3. 10366 13.10. InitialR2T 10368 Use: LO 10369 Senders: Initiator and Target 10370 Scope: SW 10371 Irrelevant when: SessionType=Discovery 10373 InitialR2T= 10375 Examples: 10377 I->InitialR2T=No 10379 T->InitialR2T=No 10381 Default is Yes. 10382 Result function is OR. 10384 The InitialR2T key is used to turn off the default use of R2T for 10385 unidirectional and the output part of bidirectional commands, thus 10386 allowing an initiator to start sending data to a target as if it 10387 has received an initial R2T with Buffer Offset=Immediate Data 10388 Length and Desired Data Transfer Length=(min(FirstBurstLength, 10389 Expected Data Transfer Length) - Received Immediate Data Length). 10391 The default action is that R2T is required, unless both the 10392 initiator and the target send this key-pair attribute specifying 10393 InitialR2T=No. Only the first outgoing data burst (immediate data 10394 and/or separate PDUs) can be sent unsolicited (i.e., not requiring 10395 an explicit R2T). 10397 13.11. ImmediateData 10399 Use: LO 10400 Senders: Initiator and Target 10401 Scope: SW 10402 Irrelevant when: SessionType=Discovery 10404 ImmediateData= 10406 Default is Yes. 10407 Result function is AND. 10409 The initiator and target negotiate support for immediate data. To 10410 turn immediate data off, the initiator or target must state its 10411 desire to do so. ImmediateData can be turned on if both the 10412 initiator and target have ImmediateData=Yes. 10414 If ImmediateData is set to Yes and InitialR2T is set to Yes 10415 (default), then only immediate data are accepted in the first 10416 burst. 10418 If ImmediateData is set to No and InitialR2T is set to Yes, then 10419 the initiator MUST NOT send unsolicited data and the target MUST 10420 reject unsolicited data with the corresponding response code. 10422 If ImmediateData is set to No and InitialR2T is set to No, then 10423 the initiator MUST NOT send unsolicited immediate data, but MAY 10424 send one unsolicited burst of Data-OUT PDUs. 10426 If ImmediateData is set to Yes and InitialR2T is set to No, then 10427 the initiator MAY send unsolicited immediate data and/or one 10428 unsolicited burst of Data-OUT PDUs. 10430 The following table is a summary of unsolicited data options: 10432 +----------+-------------+------------------+--------------+ 10433 |InitialR2T|ImmediateData| Unsolicited |Immediate Data| 10434 | | | Data Out PDUs | | 10435 +----------+-------------+------------------+--------------+ 10436 | No | No | Yes | No | 10437 +----------+-------------+------------------+--------------+ 10438 | No | Yes | Yes | Yes | 10439 +----------+-------------+------------------+--------------+ 10440 | Yes | No | No | No | 10441 +----------+-------------+------------------+--------------+ 10442 | Yes | Yes | No | Yes | 10443 +----------+-------------+------------------+--------------+ 10445 13.12. MaxRecvDataSegmentLength 10447 Use: ALL, Declarative 10448 Senders: Initiator and Target 10449 Scope: CO 10451 MaxRecvDataSegmentLength= 10453 Default is 8192 bytes. 10455 The initiator or target declares the maximum data segment length 10456 in bytes it can receive in an iSCSI PDU. 10458 The transmitter (initiator or target) is required to send PDUs 10459 with a data segment that does not exceed MaxRecvDataSegmentLength 10460 of the receiver. 10462 A target receiver is additionally limited by MaxBurstLength for 10463 solicited data and FirstBurstLength for unsolicited data. An 10464 initiator MUST NOT send solicited PDUs exceeding MaxBurstLength 10465 nor unsolicited PDUs exceeding FirstBurstLength (or 10466 FirstBurstLength-Immediate Data Length if immediate data were 10467 sent). 10469 13.13. MaxBurstLength 10471 Use: LO 10472 Senders: Initiator and Target 10473 Scope: SW 10474 Irrelevant when: SessionType=Discovery 10476 MaxBurstLength= 10478 Default is 262144 (256 Kbytes). 10479 Result function is Minimum. 10481 The initiator and target negotiate maximum SCSI data payload in 10482 bytes in a Data-In or a solicited Data-Out iSCSI sequence. A 10483 sequence consists of one or more consecutive Data-In or Data-Out 10484 PDUs that end with a Data-In or Data-Out PDU with the F bit set to 10485 one. 10487 13.14. FirstBurstLength 10489 Use: LO 10490 Senders: Initiator and Target 10491 Scope: SW 10492 Irrelevant when: SessionType=Discovery 10493 Irrelevant when: ( InitialR2T=Yes and ImmediateData=No ) 10495 FirstBurstLength= 10496 Default is 65536 (64 Kbytes). 10497 Result function is Minimum. 10499 The initiator and target negotiate the maximum amount in bytes of 10500 unsolicited data an iSCSI initiator may send to the target during 10501 the execution of a single SCSI command. This covers the immediate 10502 data (if any) and the sequence of unsolicited Data-Out PDUs (if 10503 any) that follow the command. 10505 FirstBurstLength MUST NOT exceed MaxBurstLength. 10507 13.15. DefaultTime2Wait 10509 Use: LO 10510 Senders: Initiator and Target 10511 Scope: SW 10513 DefaultTime2Wait= 10515 Default is 2. 10516 Result function is Maximum. 10518 The initiator and target negotiate the minimum time, in seconds, 10519 to wait before attempting an explicit/implicit logout or an active 10520 task reassignment after an unexpected connection termination or a 10521 connection reset. 10523 A value of 0 indicates that logout or active task reassignment can 10524 be attempted immediately. 10526 13.16. DefaultTime2Retain 10528 Use: LO 10529 Senders: Initiator and Target 10530 Scope: SW 10532 DefaultTime2Retain= 10534 Default is 20. 10535 Result function is Minimum. 10537 The initiator and target negotiate the maximum time, in seconds 10538 after an initial wait (Time2Wait), before which an active task 10539 reassignment is still possible after an unexpected connection 10540 termination or a connection reset. 10542 This value is also the session state timeout if the connection in 10543 question is the last LOGGED_IN connection in the session. 10545 A value of 0 indicates that connection/task state is immediately 10546 discarded by the target. 10548 13.17. MaxOutstandingR2T 10550 Use: LO 10551 Senders: Initiator and Target 10552 Scope: SW 10554 MaxOutstandingR2T= 10555 Irrelevant when: SessionType=Discovery 10557 Default is 1. 10558 Result function is Minimum. 10560 Initiator and target negotiate the maximum number of outstanding 10561 R2Ts per task, excluding any implied initial R2T that might be 10562 part of that task. An R2T is considered outstanding until the last 10563 data PDU (with the F bit set to 1) is transferred, or a sequence 10564 reception timeout (Section 7.1.4.1) is encountered for that data 10565 sequence. 10567 13.18. DataPDUInOrder 10569 Use: LO 10570 Senders: Initiator and Target 10571 Scope: SW 10572 Irrelevant when: SessionType=Discovery 10574 DataPDUInOrder= 10576 Default is Yes. 10577 Result function is OR. 10579 No is used by iSCSI to indicate that the data PDUs within 10580 sequences can be in any order. Yes is used to indicate that data 10581 PDUs within sequences have to be at continuously increasing 10582 addresses and overlays are forbidden. 10584 13.19. DataSequenceInOrder 10586 Use: LO 10587 Senders: Initiator and Target 10588 Scope: SW 10589 Irrelevant when: SessionType=Discovery 10591 DataSequenceInOrder= 10593 Default is Yes. 10594 Result function is OR. 10596 A Data Sequence is a sequence of Data-In or Data-Out PDUs that end 10597 with a Data-In or Data-Out PDU with the F bit set to one. A Data- 10598 out sequence is sent either unsolicited or in response to an R2T. 10599 Sequences cover an offset-range. 10601 If DataSequenceInOrder is set to No, Data PDU sequences may be 10602 transferred in any order. 10604 If DataSequenceInOrder is set to Yes, Data Sequences MUST be 10605 transferred using continuously non-decreasing sequence offsets 10606 (R2T buffer offset for writes, or the smallest SCSI Data-In buffer 10607 offset within a read data sequence). 10609 If DataSequenceInOrder is set to Yes, a target may retry at most 10610 the last R2T, and an initiator may at most request retransmission 10611 for the last read data sequence. For this reason, if 10612 ErrorRecoveryLevel is not 0 and DataSequenceInOrder is set to Yes 10613 then MaxOustandingR2T MUST be set to 1. 10615 13.20. ErrorRecoveryLevel 10617 Use: LO 10618 Senders: Initiator and Target 10619 Scope: SW 10620 ErrorRecoveryLevel= 10622 Default is 0. 10623 Result function is Minimum. 10625 The initiator and target negotiate the recovery level supported. 10627 Recovery levels represent a combination of recovery capabilities. 10628 Each recovery level includes all the capabilities of the lower 10629 recovery levels and adds some new ones to them. 10631 In the description of recovery mechanisms, certain recovery 10632 classes are specified. Section 7.1.5 describes the mapping between 10633 the classes and the levels. 10635 13.21. SessionType 10637 Use: LO, Declarative, Any-Stage 10638 Senders: Initiator 10639 Scope: SW 10641 SessionType= 10643 Default is Normal. 10645 The Initiator indicates the type of session it wants to create. 10646 The target can either accept it or reject it. 10648 A Discovery session indicates to the Target that the only purpose 10649 of this Session is discovery. The only requests a target accepts 10650 in this type of session are a text request with a SendTargets key 10651 and a logout request with reason "close the session". 10653 The Discovery session implies MaxConnections = 1 and overrides 10654 both the default and an explicit setting. As Section 7.4.1 10655 states, ErrorRecoveryLevel MUST be 0 (zero) for Discovery 10656 sessions. 10658 Depending on the type of the session, a target may decide on 10659 resources to allocate and the security to enforce, etc. for the 10660 session. If the SessionType key is thus going to be offered as 10662 "Discovery", it SHOULD be offered in the initial Login request by 10663 the initiator. 10665 13.22. The Private Extension Key Format 10667 Use: ALL 10668 Senders: Initiator and Target 10669 Scope: specific key dependent 10671 X-reversed.vendor.dns_name.do_something= 10673 Keys with this format are used for private extension purposes. 10674 These keys always start with X- if unregistered with IANA 10675 (private). New public keys (if registered with IANA via an IETF 10676 Review, [RFC5226]) no longer have an X# name prefix requirement, 10677 implementers may propose any intuitive unique name. 10679 For unregistered keys, to identify the vendor, we suggest you use 10680 the reversed DNS-name as a prefix to the key-proper. 10682 The part of key-name following X- MUST conform to the format for 10683 key-name specified in Section 6.1. 10685 Vendor specific keys MUST ONLY be used in normal sessions. 10687 Support for public or private extension keys is OPTIONAL. 10689 13.23. TaskReporting 10691 Use: LO 10692 Senders: Initiator and Target 10693 Scope: SW 10694 Irrelevant when: SessionType=Discovery 10695 TaskReporting= 10697 Default is RFC3720. 10698 Result function is AND. 10700 This key is used to negotiate the task completion reporting 10701 semantics from the SCSI target. The following table describes the 10702 semantics that an iSCSI target MUST support for respective 10703 negotiated key values. Whenever this key is negotiated, at least 10704 the RFC3720 and ResponseFence values MUST be offered as options by 10705 the negotiation originator. 10706 +--------------+------------------------------------------+ 10707 | Name | Description | 10708 +--------------+------------------------------------------+ 10709 | RFC3720 | RFC 3720-compliant semantics. Response | 10710 | | fencing is not guaranteed and fast | 10711 | | completion of multi-task aborting is not | 10712 | | supported | 10713 +--------------+------------------------------------------+ 10714 | ResponseFence| Response Fence (Section 4.2.2.3.3) | 10715 | | semantics MUST be supported in reporting | 10716 | | task completions | 10717 +--------------+------------------------------------------+ 10718 | FastAbort | Updated fast multi-task abort semantics | 10719 | | defined in Section 4.2.3.4 MUST be | 10720 | | supported. Support for Response Fence is | 10721 | | implied -- i.e., (Section 4.2.2.3.3) | 10722 | | semantics MUST be supported as well | 10723 +--------------+------------------------------------------+ 10724 When TaskReporting is not negotiated to FastAbort, the standard 10725 multi-task abort semantics in Section 4.2.3.3 MUST be used. 10727 13.24. iSCSIProtocolLevel Negotiation 10729 The iSCSIProtocolLevel associated with this document is "1". As a 10730 responder or an originator in a negotiation of this key, an iSCSI 10731 implementation compliant to this document alone, without any 10732 future protocol extensions, MUST use this value as defined by the 10733 [iSCSI-SAM] document. 10735 13.25. Obsoleted Keys 10737 This document obsoletes the following keys defined in [RFC3720]: 10738 IFMarker, OFMarker, OFMarkInt, IFMarkInt. However, iSCSI 10739 implementations compliant to this document may still receive these 10740 obsoleted keys - i.e. in a responder role - in a text negotiation. 10742 When IFMarker or OFMarker key is received, a compliant iSCSI 10743 implementation SHOULD respond with the constant "Reject" value. 10744 The implementation MAY alternatively respond with a "No" value. 10746 However, the implementation MUST NOT respond with a 10747 "NotUnderstood" value for either of these keys. 10749 When IFMarkInt or OFMarkInt key is received, a compliant iSCSI 10750 implementation MUST respond with the constant "Reject" value. 10751 The implementation MUST NOT respond with a "NotUnderstood" value 10752 for either of these keys. 10754 13.26. X#NodeArchitecture 10756 13.26.1. Definition 10758 Use: LO, Declarative 10759 Senders: Initiator and Target 10760 Scope: SW 10762 X#NodeArchitecture= 10764 Default is none. 10766 Examples: 10767 X#NodeArchitecture=ExampleOS/v1234,ExampleInc_SW_Initiator/1.05a 10768 X#NodeArchitecture=ExampleInc_HW_Initiator/4010,Firmware/2.0.0.5 10769 X#NodeArchitecture=ExampleInc_SW_Initiator/2.1,CPU_Arch/i686 10771 This document does not define the structure or content of the list 10772 of values. 10774 The initiator or target declares the details of its iSCSI node 10775 architecture to the remote endpoint. These details may include, 10776 but are not limited to, iSCSI vendor software, firmware, or 10777 hardware versions, the OS version, or hardware architecture. This 10778 key may be declared on a Discovery session or a Normal session. 10780 The length of the key value (total length of the list-of-values) 10781 MUST NOT be greater than 255 bytes. 10783 X#NodeArchitecture MUST NOT be redeclared during the login phase. 10785 13.26.2. Implementation Requirements 10787 Functional behavior of the iSCSI node (this includes the iSCSI 10788 protocol logic -- the SCSI, iSCSI, and TCP/IP protocols) MUST NOT 10789 depend on the presence, absence, or content of the 10790 X#NodeArchitecture key. The key MUST NOT be used by iSCSI nodes 10791 for interoperability, or exclusion of other nodes. To ensure 10792 proper use, key values SHOULD be set by the node itself, and there 10793 SHOULD NOT be provisions for the key values to contain user- 10794 defined text. 10796 Nodes implementing this key MUST choose one of the following 10797 implementation options: 10799 - only transmit the key, 10801 - only log the key values received from other nodes, or 10803 - both transmit and log the key values. 10805 Each node choosing to implement transmission of the key values 10806 MUST be prepared to handle the response of iSCSI Nodes that do not 10807 understand the key. 10809 Nodes that implement transmission and/or logging of the key values 10810 may also implement administrative mechanisms that disable and/or 10811 change the logging and key transmission detail (see Section 9.4). 10812 Thus, a valid behavior for this key may be that a node is 10813 completely silent (the node does not transmit any key value, and 10814 simply discards any key values it receives without issuing a 10815 NotUnderstood response). 10817 14. Rationale for revised IANA Considerations 10819 This document makes rather significant changes in this area, and 10820 this Section outlines the reasons behind the changes. As 10821 previously specified in [RFC3720], iSCSI had used text string 10822 prefixes, such as X- and X#, to distinguish extended login/text 10823 keys, digest algorithms and authentication methods from their 10824 standardized counterparts. Based on experience with other 10825 protocols, [RFC6648] however strongly recommends against this 10826 practice, in large part because extensions that use such prefixes 10827 may become standard over time at which point it can be infeasible 10828 to change their text string names due to widespread usage under 10829 the existing text string name. 10831 iSCSI's experience with public extensions supports the 10832 recommendations in [RFC6648], as the only extension item ever 10833 registered with IANA, the X#NodeArchitecture key, was specified as 10834 a standard key in a standards-track RFC [RFC4850], and hence did 10835 not require the X# prefix. In addition, that key is the only 10836 public iSCSI extension that has been registered with IANA since 10837 RFC 3720 was originally published, so there has been effectively 10838 no use of the X#, Y# and Z# public extension formats. 10840 Therefore, this document makes the following changes to the IANA 10841 registration procedures for iSCSI: 10843 (1) The separate registries for X#, Y# and Z# public 10844 extensions are removed. The single entry in the registry for 10845 X# login/text keys(X#NodeArchitecture) is transferred to the 10846 main login/text key registry. IANA has never created the 10847 latter two registries because there have been no 10848 registration requests for them. These public extension 10849 formats (X#, Y#, Z#) MUST NOT be used with the exception of 10850 the existing X#NodeArchitecture key. 10852 (2) The Registration Procedures for the main login/text key, 10853 digest algorithm and authentication method IANA registries 10854 are changed to IETF Review [RFC5226] for possible future 10855 extensions to iSCSI. This change includes a deliberate 10856 decision to remove the possibility of specifying an IANA- 10857 registered iSCSI extension in an RFC published via an RFC 10859 Editor independent submission, as the level of review in 10860 that process is insufficient for iSCSI extensions. 10862 (3) The restriction against registering items using the 10863 private extension formats (X-, Y-, Z-) in the main IANA 10864 registries is removed. Extensions using these formats MAY be 10865 registered under the IETF Review registration procedures, 10866 but each format is restricted to the type of extension for 10867 which it is specified in this RFC and MUST NOT be used for 10868 other types. For example, the X- extension format for 10869 extension login/text keys MUST NOT be used for digest 10870 algorithms or authentication methods. 10872 15. IANA Considerations 10874 The well-known TCP port number for iSCSI connections assigned by 10875 IANA is 3260 and this is the default iSCSI port. Implementations 10876 needing a system TCP port number may use port 860, the port 10877 assigned by IANA as the iSCSI system port; however in order to use 10878 port 860, it MUST be explicitly specified - implementations MUST 10879 NOT default to use of port 860, as 3260 is the only allowed 10880 default. 10882 IANA is requested to update all references to RFC 3720, RFC 4850 10883 and RFC 5048 to instead reference this RFC in all of the iSCSI 10884 registries that are part of the "Internet Small Computer System 10885 Interface (iSCSI) Parameters" set of registries. This change 10886 reflects the fact that those three RFCs are obsoleted by this RFC. 10887 References to other RFCs that are not being obsoleted (e.g., RFC 10888 3723, RFC 5046) should not be changed. 10890 IANA is requested to perform the following actions on the iSCSI 10891 Login/Text Keys registry: 10893 - Change the registration procedure to IETF Review from 10894 Standard Required. 10896 - Change the RFC 5048 reference for the registry to reference 10897 this RFC. 10899 - Add the X#NodeArchitecture Key from the iSCSI extended key 10900 registry and change its reference to this RFC. 10902 - Change all references of RFC 3720 and RFC 5048 to reference 10903 this RFC. 10905 IANA is requested to change the Registration Procedures for the 10906 iSCSI authentication methods and iSCSI digests registries to IETF 10907 Review from RFC Required. 10909 IANA is requested to remove the iSCSI extended key registry, as 10910 its one entry is to be added to the iSCSI login/text keys 10911 registry. 10913 IANA is requested to mark obsolete the values 4 and 5, for SPKM1 10914 and SPKM2 respectively, in the iSCSI authentication methods 10915 subregistry of the Internet Small Computer System Interface 10916 (iSCSI) Parameters registries. 10918 All the other IANA considerations stated in [RFC3720] and 10919 [RFC5048] remain unchanged. 10921 This document obsoletes the SPKM1 and SPKM2 key values for the 10922 AuthMethod text key. Consequently, the SPKM_ text key prefix MUST 10923 be treated as obsolete and be not reused. 10925 IANA is requested to add the following entry to the "iSCSI 10926 Protocol Level" registry created by Section 9 of [iSCSI-SAM]: 10928 Assigned value: 1 10929 RFC Reference: [RFCyyyy] 10931 RFC Editor: Please replace yyyy in the above reference with the 10932 RFC number assigned to this document and remove this note. 10934 Expert Review of this assignment has been performed by David Black 10935 in his role as the T10 Liaison to IETF. The value 1 is part of 10936 the initial contents of this registry; for that reason, IANA is 10937 instructed to assign the value 1 as indicated above and apply the 10938 sequential assignment policy for this registry (as specified in 10939 [iSCSI-SAM]) to future assignments, starting with the value 3. 10941 References 10943 Normative References 10945 [EUI] "Guidelines for 64-bit Global Identifier (EUI-64)", 10946 http://standards.ieee.org/regauth/oui/tutorials/EUI64.html 10948 [FC-FS3] INCITS 470-2011, Fibre Channel - Framing and 10949 Signaling - 3 (FC-FS-3). 10951 [iSCSI-SAM] Knight, F., Chadalapaka, M., "Internet Small 10952 Computer Systems Interface (iSCSI) SCSI Architecture 10953 Features Update", draft-ietf-storm-iscsi-sam-06.txt (work in 10954 progress), July 2012 10956 [OUI] "IEEE OUI and Company_Id Assignments", 10957 http://standards.ieee.org/regauth/oui 10959 [RFC1964] J. Linn, "The Kerberos Version 5 GSS-API Mechanism", 10960 June 1996. 10962 [RFC1982] Elz, R., Bush, R., "Serial Number Arithmetic", 10963 August 1996. 10965 [RFC1994] W. Simpson, "PPP Challenge Handshake Authentication 10966 Protocol (CHAP)", August 1996. 10968 [RFC2045] N. Borenstein, N. Freed, "MIME (Multipurpose 10969 Internet Mail Extensions) Part One: Mechanisms for 10970 Specifying and Describing the Format of Internet Message 10971 Bodies", November 1996. 10973 [RFC2119] Bradner, S. "Key Words for use in RFCs to Indicate 10974 Requirement Levels", BCP 14, March 1997. 10976 [RFC2404] C. Madson, R. Glenn, "The Use of HMAC-SHA-1-96 10977 within ESP and AH", November 1998. 10979 [RFC2451] R. Pereira, R. Adams "The ESP CBC-Mode Cipher 10980 Algorithms". 10982 [RFC2945] Wu, T., "The SRP Authentication and Key Exchange 10983 System", September 2000. 10985 [RFC3454] Hoffman, P. and M. Blanchet, "Preparation of 10986 Internationalized Strings ("stringprep")", RFC 3454, 10987 December 2002. 10989 [RFC3566] Frankel, S. and H. Herbert, "The AES-XCBC-MAC-96 10990 Algorithm and Its Use With IPsec", RFC 3566, September 2003. 10992 [RFC3629] Yergeau, F., "UTF-8, a Transformation Format of ISO 10993 10646", RFC 3629, November 2003 10995 [RFC3686] Housley, R., "Using Advanced Encryption Standard 10996 (AES) Counter Mode with IPsec Encapsulating Security Payload 10997 (ESP)", RFC 3686, January 2004. 10999 [RFC3722] Bakke, M., "String Profile for Internet Small 11000 Computer Systems Interface (iSCSI) Names", RFC 3722, March 11001 2004. 11003 [RFC3723] Aboba, B., Tseng, J., Walker, J., Rangan, V. and F. 11004 Travostino, "Securing Block Storage Protocols over IP", RFC 11005 3723, March 2004. 11007 [RFC3986] T. Berners-Lee, R. Fielding, L. Masinter "Uniform 11008 Resource Identifier (URI): Generic Syntax", January 2005. 11010 [RFC4106] J. Viega, D. McGrew, "The Use of Galois/Counter Mode 11011 (GCM) in IPsec Encapsulating Security Payload (ESP)", RFC 11012 4106, June 2005. 11014 [RFC4120] Neuman, C., Yu, T., Hartman, S., Raeburn, K, "The 11015 Kerberos Network Authentication Service (V5)", RFC 4120, 11016 July 2005. 11018 [RFC4171] J. Tseng, K. Gibbons, F. Travostino, C. Du Laney, J. 11019 Souza, "Internet Storage Name Service (iSNS)", September 11020 2005. 11022 [RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing 11023 Architecture", February 2006. 11025 [RFC4301] S. Kent, K.Seo, "Security Architecture for the 11026 Internet Protocol", December 2005. 11028 [RFC4303] Kent, S., "IP Encapsulating Security Payload (ESP)", 11029 RFC 4303, December 2005 11031 [RFC4543] D. McGrew, J. Viega, "The Use of Galois Message 11032 Authentication Code (GMAC) in IPsec ESP and AH", RFC 4543, 11033 May 2006 11035 [RFC5226] H. Alvestrand, T. Narten, "Guidelines for Writing an 11036 IANA Considerations Section in RFCs", RFC 5226, May 2008 11038 [RFC5996] C. Kaufman, P. Hoffman, Y. Nir, P. Eronen, "Internet 11039 Key Exchange Protocol Version 2 (IKEv2) ", RFC 5996, 11040 September 2010. 11042 [SAM2] T10/1157-D, SCSI Architecture Model - 2 (SAM-2). 11044 [SAM4] T10/1683-D, SCSI Architecture Model - 4 (SAM-4). 11046 [SPC2] T10/1236-D, SCSI Primary Commands-2. 11048 [SPC3] T10/1416-D, SCSI Primary Commands-3. 11050 [UML] ISO/IEC 19501, Unified Modeling Language 11051 Specification Version 1.4.2. 11053 [UNICODE] Unicode Standard Annex #15, "Unicode Normalization 11054 Forms", http://www.unicode.org/unicode/reports/tr15 11056 Informative References 11058 [RFC1737] K. Sollins, L. Masinter "Functional Requirements for 11059 Uniform Resource Names". 11061 [IB] InfiniBand{tm} Architecture Specification, Vol. 1, 11062 Rel.1.0.a, InfiniBand 11063 TradezAssociation(http://www.infinibandta.org). 11065 [Castagnoli93] G. Castagnoli, S. Braeuer and M. Herrman 11066 "Optimization of Cyclic Redundancy-Check Codes with 24 and 11067 32 Parity Bits", IEEE Transact. on Communications, Vol. 41, 11068 No. 6, June 1993. 11070 [CRC] ISO 3309, High-Level Data Link Control (CRC 32). 11072 [RFC2401] S. Kent, R. Atkinson, "Security Architecture for the 11073 Internet Protocol ", November 1998. 11075 [RFC2406] S. Kent, R. Atkinson, "IP Encapsulating Security 11076 Payload (ESP)", November 1998. 11078 [RFC2407] D. Piper, "The Internet IP Security Domain of 11079 Interpretation for ISAKMP", November 1998. 11081 [RFC2409] D. Harkins, D. Carrel, "The Internet Key Exchange 11082 (IKE)", November 1998. 11084 [RFC3385] Sheinwald, D., Staran, J., Thaler, P. and V. 11085 Cavanna, "Internet Protocol Small Computer System Interface 11086 (iSCSI) Cyclic Redundancy Check (CRC)/Checksum 11087 Considerations", RFC 3385, September 2002. 11089 [RFC3720] Satran, J., Meth, K., Sapuntzakis, C., Chadalapaka, 11090 M., and E. Zeidner, "Internet Small Computer Systems 11091 Interface (iSCSI)", RFC 3720, April 2004. 11093 [RFC3721] Bakke, M., Hafner, J., Hufferd, J., Voruganti, K. 11094 and M. Krueger, "Internet Small Computer Systems Interface 11095 (iSCSI) Naming and Discovery", RFC 3721, March 2004 11097 [RFC3783] M. Chadalapaka, R. Elliott, "Small Computer Systems 11098 Interface (SCSI) Command Ordering Considerations with 11099 iSCSI", RFC 3783, May 2004. 11101 [RFC4297] Romanow, A., Mogul, J., Talpey, T., and S. Bailey, 11102 "Remote Direct Memory Access (RDMA) over IP Problem 11103 Statement", RFC 4297, October 2004 11105 [RFC4850] Wysochanski, D., "Declarative Public Extension Key 11106 for Internet Small Computer Systems Interface (iSCSI) Node 11107 Architecture", RFC 4850, April 2007. 11109 [RFC5046] Ko, M., Chadalapaka, M., Hufferd, J., Elzur, U., 11110 Shah, H., and P. Thaler, "Internet Small Computer System 11111 Interface (iSCSI) Extensions for Remote Direct Memory Access 11112 (RDMA)", RFC 5046, October 2007 11114 [RFC5048] Chadalapaka, M., "Internet Small Computer Systems 11115 Interface (iSCSI) Corrections and Clarifications", RFC 5048, 11116 October 2007. 11118 [RFC6648] P. Saint-Andre, D. Crocker, M. Nottingham, 11119 "Deprecating the X- Prefix and Similar Constructs in 11120 Application Protocols", RFC 6648, June 2012 11122 [SAS] T10/2125-D, Serial Attached SCSI - 2.1 (SAS-2.1); 11123 T10/2124-D, SAS Protocol Layer (SPL); T10/2124-M, SAS 11124 Protocol Layer (SPL) Amendment #1 (SPL AM1). 11126 [SBC2] NCITS.405-205, SCSI Block Commands - 2 (SBC-2). 11128 [SPC4] T10/1731-D, SCSI Primary Commands-4. 11130 Appendix A. Examples 11132 Read Operation Example 11134 +------------------+-----------------------+---------------------+ 11135 |Initiator Function| PDU Type | Target Function | 11136 +------------------+-----------------------+---------------------+ 11137 | Command request |SCSI Command (READ)>>> | | 11138 | (read) | | | 11139 +------------------+-----------------------+---------------------+ 11140 | | |Prepare Data Transfer| 11141 +------------------+-----------------------+---------------------+ 11142 | Receive Data | <<< SCSI Data-in | Send Data | 11143 +------------------+-----------------------+---------------------+ 11144 | Receive Data | <<< SCSI Data-in | Send Data | 11145 +------------------+-----------------------+---------------------+ 11146 | Receive Data | <<< SCSI Data-in | Send Data | 11147 +------------------+-----------------------+---------------------+ 11148 | | <<< SCSI Response |Send Status and Sense| 11149 +------------------+-----------------------+---------------------+ 11150 | Command Complete | | | 11151 +------------------+-----------------------+---------------------+ 11153 Write Operation Example 11155 +------------------+-----------------------+---------------------+ 11156 |Initiator Function| PDU Type | Target Function | 11157 +------------------+-----------------------+---------------------+ 11158 | Command request |SCSI Command (WRITE)>>>| Receive command | 11159 | (write) | | and queue it | 11160 +------------------+-----------------------+---------------------+ 11161 | | | Process old commands| 11162 +------------------+-----------------------+---------------------+ 11163 | | | Ready to process | 11164 | | <<< R2T | WRITE command | 11165 +------------------+-----------------------+---------------------+ 11166 | Send Data | SCSI Data-out >>> | Receive Data | 11167 +------------------+-----------------------+---------------------+ 11168 | | <<< R2T | Ready for data | 11169 +------------------+-----------------------+---------------------+ 11170 | | <<< R2T | Ready for data | 11171 +------------------+-----------------------+---------------------+ 11172 | Send Data | SCSI Data-out >>> | Receive Data | 11173 +------------------+-----------------------+---------------------+ 11174 | Send Data | SCSI Data-out >>> | Receive Data | 11175 +------------------+-----------------------+---------------------+ 11176 | | <<< SCSI Response |Send Status and Sense| 11177 +------------------+-----------------------+---------------------+ 11178 | Command Complete | | | 11179 +------------------+-----------------------+---------------------+ 11181 R2TSN/DataSN Use Examples 11183 Output (write) data DataSN/R2TSN Example 11184 +------------------+-----------------------+---------------------+ 11185 |Initiator Function| PDU Type & Content | Target Function | 11186 +------------------+-----------------------+---------------------+ 11187 | Command request |SCSI Command (WRITE)>>>| Receive command | 11188 | (write) | | and queue it | 11189 +------------------+-----------------------+---------------------+ 11190 | | | Process old commands| 11191 +------------------+-----------------------+---------------------+ 11192 | | <<< R2T | Ready for data | 11193 | | R2TSN = 0 | | 11194 +------------------+-----------------------+---------------------+ 11195 | | <<< R2T | Ready for more data | 11196 | | R2TSN = 1 | | 11197 +------------------+-----------------------+---------------------+ 11198 | Send Data | SCSI Data-out >>> | Receive Data | 11199 | for R2TSN 0 | DataSN = 0, F=0 | | 11200 +------------------+-----------------------+---------------------+ 11201 | Send Data | SCSI Data-out >>> | Receive Data | 11202 | for R2TSN 0 | DataSN = 1, F=1 | | 11203 +------------------+-----------------------+---------------------+ 11204 | Send Data | SCSI Data >>> | Receive Data | 11205 | for R2TSN 1 | DataSN = 0, F=1 | | 11206 +------------------+-----------------------+---------------------+ 11207 | | <<< SCSI Response |Send Status and Sense| 11208 | | ExpDataSN = 0 | | 11209 +------------------+-----------------------+---------------------+ 11210 | Command Complete | | | 11211 +------------------+-----------------------+---------------------+ 11213 Input (read) data DataSN Example 11215 +------------------+-----------------------+---------------------+ 11216 |Initiator Function| PDU Type | Target Function | 11217 +------------------+-----------------------+---------------------+ 11218 | Command request |SCSI Command (READ)>>> | | 11219 | (read) | | | 11220 +------------------+-----------------------+---------------------+ 11221 | | |Prepare Data Transfer| 11222 +------------------+-----------------------+---------------------+ 11223 | Receive Data | <<< SCSI Data-in | Send Data | 11224 | | DataSN = 0, F=0 | | 11225 +------------------+-----------------------+---------------------+ 11226 | Receive Data | <<< SCSI Data-in | Send Data | 11227 | | DataSN = 1, F=0 | | 11228 +------------------+-----------------------+---------------------+ 11229 | Receive Data | <<< SCSI Data-in | Send Data | 11230 | | DataSN = 2, F=1 | | 11231 +------------------+-----------------------+---------------------+ 11232 | | <<< SCSI Response |Send Status and Sense| 11233 | | ExpDataSN = 3 | | 11234 +------------------+-----------------------+---------------------+ 11235 | Command Complete | | | 11236 +------------------+-----------------------+---------------------+ 11238 Bidirectional DataSN Example 11240 +------------------+-----------------------+---------------------+ 11241 |Initiator Function| PDU Type | Target Function | 11242 +------------------+-----------------------+---------------------+ 11243 | Command request |SCSI Command >>> | | 11244 | (Read-Write) | Read-Write | | 11245 +------------------+-----------------------+---------------------+ 11246 | | | Process old commands| 11247 +------------------+-----------------------+---------------------+ 11248 | | <<< R2T | Ready to process | 11249 | | R2TSN = 0 | WRITE command | 11250 +------------------+-----------------------+---------------------+ 11251 | * Receive Data | <<< SCSI Data-in | Send Data | 11252 | | DataSN = 0, F=0 | | 11253 +------------------+-----------------------+---------------------+ 11254 | * Receive Data | <<< SCSI Data-in | Send Data | 11255 | | DataSN = 1, F=1 | | 11256 +------------------+-----------------------+---------------------+ 11257 | * Send Data | SCSI Data-out >>> | Receive Data | 11258 | for R2TSN 0 | DataSN = 0, F=1 | | 11259 +------------------+-----------------------+---------------------+ 11260 | | <<< SCSI Response |Send Status and Sense| 11261 | | ExpDataSN = 2 | | 11262 +------------------+-----------------------+---------------------+ 11263 | Command Complete | | | 11264 +------------------+-----------------------+---------------------+ 11266 *) Send data and Receive Data may be transferred simultaneously as 11267 in an atomic Read-Old-Write-New or sequentially as in an atomic 11268 Read-Update-Write (in the latter case the R2T may follow the 11269 received data). 11271 Unsolicited and immediate output (write) data with DataSN Example 11272 +------------------+-----------------------+---------------------+ 11273 |Initiator Function| PDU Type & Content | Target Function | 11274 +------------------+-----------------------+---------------------+ 11275 | Command request |SCSI Command (WRITE)>>>| Receive command | 11276 | (write) |F=0 | and data | 11277 |+ immediate data | | and queue it | 11278 +------------------+-----------------------+---------------------+ 11279 | Send Unsolicited | SCSI Write Data >>> | Receive more Data | 11280 | Data | DataSN = 0, F=1 | | 11281 +------------------+-----------------------+---------------------+ 11282 | | | Process old commands| 11283 +------------------+-----------------------+---------------------+ 11284 | | <<< R2T | Ready for more data | 11285 | | R2TSN = 0 | | 11286 +------------------+-----------------------+---------------------+ 11287 | Send Data | SCSI Write Data >>> | Receive Data | 11288 | for R2TSN 0 | DataSN = 0, F=1 | | 11289 +------------------+-----------------------+---------------------+ 11290 | | <<< SCSI Response |Send Status and Sense| 11291 | | | | 11292 +------------------+-----------------------+---------------------+ 11293 | Command Complete | | | 11294 +------------------+-----------------------+---------------------+ 11296 CRC Examples 11298 N.B. all Values are Hexadecimal 11300 32 bytes of zeroes: 11302 Byte: 0 1 2 3 11304 0: 00 00 00 00 11305 ... 11306 28: 00 00 00 00 11308 CRC: aa 36 91 8a 11310 32 bytes of ones: 11312 Byte: 0 1 2 3 11313 0: ff ff ff ff 11314 ... 11315 28: ff ff ff ff 11317 CRC: 43 ab a8 62 11319 32 bytes of incrementing 00..1f: 11321 Byte: 0 1 2 3 11323 0: 00 01 02 03 11324 ... 11325 28: 1c 1d 1e 1f 11327 CRC: 4e 79 dd 46 11329 32 bytes of decrementing 1f..00: 11331 Byte: 0 1 2 3 11333 0: 1f 1e 1d 1c 11334 ... 11335 28: 03 02 01 00 11337 CRC: 5c db 3f 11 11339 An iSCSI - SCSI Read (10) Command PDU 11341 Byte: 0 1 2 3 11343 0: 01 c0 00 00 11344 4: 00 00 00 00 11345 8: 00 00 00 00 11346 12: 00 00 00 00 11347 16: 14 00 00 00 11348 20: 00 00 04 00 11349 24: 00 00 00 14 11350 28: 00 00 00 18 11351 32: 28 00 00 00 11352 36: 00 00 00 00 11353 40: 02 00 00 00 11354 44: 00 00 00 00 11356 CRC: 56 3a 96 d9 11358 Appendix B. Login Phase Examples 11360 In the first example, the initiator and target authenticate each 11361 other via Kerberos: 11363 I-> Login (CSG,NSG=0,1 T=1) 11364 InitiatorName=iqn.1999-07.com.os:hostid.77 11365 TargetName=iqn.1999-07.com.example:diskarray.sn.88 11366 AuthMethod=KRB5,SRP,None 11368 T-> Login (CSG,NSG=0,0 T=0) 11369 AuthMethod=KRB5 11371 I-> Login (CSG,NSG=0,1 T=1) 11372 KRB_AP_REQ= 11374 (krb_ap_req contains the Kerberos V5 ticket and authenticator with 11375 MUTUAL-REQUIRED set in the ap-options field) 11377 If the authentication is successful, the target proceeds with: 11379 T-> Login (CSG,NSG=0,1 T=1) 11380 KRB_AP_REP= 11382 (krb_ap_rep is the Kerberos V5 mutual authentication reply) 11384 If the authentication is successful, the initiator may proceed 11385 with: 11387 I-> Login (CSG,NSG=1,0 T=0) FirstBurstLength=8192 11388 T-> Login (CSG,NSG=1,0 T=0) FirstBurstLength=4096 11389 MaxBurstLength=8192 11390 I-> Login (CSG,NSG=1,0 T=0) MaxBurstLength=8192 11391 ... more iSCSI Operational Parameters 11393 T-> Login (CSG,NSG=1,0 T=0) 11394 ... more iSCSI Operational Parameters 11396 And at the end: 11398 I-> Login (CSG,NSG=1,3 T=1) 11399 optional iSCSI parameters 11401 T-> Login (CSG,NSG=1,3 T=1) "login accept" 11403 If the initiator's authentication by the target is not successful, 11404 the target responds with: 11406 T-> Login "login reject" 11408 instead of the Login KRB_AP_REP message, and terminates the 11409 connection. 11411 If the target's authentication by the initiator is not successful, 11412 the initiator terminates the connection (without responding to the 11413 Login KRB_AP_REP message). 11415 In the next example only the initiator is authenticated by the 11416 target via Kerberos: 11418 I-> Login (CSG,NSG=0,1 T=1) 11419 InitiatorName=iqn.1999-07.com.os:hostid.77 11420 TargetName=iqn.1999-07.com.example:diskarray.sn.88 11421 AuthMethod=SRP,KRB5,None 11423 T-> Login-PR (CSG,NSG=0,0 T=0) 11424 AuthMethod=KRB5 11426 I-> Login (CSG,NSG=0,1 T=1) 11427 KRB_AP_REQ=krb_ap_req 11429 (MUTUAL-REQUIRED not set in the ap-options field of krb_ap_req) 11431 If the authentication is successful, the target proceeds with: 11433 T-> Login (CSG,NSG=0,1 T=1) 11435 I-> Login (CSG,NSG=1,0 T=0) 11436 ... iSCSI parameters 11438 T-> Login (CSG,NSG=1,0 T=0) 11439 ... iSCSI parameters 11441 . . . 11443 T-> Login (CSG,NSG=1,3 T=1)"login accept" 11445 In the next example, the initiator and target authenticate each 11446 other via SRP: 11448 I-> Login (CSG,NSG=0,1 T=1) 11449 InitiatorName=iqn.1999-07.com.os:hostid.77 11450 TargetName=iqn.1999-07.com.example:diskarray.sn.88 11451 AuthMethod=KRB5,SRP,None 11453 T-> Login-PR (CSG,NSG=0,0 T=0) 11454 AuthMethod=SRP 11456 I-> Login (CSG,NSG=0,0 T=0) 11457 SRP_U= 11458 TargetAuth=Yes 11460 T-> Login (CSG,NSG=0,0 T=0) 11461 SRP_N= 11462 SRP_g= 11463 SRP_s= 11465 I-> Login (CSG,NSG=0,0 T=0) 11466 SRP_A= 11468 T-> Login (CSG,NSG=0,0 T=0) 11469 SRP_B= 11471 I-> Login (CSG,NSG=0,1 T=1) 11472 SRP_M= 11474 If the initiator authentication is successful, the target 11475 proceeds: 11477 T-> Login (CSG,NSG=0,1 T=1) 11478 SRP_HM= 11480 Where N, g, s, A, B, M, and H(A | M | K) are defined in 11481 [RFC2945]. 11483 If the target authentication is not successful, the initiator 11484 terminates the connection; otherwise, it proceeds. 11486 I-> Login (CSG,NSG=1,0 T=0) 11487 ... iSCSI parameters 11489 T-> Login (CSG,NSG=1,0 T=0) 11490 ... iSCSI parameters 11492 And at the end: 11494 I-> Login (CSG,NSG=1,3 T=1) 11495 optional iSCSI parameters 11497 T-> Login (CSG,NSG=1,3 T=1) "login accept" 11499 If the initiator authentication is not successful, the target 11500 responds with: 11502 T-> Login "login reject" 11504 Instead of the T-> Login SRP_HM= message and 11505 terminates the connection. 11507 In the next example, only the initiator is authenticated by the 11508 target via SRP: 11510 I-> Login (CSG,NSG=0,1 T=1) 11511 InitiatorName=iqn.1999-07.com.os:hostid.77 11512 TargetName=iqn.1999-07.com.example:diskarray.sn.88 11513 AuthMethod=KRB5,SRP,None 11515 T-> Login-PR (CSG,NSG=0,0 T=0) 11516 AuthMethod=SRP 11518 I-> Login (CSG,NSG=0,0 T=0) 11519 SRP_U= 11520 TargetAuth=No 11522 T-> Login (CSG,NSG=0,0 T=0) 11523 SRP_N= 11524 SRP_g= 11525 SRP_s= 11527 I-> Login (CSG,NSG=0,0 T=0) 11528 SRP_A= 11530 T-> Login (CSG,NSG=0,0 T=0) 11531 SRP_B= 11533 I-> Login (CSG,NSG=0,1 T=1) 11534 SRP_M= 11536 If the initiator authentication is successful, the target 11537 proceeds: 11539 T-> Login (CSG,NSG=0,1 T=1) 11541 I-> Login (CSG,NSG=1,0 T=0) 11543 ... iSCSI parameters 11545 T-> Login (CSG,NSG=1,0 T=0) 11547 ... iSCSI parameters 11549 And at the end: 11551 I-> Login (CSG,NSG=1,3 T=1) 11553 optional iSCSI parameters 11555 T-> Login (CSG,NSG=1,3 T=1) "login accept" 11557 In the next example the initiator and target authenticate each 11558 other via CHAP: 11560 I-> Login (CSG,NSG=0,0 T=0) 11562 InitiatorName=iqn.1999-07.com.os:hostid.77 11564 TargetName=iqn.1999-07.com.example:diskarray.sn.88 11566 AuthMethod=KRB5,CHAP,None 11568 T-> Login-PR (CSG,NSG=0,0 T=0) 11570 AuthMethod=CHAP 11572 I-> Login (CSG,NSG=0,0 T=0) 11574 CHAP_A= 11576 T-> Login (CSG,NSG=0,0 T=0) 11577 CHAP_A= 11578 CHAP_I= 11579 CHAP_C= 11581 I-> Login (CSG,NSG=0,1 T=1) 11582 CHAP_N= 11584 CHAP_R= 11586 CHAP_I= 11588 CHAP_C= 11590 If the initiator authentication is successful, the target 11591 proceeds: 11593 T-> Login (CSG,NSG=0,1 T=1) 11595 CHAP_N= 11597 CHAP_R= 11599 If the target authentication is not successful, the initiator 11600 aborts the connection; otherwise, it proceeds. 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 If the initiator authentication is not successful, the target 11619 responds with: 11621 T-> Login "login reject" 11623 Instead of the Login CHAP_R= "proceed and change 11624 stage" message and terminates the connection. 11626 In the next example, only the initiator is authenticated by the 11627 target via CHAP: 11629 I-> Login (CSG,NSG=0,1 T=0) 11631 InitiatorName=iqn.1999-07.com.os:hostid.77 11633 TargetName=iqn.1999-07.com.example:diskarray.sn.88 11635 AuthMethod=KRB5,CHAP,None 11637 T-> Login-PR (CSG,NSG=0,0 T=0) 11639 AuthMethod=CHAP 11641 I-> Login (CSG,NSG=0,0 T=0) 11643 CHAP_A= 11645 T-> Login (CSG,NSG=0,0 T=0) 11646 CHAP_A= 11647 CHAP_I= 11648 CHAP_C= 11650 I-> Login (CSG,NSG=0,1 T=1) 11652 CHAP_N= 11654 CHAP_R= 11656 If the initiator authentication is successful, the target 11657 proceeds: 11659 T-> Login (CSG,NSG=0,1 T=1) 11661 I-> Login (CSG,NSG=1,0 T=0) 11663 ... iSCSI parameters 11665 T-> Login (CSG,NSG=1,0 T=0) 11667 ... iSCSI parameters 11669 And at the end: 11671 I-> Login (CSG,NSG=1,3 T=1) 11673 optional iSCSI parameters 11675 T-> Login (CSG,NSG=1,3 T=1) "login accept" 11677 In the next example, the initiator does not offer any security 11678 parameters. It therefore may offer iSCSI parameters on the Login 11679 PDU with the T bit set to 1, and the target may respond with a 11680 final Login Response PDU immediately: 11682 I-> Login (CSG,NSG=1,3 T=1) 11684 InitiatorName=iqn.1999-07.com.os:hostid.77 11686 TargetName=iqn.1999-07.com.example:diskarray.sn.88 11688 ... iSCSI parameters 11690 T-> Login (CSG,NSG=1,3 T=1) "login accept" 11692 ... ISCSI parameters 11694 In the next example, the initiator does offer security 11695 parameters on the Login PDU, but the target does not choose 11696 any (i.e., chooses the "None" values): 11698 I-> Login (CSG,NSG=0,1 T=1) 11700 InitiatorName=iqn.1999-07.com.os:hostid.77 11702 TargetName=iqn.1999-07.com.example:diskarray.sn.88 11704 AuthMethod=KRB5,SRP,None 11706 T-> Login-PR (CSG,NSG=0,1 T=1) 11708 AuthMethod=None 11710 I-> Login (CSG,NSG=1,0 T=0) 11712 ... iSCSI parameters 11714 T-> Login (CSG,NSG=1,0 T=0) 11716 ... iSCSI parameters 11718 And at the end: 11720 I-> Login (CSG,NSG=1,3 T=1) 11722 optional iSCSI parameters 11724 T-> Login (CSG,NSG=1,3 T=1) "login accept" 11726 Appendix C. SendTargets Operation 11728 The text in this Appendix is a normative part of this document. 11730 To reduce the amount of configuration required on an initiator, 11731 iSCSI provides the SendTargets text request. The initiator uses 11732 the SendTargets request to get a list of targets to which it may 11733 have access, as well as the list of addresses (IP address and TCP 11734 port) on which these targets may be accessed. 11736 To make use of SendTargets, an initiator must first establish one 11737 of two types of sessions. If the initiator establishes 11738 the session using the key "SessionType=Discovery", the session is 11739 a discovery session, and a target name does not need to be 11740 specified. Otherwise, the session is a normal, operational 11741 session. The SendTargets command MUST only be sent during the 11742 Full Feature Phase of a normal or discovery session. 11744 A system that contains targets MUST support discovery sessions on 11745 each of its iSCSI IP address-port pairs, and MUST support the 11746 SendTargets command on the discovery session. In a discovery 11747 session, a target MUST return all path information (IP address- 11748 port pairs and portal group tags) for the targets on the target 11749 network entity which the requesting initiator is authorized to 11750 access. 11752 A target MUST support the SendTargets command on operational 11753 sessions; these will only return path information about the target 11754 to which the session is connected, and do not need to return 11755 information about other target names that may be defined in the 11756 responding system. 11758 An initiator MAY make use of the SendTargets as it sees fit. 11760 A SendTargets command consists of a single Text request PDU. 11761 This PDU contains exactly one text key and value. The text key 11762 MUST be SendTargets. The expected response depends upon the 11763 value, as well as whether the session is a discovery or 11764 operational session. 11766 The value must be one of: 11768 All 11770 The initiator is requesting that information on all relevant 11771 targets known to the implementation be returned. This value 11772 MUST be supported on a discovery session, and MUST NOT be 11773 supported on an operational session. 11775 11777 If an iSCSI target name is specified, the session should 11778 respond with addresses for only the named target, if 11779 possible. This value MUST be supported on discovery 11781 sessions. A discovery session MUST be capable of returning 11782 addresses for those targets that would have been returned 11783 had value=All been designated. 11785 11787 The session should only respond with addresses for the target 11788 to which the session is logged in. This MUST be supported 11789 on operational sessions, and MUST NOT return targets other 11790 than the one to which the session is logged in. 11792 The response to this command is a text response that contains a 11793 list of zero or more targets and, optionally, their addresses. 11794 Each target is returned as a target record. A target record 11795 begins with the TargetName text key, followed by a list of 11796 TargetAddress text keys, and bounded by the end of the text 11797 response or the next TargetName key, which begins a new record. 11798 No text keys other than TargetName and TargetAddress are permitted 11799 within a SendTargets response. 11801 For the format of the TargetName, see Section 13.4. 11803 A discovery session MAY respond to a SendTargets request with its 11804 complete list of targets, or with a list of targets that is based 11805 on the name of the initiator logged in to the session. 11807 A SendTargets response MUST NOT contain target names if there are 11808 no targets for the requesting initiator to access. 11810 Each target record returned includes zero or more TargetAddress 11811 fields. 11813 Each target record starts with one text key of the form: 11815 TargetName= 11817 Followed by zero or more address keys of the form: 11819 TargetAddress=[:], 11822 The hostname-or-ipaddress contains a domain name, IPv4 address, or 11823 IPv6 address ([RFC4291]), as specified for the TargetAddress key. 11825 A hostname-or-ipaddress duplicated in TargetAddress responses for 11826 a given node (the port is absent or equal) would probably indicate 11827 that multiple address families are in use at once (IPv6 and IPv4). 11829 Each TargetAddress belongs to a portal group, identified by its 11830 numeric portal group tag (as in Section 13.9). The iSCSI target 11831 name, together with this tag, constitutes the SCSI port 11832 identifier; the tag only needs to be unique within a given 11833 target's name list of addresses. 11835 Multiple-connection sessions can span iSCSI addresses that belong 11836 to the same portal group. 11838 Multiple-connection sessions cannot span iSCSI addresses that 11839 belong to different portal groups. 11841 If a SendTargets response reports an iSCSI address for a target, 11842 it SHOULD also report all other addresses in its portal group in 11843 the same response. 11845 A SendTargets text response can be longer than a single Text 11846 Response PDU, and makes use of the long text responses as 11847 specified. 11849 After obtaining a list of targets from the discovery target 11850 session, 11851 an iSCSI initiator may initiate new sessions to log in to the 11852 discovered targets for full operation. The initiator MAY keep the 11853 discovery session open, and MAY send subsequent SendTargets 11854 commands to discover new targets. 11856 Examples: 11858 This example is the SendTargets response from a single target that 11859 has no other interface ports. 11861 Initiator sends text request that contains: 11863 SendTargets=All 11865 Target sends a text response that contains: 11867 TargetName=iqn.1993-11.com.example:diskarray.sn.8675309 11869 All the target had to return in the simple case was the target 11870 name. It is assumed by the initiator that the IP address and TCP 11871 port for this target are the same as used on the current 11872 connection to the default iSCSI target. 11874 The next example has two internal iSCSI targets, each accessible 11875 via two different ports with different IP addresses. The 11876 following is the text response: 11878 TargetName=iqn.1993-11.com.example:diskarray.sn.8675309 11880 TargetAddress=10.1.0.45:3000,1 11882 TargetAddress=10.1.1.45:3000,2 11884 TargetName=iqn.1993-11.com.example:diskarray.sn.1234567 11886 TargetAddress=10.1.0.45:3000,1 11888 TargetAddress=10.1.1.45:3000,2 11890 Both targets share both addresses; the multiple addresses are 11891 likely used to provide multi-path support. The initiator may 11892 connect to either target name on either address. Each of the 11893 addresses has its own portal group tag; they do not support 11894 spanning multiple-connection sessions with each other. Keep in 11895 mind that the portal group tags for the two named targets are 11896 independent of one another; portal group "1" on the first target 11897 is not necessarily the same as portal group "1" on the second 11898 target. 11900 In the above example, a DNS host name or an IPv6 address could 11901 have been returned instead of an IPv4 address. 11903 The next text response shows a target that supports spanning 11904 sessions across multiple addresses, and further illustrates the 11905 use of the portal group tags: 11907 TargetName=iqn.1993-11.com.example:diskarray.sn.8675309 11909 TargetAddress=10.1.0.45:3000,1 11911 TargetAddress=10.1.1.46:3000,1 11913 TargetAddress=10.1.0.47:3000,2 11915 TargetAddress=10.1.1.48:3000,2 11917 TargetAddress=10.1.1.49:3000,3 11919 In this example, any of the target addresses can be used to reach 11920 the same target. A single-connection session can be established 11921 to any of these TCP addresses. A multiple-connection session 11922 could span addresses .45 and .46 or .47 and .48, but cannot span 11923 any other combination. A TargetAddress with its own tag (.49) 11924 cannot be combined with any other address within the same session. 11926 This SendTargets response does not indicate whether .49 supports 11927 multiple connections per session; it is communicated via the 11928 MaxConnections text key upon login to the target. 11930 Appendix D. Algorithmic Presentation of Error Recovery Classes 11932 This Appendix illustrates the error recovery classes using a 11933 pseudo-programming-language. The procedure names are chosen to be 11934 obvious to most implementers. Each of the recovery classes 11935 described has initiator procedures as well as target procedures. 11936 These algorithms focus on outlining the mechanics of error 11937 recovery classes, and do not exhaustively describe all other 11938 aspects/cases. Examples of this approach are: 11940 - Handling for only certain Opcode types is shown. 11942 - Only certain reason codes (e.g., Recovery in Logout command) 11943 are outlined. 11945 - Resultant cases, such as recovery of Synchronization on a 11946 header digest error are considered out-of-scope in these 11947 algorithms. In this particular example, a header digest 11948 error may lead to connection recovery if some type of sync 11949 and steering layer is not implemented. 11951 These algorithms strive to convey the iSCSI error recovery 11952 concepts in the simplest terms, and are not designed to be 11953 optimal. 11955 D.1. General Data Structure and Procedure Description 11957 This Section defines the procedures and data structures that are 11958 commonly used by all the error recovery algorithms. The structures 11959 may not be the exhaustive representations of what is required for 11960 a typical implementation. 11962 Data structure definitions - 11963 struct TransferContext { 11964 int TargetTransferTag; 11965 int ExpectedDataSN; 11966 }; 11968 struct TCB { /* task control block */ 11969 Boolean SoFarInOrder; 11970 int ExpectedDataSN; /* used for both R2Ts, and Data */ 11971 int MissingDataSNList[MaxMissingDPDU]; 11972 Boolean FbitReceived; 11973 Boolean StatusXferd; 11974 Boolean CurrentlyAllegiant; 11975 int ActiveR2Ts; 11976 int Response; 11977 char *Reason; 11978 struct TransferContext 11979 TransferContextList[MaxOutStandingR2T]; 11980 int InitiatorTaskTag; 11981 int CmdSN; 11982 int SNACK_Tag; 11983 }; 11985 struct Connection { 11986 struct Session SessionReference; 11987 Boolean SoFarInOrder; 11988 int CID; 11989 int State; 11990 int CurrentTimeout; 11991 int ExpectedStatSN; 11992 int MissingStatSNList[MaxMissingSPDU]; 11993 Boolean PerformConnectionCleanup; 11994 }; 11996 struct Session { 11997 int NumConnections; 11998 int CmdSN; 11999 int Maxconnections; 12000 int ErrorRecoveryLevel; 12001 struct iSCSIEndpoint OtherEndInfo; 12002 struct Connection ConnectionList[MaxSupportedConns]; 12003 }; 12005 Procedure descriptions - 12006 Receive-a-In-PDU(transport connection, inbound PDU); 12007 check-basic-validity(inbound PDU); 12008 Start-Timer(timeout handler, argument, timeout value); 12009 Build-And-Send-Reject(transport connection, bad PDU, reason 12010 code); 12012 D.2. Within-command Error Recovery Algorithms 12014 D.2.1. Procedure Descriptions 12016 Recover-Data-if-Possible(last required DataSN, task control 12017 block); 12018 Build-And-Send-DSnack(task control block); 12019 Build-And-Send-RDSnack(task control block); 12020 Build-And-Send-Abort(task control block); 12021 SCSI-Task-Completion(task control block); 12022 Build-And-Send-A-Data-Burst(transport connection, data- 12023 descriptor, 12024 task control 12025 block); 12026 Build-And-Send-R2T(transport connection, data-descriptor, 12027 task control 12028 block); 12029 Build-And-Send-Status(transport connection, task control block); 12030 Transfer-Context-Timeout-Handler(transfer context); 12032 Notes: 12034 - One procedure used in this Section: Handle-Status-SNACK- 12035 request is defined in Within-connection recovery algorithms. 12037 - The Response processing pseudo-code, shown in the target 12038 algorithms, applies to all solicited PDUs that carry StatSN 12039 - SCSI Response, Text Response etc. 12041 D.2.2. Initiator Algorithms 12043 Recover-Data-if-Possible(LastRequiredDataSN, TCB) 12044 { 12045 if (operational ErrorRecoveryLevel > 0) { 12046 if (# of missing PDUs is trackable) { 12047 Note the missing DataSNs in TCB. 12048 if (the task spanned a change in 12049 MaxRecvDataSegmentLength) { 12050 if (TCB.StatusXferd is TRUE) 12051 drop the status PDU; 12052 Build-And-Send-RDSnack(TCB); 12053 } else { 12054 Build-And-Send-DSnack(TCB); 12055 } 12057 } else { 12058 TCB.Reason = "Protocol service CRC error"; 12059 } 12060 } else { 12061 TCB.Reason = "Protocol service CRC error"; 12062 } 12063 if (TCB.Reason == "Protocol service CRC error") { 12064 Clear the missing PDU list in the TCB. 12065 if (TCB.StatusXferd is not TRUE) 12066 Build-And-Send-Abort(TCB); 12067 } 12068 } 12070 Receive-a-In-PDU(Connection, CurrentPDU) 12071 { 12072 check-basic-validity(CurrentPDU); 12073 if (Header-Digest-Bad) discard, return; 12074 Retrieve TCB for CurrentPDU.InitiatorTaskTag. 12075 if ((CurrentPDU.type == Data) 12076 or (CurrentPDU.type = R2T)) { 12077 if (Data-Digest-Bad for Data) { 12078 send-data-SNACK = TRUE; 12079 LastRequiredDataSN = CurrentPDU.DataSN; 12080 } else { 12081 if (TCB.SoFarInOrder = TRUE) { 12082 if (current DataSN is expected) { 12083 Increment TCB.ExpectedDataSN. 12084 } else { 12085 TCB.SoFarInOrder = FALSE; 12086 send-data-SNACK = TRUE; 12087 } 12088 } else { 12089 if (current DataSN was considered 12090 missing) { 12091 remove current DataSN from missing 12092 PDU list. 12093 } else if (current DataSN is higher than 12094 expected) { 12095 send-data-SNACK = TRUE; 12096 } else { 12097 discard, return; 12098 } 12099 Adjust TCB.ExpectedDataSN if 12100 appropriate. 12101 } 12102 LastRequiredDataSN = CurrentPDU.DataSN - 1; 12103 } 12104 if (send-data-SNACK is TRUE and 12105 task is not already considered failed) { 12106 Recover-Data-if-Possible(LastRequiredDataSN, TCB); 12107 } 12108 if (missing data PDU list is empty) { 12109 TCB.SoFarInOrder = TRUE; 12110 } 12111 if (CurrentPDU.type == R2T) { 12112 Increment ActiveR2Ts for this task. 12113 Create a data-descriptor for the data burst. 12114 Build-And-Send-A-Data-Burst(Connection, data- 12115 descriptor, 12116 TCB); 12117 } 12118 } else if (CurrentPDU.type == Response) { 12119 if (Data-Digest-Bad) { 12120 send-status-SNACK = TRUE; 12121 } else { 12122 TCB.StatusXferd = TRUE; 12123 Store the status information in TCB. 12124 if (ExpDataSN does not match) { 12125 TCB.SoFarInOrder = FALSE; 12126 Recover-Data-if-Possible(current DataSN, TCB); 12127 } 12128 if (missing data PDU list is empty) { 12129 TCB.SoFarInOrder = TRUE; 12130 } 12131 } 12132 } else { /* REST UNRELATED TO WITHIN-COMMAND-RECOVERY, NOT 12133 SHOWN */ 12134 } 12135 if ((TCB.SoFarInOrder == TRUE) and 12136 (TCB.StatusXferd == TRUE)) { 12138 SCSI-Task-Completion(TCB); 12139 } 12140 } 12142 D.2.3. Target Algorithms 12144 Receive-a-In-PDU(Connection, CurrentPDU) 12145 { 12146 check-basic-validity(CurrentPDU); 12147 if (Header-Digest-Bad) discard, return; 12148 Retrieve TCB for CurrentPDU.InitiatorTaskTag. 12149 if (CurrentPDU.type == Data) { 12150 Retrieve TContext from CurrentPDU.TargetTransferTag; 12151 if (Data-Digest-Bad) { 12152 Build-And-Send-Reject(Connection, CurrentPDU, 12153 Payload-Digest-Error); 12154 Note the missing data PDUs in MissingDataRange[]. 12155 send-recovery-R2T = TRUE; 12156 } else { 12157 if (current DataSN is not expected) { 12158 Note the missing data PDUs in MissingDataRange[]. 12159 send-recovery-R2T = TRUE; 12160 } 12161 if (CurrentPDU.Fbit == TRUE) { 12162 if (current PDU is solicited) { 12163 Decrement TCB.ActiveR2Ts. 12164 } 12165 if ((current PDU is unsolicited and 12166 data received is less than I/O length and 12167 data received is less than 12168 FirstBurstLength) 12169 or (current PDU is solicited and the length of 12170 this burst is less than expected)) { 12171 send-recovery-R2T = TRUE; 12172 Note the missing data in MissingDataRange[]. 12173 } 12174 } 12175 } 12176 Increment TContext.ExpectedDataSN. 12177 if (send-recovery-R2T is TRUE and 12178 task is not already considered failed) { 12179 if (operational ErrorRecoveryLevel > 0) { 12180 Increment TCB.ActiveR2Ts. 12181 Create a data-descriptor for the data burst 12182 from MissingDataRange. 12183 Build-And-Send-R2T(Connection, data-descriptor, 12184 TCB); 12185 } else { 12186 if (current PDU is the last unsolicited) 12187 TCB.Reason = "Not enough unsolicited data"; 12188 else 12189 TCB.Reason = "Protocol service CRC error"; 12190 } 12191 } 12192 if (TCB.ActiveR2Ts == 0) { 12193 Build-And-Send-Status(Connection, TCB); 12194 } 12195 } else if (CurrentPDU.type == SNACK) { 12196 snack-failure = FALSE; 12197 if (operational ErrorRecoveryLevel > 0) { 12198 if (CurrentPDU.type == Data/R2T) { 12199 if (the request is satisfiable) { 12200 if (request for Data) { 12201 Create a data-descriptor for the data burst 12202 from BegRun and RunLength. 12203 Build-And-Send-A-Data-Burst(Connection, 12204 data-descriptor, TCB); 12205 } else { /* R2T */ 12206 Create a data-descriptor for the data burst 12207 from BegRun and RunLength. 12208 Build-And-Send-R2T(Connection, data- 12209 descriptor, 12210 TCB); 12211 } 12212 } else { 12213 snack-failure = TRUE; 12214 } 12215 } else if (CurrentPDU.type == status) { 12216 Handle-Status-SNACK-request(Connection, 12217 CurrentPDU); 12218 } else if (CurrentPDU.type == DataACK) { 12219 Consider all data upto CurrentPDU.BegRun as 12220 acknowledged. 12221 Free up the retransmission resources for that data. 12222 } else if (CurrentPDU.type == R-Data SNACK) { 12223 Create a data descriptor for a data burst 12224 covering 12225 all unacknowledged data. 12226 Build-And-Send-A-Data-Burst(Connection, 12227 data-descriptor, TCB); 12228 TCB.SNACK_Tag = CurrentPDU.SNACK_Tag; 12229 if (there's no more data to send) { 12230 Build-And-Send-Status(Connection, TCB); 12231 } 12232 } 12233 } else { /* operational ErrorRecoveryLevel = 0 */ 12234 snack-failure = TRUE; 12235 } 12236 if (snack-failure == TRUE) { 12237 Build-And-Send-Reject(Connection, CurrentPDU, 12238 SNACK-Reject); 12239 if (TCB.StatusXferd != TRUE) { 12240 TCB.Reason = "SNACK Rejected"; 12241 Build-And-Send-Status(Connection, TCB); 12242 } 12243 } 12245 } else { /* REST UNRELATED TO WITHIN-COMMAND-RECOVERY, NOT 12246 SHOWN */ 12247 } 12248 } 12250 Transfer-Context-Timeout-Handler(TContext) 12251 { 12252 Retrieve TCB and Connection from TContext. 12253 Decrement TCB.ActiveR2Ts. 12254 if (operational ErrorRecoveryLevel > 0 and 12255 task is not already considered failed) { 12256 Note the missing data PDUs in MissingDataRange[]. 12257 Create a data-descriptor for the data burst 12258 from MissingDataRange[]. 12259 Build-And-Send-R2T(Connection, data-descriptor, TCB); 12261 } else { 12262 TCB.Reason = "Protocol service CRC error"; 12263 if (TCB.ActiveR2Ts = 0) { 12264 Build-And-Send-Status(Connection, TCB); 12265 } 12266 } 12267 } 12269 D.3. Within-connection Recovery Algorithms 12271 D.3.1. Procedure Descriptions 12273 Procedure descriptions: 12274 Recover-Status-if-Possible(transport connection, 12275 currently received PDU); 12276 Evaluate-a-StatSN(transport connection, currently received PDU); 12277 Retransmit-Command-if-Possible(transport connection, CmdSN); 12278 Build-And-Send-SSnack(transport connection); 12279 Build-And-Send-Command(transport connection, task control 12280 block); 12281 Command-Acknowledge-Timeout-Handler(task control block); 12282 Status-Expect-Timeout-Handler(transport connection); 12283 Build-And-Send-Nop-Out(transport connection); 12284 Handle-Status-SNACK-request(transport connection, status SNACK 12285 PDU); 12286 Retransmit-Status-Burst(status SNACK, task control block); 12287 Is-Acknowledged(beginning StatSN, run length); 12289 Implementation-specific tunables: 12290 InitiatorProactiveSNACKEnabled 12292 Notes: 12293 - The initiator algorithms only deal with unsolicited Nop-In 12294 PDUs for generating status SNACKs. A solicited Nop-In PDU 12295 has an assigned StatSN, which, when out of order, could 12296 trigger the out of order StatSN handling in Within-command 12297 algorithms, again leading to Recover-Status-if-Possible. 12299 - The pseudo-code shown may result in the retransmission of 12300 unacknowledged commands in more cases than necessary. This 12301 will not, however, affect the correctness of the operation 12302 because the target is required to discard the duplicate 12303 CmdSNs. 12305 - The procedure Build-And-Send-Async is defined in the 12306 Connection recovery algorithms. 12308 - The procedure Status-Expect-Timeout-Handler describes how 12309 initiators may proactively attempt to retrieve the Status if 12310 they so choose. This procedure is assumed to be triggered 12311 much before the standard ULP timeout. 12313 D.3.2. Initiator Algorithms 12315 Recover-Status-if-Possible(Connection, CurrentPDU) 12316 { 12317 if ((Connection.state == LOGGED_IN) and 12318 connection is not already considered 12319 failed) { 12320 if (operational ErrorRecoveryLevel > 0) { 12321 if (# of missing PDUs is trackable) { 12322 Note the missing StatSNs in Connection 12323 that were not already requested with SNACK; 12324 Build-And-Send-SSnack(Connection); 12325 } else { 12326 Connection.PerformConnectionCleanup = TRUE; 12327 } 12328 } else { 12329 Connection.PerformConnectionCleanup = TRUE; 12330 } 12331 if (Connection.PerformConnectionCleanup == TRUE) { 12332 Start-Timer(Connection-Cleanup-Handler, Connection, 12333 0); 12334 } 12335 } 12337 } 12339 Retransmit-Command-if-Possible(Connection, CmdSN) 12340 { 12341 if (operational ErrorRecoveryLevel > 0) { 12342 Retrieve the InitiatorTaskTag, and thus TCB for the 12343 CmdSN. 12344 Build-And-Send-Command(Connection, TCB); 12345 } 12346 } 12348 Evaluate-a-StatSN(Connection, CurrentPDU) 12349 { 12350 send-status-SNACK = FALSE; 12351 if (Connection.SoFarInOrder == TRUE) { 12352 if (current StatSN is the expected) { 12353 Increment Connection.ExpectedStatSN. 12354 } else { 12355 Connection.SoFarInOrder = FALSE; 12356 send-status-SNACK = TRUE; 12357 } 12358 } else { 12359 if (current StatSN was considered missing) { 12360 remove current StatSN from the missing list. 12361 } else { 12362 if (current StatSN is higher than expected){ 12363 send-status-SNACK = TRUE; 12364 } else { 12365 send-status-SNACK = FALSE; 12366 discard the PDU; 12367 } 12368 } 12369 Adjust Connection.ExpectedStatSN if appropriate. 12370 if (missing StatSN list is empty) { 12371 Connection.SoFarInOrder = TRUE; 12372 } 12373 } 12374 return send-status-SNACK; 12375 } 12376 Receive-a-In-PDU(Connection, CurrentPDU) 12377 { 12378 check-basic-validity(CurrentPDU); 12379 if (Header-Digest-Bad) discard, return; 12380 Retrieve TCB for CurrentPDU.InitiatorTaskTag. 12381 if (CurrentPDU.type == Nop-In) { 12382 if (the PDU is unsolicited) { 12383 if (current StatSN is not expected) { 12384 Recover-Status-if-Possible(Connection, 12385 CurrentPDU); 12386 } 12387 if (current ExpCmdSN is not Session.CmdSN) { 12388 Retransmit-Command-if-Possible(Connection, 12389 CurrentPDU.ExpCmdSN); 12390 } 12391 } 12392 } else if (CurrentPDU.type == Reject) { 12393 if (it is a data digest error on immediate data) { 12394 Retransmit-Command-if-Possible(Connection, 12396 CurrentPDU.BadPDUHeader.CmdSN); 12397 } 12398 } else if (CurrentPDU.type == Response) { 12399 send-status-SNACK = Evaluate-a-StatSN(Connection, 12400 CurrentPDU); 12401 if (send-status-SNACK == TRUE) 12402 Recover-Status-if-Possible(Connection, CurrentPDU); 12403 } else { /* REST UNRELATED TO WITHIN-CONNECTION-RECOVERY, 12404 * NOT SHOWN */ 12405 } 12406 } 12408 Command-Acknowledge-Timeout-Handler(TCB) 12409 { 12410 Retrieve the Connection for TCB. 12411 Retransmit-Command-if-Possible(Connection, TCB.CmdSN); 12412 } 12414 Status-Expect-Timeout-Handler(Connection) 12415 { 12416 if (operational ErrorRecoveryLevel > 0) { 12417 Build-And-Send-Nop-Out(Connection); 12418 } else if (InitiatorProactiveSNACKEnabled){ 12419 if ((Connection.state == LOGGED_IN) and 12420 connection is not already considered 12421 failed) { 12422 Build-And-Send-SSnack(Connection); 12423 } 12424 } 12425 } 12427 D.3.3.Target Algorithms 12428 Handle-Status-SNACK-request(Connection, CurrentPDU) 12429 { 12430 if (operational ErrorRecoveryLevel > 0) { 12431 if (request for an acknowledged run) { 12432 Build-And-Send-Reject(Connection, CurrentPDU, 12433 Protocol-Error); 12434 } else if (request for an untransmitted run) { 12435 discard, return; 12436 } else { 12437 Retransmit-Status-Burst(CurrentPDU, TCB); 12438 } 12439 } else { 12440 Build-And-Send-Async(Connection, DroppedConnection, 12441 DefaultTime2Wait, 12442 DefaultTime2Retain); 12443 } 12444 } 12446 D.4. Connection Recovery Algorithms 12448 D.4.1. Procedure Descriptions 12450 Build-And-Send-Async(transport connection, reason code, 12451 minimum time, maximum time); 12452 Pick-A-Logged-In-Connection(session); 12453 Build-And-Send-Logout(transport connection, logout connection 12454 identifier, reason code); 12455 PerformImplicitLogout(transport connection, logout connection 12456 identifier, target information); 12458 PerformLogin(transport connection, target information); 12459 CreateNewTransportConnection(target information); 12460 Build-And-Send-Command(transport connection, task control 12461 block); 12462 Connection-Cleanup-Handler(transport connection); 12463 Connection-Resource-Timeout-Handler(transport connection); 12464 Quiesce-And-Prepare-for-New-Allegiance(session, task control 12465 block); 12466 Build-And-Send-Logout-Response(transport connection, 12467 CID of connection in recovery, reason 12468 code); 12469 Build-And-Send-TaskMgmt-Response(transport connection, 12470 task mgmt command PDU, response code); 12471 Establish-New-Allegiance(task control block, transport 12472 connection); 12473 Schedule-Command-To-Continue(task control block); 12475 Notes: 12476 - Transport exception conditions, such as unexpected 12477 connection termination, connection reset, and hung 12478 connection while the connection is in the full-feature 12479 phase, are all assumed to be asynchronously signaled to the 12480 iSCSI layer using the Transport_Exception_Handler procedure. 12482 D.4.2. Initiator Algorithms 12484 Receive-a-In-PDU(Connection, CurrentPDU) 12485 { 12486 check-basic-validity(CurrentPDU); 12487 if (Header-Digest-Bad) discard, return; 12488 Retrieve TCB from CurrentPDU.InitiatorTaskTag. 12489 if (CurrentPDU.type == Async) { 12490 if (CurrentPDU.AsyncEvent == ConnectionDropped) { 12491 Retrieve the AffectedConnection for 12492 CurrentPDU.Parameter1. 12493 AffectedConnection.CurrentTimeout = 12494 CurrentPDU.Parameter3; 12495 AffectedConnection.State = CLEANUP_WAIT; 12496 Start-Timer(Connection-Cleanup-Handler, 12497 AffectedConnection, 12498 CurrentPDU.Parameter2); 12499 } else if (CurrentPDU.AsyncEvent == LogoutRequest)) { 12500 AffectedConnection = Connection; 12501 AffectedConnection.State = LOGOUT_REQUESTED; 12502 AffectedConnection.PerformConnectionCleanup = TRUE; 12503 AffectedConnection.CurrentTimeout = 12504 CurrentPDU.Parameter3; 12505 Start-Timer(Connection-Cleanup-Handler, 12506 AffectedConnection, 0); 12507 } else if (CurrentPDU.AsyncEvent == SessionDropped)) { 12508 for (each Connection) { 12509 Connection.State = CLEANUP_WAIT; 12510 Connection.CurrentTimeout = CurrentPDU.Parameter3; 12511 Start-Timer(Connection-Cleanup-Handler, 12512 Connection, CurrentPDU.Parameter2); 12513 } 12514 Session.state = FAILED; 12515 } 12517 } else if (CurrentPDU.type == LogoutResponse) { 12518 Retrieve the CleanupConnection for CurrentPDU.CID. 12519 if (CurrentPDU.Response = failure) { 12520 CleanupConnection.State = CLEANUP_WAIT; 12521 } else { 12522 CleanupConnection.State = FREE; 12523 } 12524 } else if (CurrentPDU.type == LoginResponse) { 12525 if (this is a response to an implicit Logout) { 12526 Retrieve the CleanupConnection. 12527 if (successful) { 12528 CleanupConnection.State = FREE; 12529 Connection.State = LOGGED_IN; 12530 } else { 12531 CleanupConnection.State = CLEANUP_WAIT; 12532 DestroyTransportConnection(Connection); 12533 } 12534 } 12535 } else { /* REST UNRELATED TO CONNECTION-RECOVERY, 12536 * NOT SHOWN */ 12538 } 12539 if (CleanupConnection.State == FREE) { 12540 for (each command that was active on CleanupConnection) { 12541 /* Establish new connection allegiance */ 12542 NewConnection = Pick-A-Logged-In- 12543 Connection(Session); 12544 Build-And-Send-Command(NewConnection, TCB); 12545 } 12546 } 12547 } 12549 Connection-Cleanup-Handler(Connection) 12550 { 12551 Retrieve Session from Connection. 12552 if (Connection can still exchange iSCSI PDUs) { 12553 NewConnection = Connection; 12554 } else { 12555 Start-Timer(Connection-Resource-Timeout-Handler, 12556 Connection, Connection.CurrentTimeout); 12557 if (there are other logged-in connections) { 12558 NewConnection = Pick-A-Logged-In- 12559 Connection(Session); 12560 } else { 12561 NewConnection = 12563 CreateTransportConnection(Session.OtherEndInfo); 12564 Initiate an implicit Logout on NewConnection for 12565 Connection.CID. 12566 return; 12567 } 12568 } 12569 Build-And-Send-Logout(NewConnection, Connection.CID, 12570 RecoveryRemove); 12571 } 12573 Transport_Exception_Handler(Connection) 12574 { 12575 Connection.PerformConnectionCleanup = TRUE; 12576 if (the event is an unexpected transport disconnect) { 12577 Connection.State = CLEANUP_WAIT; 12578 Connection.CurrentTimeout = DefaultTime2Retain; 12579 Start-Timer(Connection-Cleanup-Handler, Connection, 12580 DefaultTime2Wait); 12582 } else { 12583 Connection.State = FREE; 12584 } 12585 } 12587 D.4.3. Target Algorithms 12589 Receive-a-In-PDU(Connection, CurrentPDU) 12590 { 12591 check-basic-validity(CurrentPDU); 12592 if (Header-Digest-Bad) discard, return; 12593 else if (Data-Digest-Bad) { 12594 Build-And-Send-Reject(Connection, CurrentPDU, 12595 Payload-Digest-Error); 12596 discard, return; 12597 } 12598 Retrieve TCB and Session. 12599 if (CurrentPDU.type == Logout) { 12600 if (CurrentPDU.ReasonCode = RecoveryRemove) { 12601 Retrieve the CleanupConnection from CurrentPDU.CID). 12602 for (each command active on CleanupConnection) { 12603 Quiesce-And-Prepare-for-New-Allegiance(Session, 12604 TCB); 12605 TCB.CurrentlyAllegiant = FALSE; 12606 } 12607 Cleanup-Connection-State(CleanupConnection); 12608 if ((quiescing successful) and (cleanup successful)) 12609 { 12610 Build-And-Send-Logout-Response(Connection, 12611 CleanupConnection.CID, 12612 Success); 12613 } else { 12614 Build-And-Send-Logout-Response(Connection, 12615 CleanupConnection.CID, 12616 Failure); 12617 } 12619 } 12620 } else if ((CurrentPDU.type == Login) and 12621 operational ErrorRecoveryLevel == 2) { 12622 Retrieve the CleanupConnection from CurrentPDU.CID). 12623 for (each command active on CleanupConnection) { 12624 Quiesce-And-Prepare-for-New-Allegiance(Session, 12625 TCB); 12626 TCB.CurrentlyAllegiant = FALSE; 12627 } 12628 Cleanup-Connection-State(CleanupConnection); 12629 if ((quiescing successful) and (cleanup successful)) 12630 { 12631 Continue with the rest of the Login processing; 12632 } else { 12633 Build-And-Send-Login-Response(Connection, 12634 CleanupConnection.CID, Target 12635 Error); 12636 } 12637 } 12638 } else if (CurrentPDU.type == TaskManagement) { 12639 if (CurrentPDU.function == "TaskReassign") { 12640 if (Session.ErrorRecoveryLevel < 2) { 12641 Build-And-Send-TaskMgmt-Response(Connection, 12642 CurrentPDU, "Allegiance reassignment 12643 not supported"); 12644 } else if (task is not found) { 12645 Build-And-Send-TaskMgmt-Response(Connection, 12646 CurrentPDU, "Task not in task set"); 12647 } else if (task is currently allegiant) { 12648 Build-And-Send-TaskMgmt-Response(Connection, 12649 CurrentPDU, "Task still allegiant"); 12650 } else { 12651 Establish-New-Allegiance(TCB, Connection); 12652 TCB.CurrentlyAllegiant = TRUE; 12653 Schedule-Command-To-Continue(TCB); 12654 } 12655 } 12656 } else { /* REST UNRELATED TO CONNECTION-RECOVERY, 12657 * NOT SHOWN */ 12658 } 12660 } 12662 Transport_Exception_Handler(Connection) 12663 { 12664 Connection.PerformConnectionCleanup = TRUE; 12665 if (the event is an unexpected transport disconnect) { 12666 Connection.State = CLEANUP_WAIT; 12667 Start-Timer(Connection-Resource-Timeout-Handler, 12668 Connection, 12670 (DefaultTime2Wait+DefaultTime2Retain)); 12671 if (this Session has full-feature phase connections 12672 left) { 12673 DifferentConnection = 12674 Pick-A-Logged-In-Connection(Session); 12675 Build-And-Send-Async(DifferentConnection, 12676 DroppedConnection, DefaultTime2Wait, 12677 DefaultTime2Retain); 12678 } 12679 } else { 12680 Connection.State = FREE; 12681 } 12682 } 12683 Appendix E. Clearing Effects of Various Events on Targets 12685 E.1. C 12686 learing Effects on iSCSI Objects 12688 The following tables describe the target behavior on receiving the 12689 events specified in the rows of the table. The second table is 12690 an extension of the first table and defines clearing actions for 12691 more objects on the same events. The legend is: 12693 Y = Yes (cleared/discarded/reset on the event specified in 12694 the row). Unless otherwise noted, the clearing action is 12695 only applicable for the issuing initiator port. 12697 N = No (not affected on the event specified in the row, 12698 i.e., stays at previous value). 12700 NA = Not Applicable or Not Defined. 12702 +-----+-----+-----+-----+-----+ 12703 |IT(1)|IC(2)|CT(5)|ST(6)|PP(7)| 12704 +---------------------+-----+-----+-----+-----+-----+ 12705 |connection failure(8)|Y |Y |N |N |Y | 12706 +---------------------+-----+-----+-----+-----+-----+ 12707 |connection state |NA |NA |Y |N |NA | 12708 |timeout (9) | | | | | | 12709 +---------------------+-----+-----+-----+-----+-----+ 12710 |session timeout/ |Y |Y |Y |Y |Y(14)| 12711 |closure/reinstatement| | | | | | 12712 |(10) | | | | | | 12713 +---------------------+-----+-----+-----+-----+-----+ 12714 |session continuation |NA |NA |N(11)|N |NA | 12715 |(12) | | | | | | 12716 +---------------------+-----+-----+-----+-----+-----+ 12717 |successful connection|Y |Y |Y |N |Y(13)| 12718 |close logout | | | | | | 12719 +---------------------+-----+-----+-----+-----+-----+ 12720 |session failure (18) |Y |Y |N |N |Y | 12721 +---------------------+-----+-----+-----+-----+-----+ 12722 |successful recovery |Y |Y |N |N |Y(13)| 12723 |Logout | | | | | | 12724 +---------------------+-----+-----+-----+-----+-----+ 12725 |failed Logout |Y |Y |N |N |Y | 12726 +---------------------+-----+-----+-----+-----+-----+ 12727 |connection Login |NA |NA |NA |Y(15)|NA | 12728 |(leading) | | | | | | 12729 +---------------------+-----+-----+-----+-----+-----+ 12730 |connection Login |NA |NA |N(11)|N |Y | 12731 |(non-leading) | | | | | | 12732 +---------------------+-----+-----+-----+-----+-----+ 12733 |target cold reset(16)|Y(20)|Y |Y |Y |Y | 12734 +---------------------+-----+-----+-----+-----+-----+ 12735 |target warm reset(16)|Y(20)|Y |Y |Y |Y | 12736 +---------------------+-----+-----+-----+-----+-----+ 12737 |LU reset(19) |Y(20)|Y |Y |Y |Y | 12738 +---------------------+-----+-----+-----+-----+-----+ 12739 |powercycle(16) |Y |Y |Y |Y |Y | 12740 +---------------------+-----+-----+-----+-----+-----+ 12742 1. Incomplete TTTs - Target Transfer Tags on which the target is 12743 still expecting PDUs to be received. Examples include TTTs 12744 received via R2T, NOP-IN, etc. 12746 2. Immediate Commands - immediate commands, but waiting for 12747 execution on a target. For example, Abort Task Set. 12749 5. Connection Tasks - tasks that are active on the iSCSI connection 12750 in question. 12752 6. Session Tasks - tasks that are active on the entire iSCSI 12753 session. A union of "connection tasks" on all participating 12754 connections. 12756 7. Partial PDUs (if any) - PDUs that are partially sent and waiting 12757 for transport window credit to complete the transmission. 12759 8. Connection failure is a connection exception condition - one of 12760 the transport connections shutdown, transport connections 12761 reset, or transport connections timed out, which abruptly 12762 terminated the iSCSI full-feature phase connection. A 12763 connection failure always takes the connection state machine to 12764 the CLEANUP_WAIT state. 12766 9. Connection state timeout happens if a connection spends more 12767 time than agreed upon during Login negotiation in the 12768 CLEANUP_WAIT state, and this takes the connection to the FREE 12769 state (M1 transition in connection cleanup state diagram). 12771 10.These are defined in Section 6.3.5. 12773 11.This clearing effect is "Y" only if it is a connection 12774 reinstatement and the operational ErrorRecoveryLevel is less 12775 than 2. 12777 12.Session continuation is defined in Section 6.3.5. 12779 13.This clearing effect is only valid if the connection is being 12780 logged out on a different connection and when the connection 12781 being logged out on the target may have some partial PDUs 12782 pending to be sent. In all other cases, the effect is "NA". 12784 14.This clearing effect is only valid for a "close the session" 12785 logout in a multi-connection session. In all other cases, the 12786 effect is "NA". 12787 15.Only applicable if this leading connection login is a session 12788 reinstatement. If this is not the case, it is "NA". 12789 16.This operation affects all logged-in initiators. 12790 18.Session failure is defined in Section 6.3.5. 12791 19.This operation affects all logged-in initiators and the clearing 12792 effects are only applicable to the LU being reset. 12793 20.With Standard multi-task abort semantics (Section 4.2.3.3), a 12794 target warm reset or a target cold reset or an LU reset would 12795 clear the active TTTs upon completion. However, the FastAbort 12796 multi-task abort semantics defined by Section 4.2.3.4 do not 12797 guarantee that the active TTTs are cleared by the end of the 12798 reset operations. In fact, the FastAbort semantics are designed 12799 to allow clearing the TTTs in a "lazy" fashion after the TMF 12800 Response is delivered. Thus, when TaskReporting=FastAbort 12801 (Section 13.23) is operational on a session, the clearing 12802 effects of reset operations on "Incomplete TTTs" is "N". 12804 +-----+-----+-----+-----+-----+ 12805 |DC(1)|DD(2)|SS(3)|CS(4)|DS(5)| 12806 +---------------------+-----+-----+-----+-----+-----+ 12807 |connection failure |N |Y |N |N |N | 12808 +---------------------+-----+-----+-----+-----+-----+ 12809 |connection state |Y |NA |Y |N |NA | 12810 |timeout | | | | | | 12811 +---------------------+-----+-----+-----+-----+-----+ 12812 |session timeout/ |Y |Y |Y(7) |Y |NA | 12813 |closure/reinstatement| | | | | | 12814 +---------------------+-----+-----+-----+-----+-----+ 12815 |session continuation |N(11)|NA*12|NA |N |NA*13| 12816 +---------------------+-----+-----+-----+-----+-----+ 12817 |successful connection|Y |Y |Y |N |NA | 12818 |close Logout | | | | | | 12819 +---------------------+-----+-----+-----+-----+-----+ 12820 |session failure |N |Y |N |N |N | 12821 +---------------------+-----+-----+-----+-----+-----+ 12822 |successful recovery |Y |Y |Y |N |N | 12823 |Logout | | | | | | 12824 +---------------------+-----+-----+-----+-----+-----+ 12825 |failed Logout |N |Y(9) |N |N |N | 12826 +---------------------+-----+-----+-----+-----+-----+ 12827 |connection Login |NA |NA |N(8) |N(8) |NA | 12828 |(leading | | | | | | 12829 +---------------------+-----+-----+-----+-----+-----+ 12830 |connection Login |N(11)|NA*12|N(8) |N |NA*13| 12831 |(non-leading) | | | | | | 12832 +---------------------+-----+-----+-----+-----+-----+ 12833 |target cold reset |Y |Y |Y |Y(10)|NA | 12834 +---------------------+-----+-----+-----+-----+-----+ 12835 |target warm reset |Y |Y |N |N |NA | 12836 +---------------------+-----+-----+-----+-----+-----+ 12837 |LU reset |N |Y |N |N |N | 12838 +---------------------+-----+-----+-----+-----+-----+ 12839 |powercycle |Y |Y |Y |Y(10)|NA | 12840 +---------------------+-----+-----+-----+-----+-----+ 12842 1. Discontiguous Commands - commands allegiant to the connection 12843 in question and waiting to be reordered in the iSCSI layer. All 12844 "Y"s in this column assume that the task causing the event (if 12845 indeed the event is the result of a task) is issued as an 12846 immediate command, because the discontiguities can be ahead of the 12847 task. 12849 2. Discontiguous Data - data PDUs received for the task in 12850 question and waiting to be reordered due to prior discontiguities 12851 in DataSN. 12853 3. StatSN 12855 4. CmdSN 12857 5. DataSN 12859 7. It clears the StatSN on all the connections. 12861 8. This sequence number is instantiated on this event. 12863 9. A logout failure drives the connection state machine to the 12864 CLEANUP_WAIT state, similar to the connection failure event. 12865 Hence, it has a similar effect on this and several other protocol 12866 aspects. 12868 10. This is cleared by virtue of the fact that all sessions with 12869 all initiators are terminated. 12871 11. This clearing effect is "Y" if it is a connection 12872 reinstatement. 12874 12. This clearing effect is "Y" only if it is a connection 12875 reinstatement and the operational ErrorRecoveryLevel is 2. 12877 13. This clearing effect is "N" only if it is a connection 12878 reinstatement and the operational ErrorRecoveryLevel is 2. 12880 E.2. C 12881 learing Effects on SCSI Objects 12883 The only iSCSI protocol action that can effect clearing actions on 12884 SCSI objects is the "I_T nexus loss" notification (Section 6.3.5.1 12885 Loss of Nexus notification). [SPC3] describes the clearing effects 12886 of this notification on a variety of SCSI attributes. In addition, 12887 SCSI standards documents (such as [SAM2] and [SBC2]) define 12888 additional clearing actions that may take place for several SCSI 12889 objects on SCSI events such as LU resets and power-on resets. 12891 Since iSCSI defines a target cold reset as a protocol-equivalent 12892 to a target power-cycle, the iSCSI target cold reset must also be 12893 considered as the power-on reset event in interpreting the actions 12894 defined in the SCSI standards. 12896 When the iSCSI session is reconstructed (between the same SCSI 12897 ports with the same nexus identifier) reestablishing the same I_T 12898 nexus, all SCSI objects that are defined to not clear on the "I_T 12899 nexus loss" notification event, such as persistent reservations, 12900 are automatically associated to this new session. 12902 Acknowledgments 12904 Several individuals on the original IPS Working Group made 12905 significant contributions to the original RFCs 3720, 3980, 4850 12906 and 5048. 12908 Specifically, the authors of the original RFCs - which this draft 12909 consolidates into a single document - were the following: 12911 RFC 3720: Julian Satran, Kalman Meth, Costa Sapuntzakis, 12912 Mallikarjun Chadalapaka, Efri Zeidner 12914 RFC 3980: Marjorie Krueger, Mallikarjun Chadalapaka, Rob Elliott 12916 RFC 4850: David Wysochanski 12918 RFC 5048: Mallikarjun Chadalapaka 12920 Many thanks to Fred Knight for contributing to the UML notations 12921 and drawings in this draft. 12923 We would in addition like to acknowledge the following individuals 12924 who contributed to this revised draft: David Harrington, Paul 12925 Koning, Mark Edwards, Rob Elliott, Martin Stiemerling. Finally, 12926 this draft also benefited from significant review contributions 12927 from the Storm Working Group at large. 12929 Authors' Addresses 12931 Mallikarjun Chadalapaka 12932 Microsoft 12933 One Microsoft Way 12934 Redmond WA 98052 USA 12935 E-mail: cbm@chadalapaka.com 12937 Julian Satran 12938 Infinidat Ltd. 12939 E-mail: julians@infinidat.com, julian@satran.net 12941 Kalman Meth 12942 IBM Haifa Research Lab 12943 Haifa University Campus - Mount Carmel 12944 Haifa 31905, Israel 12945 Phone +972.4.829.6341 12946 E-mail: meth@il.ibm.com 12948 David L. Black, 12949 EMC Corporation, 12950 176 South St., Hopkinton, MA 01748 12951 Phone +1 (508) 293-7953 12952 Email: david.black@emc.com 12954 Comments may be sent to Mallikarjun Chadalapaka 12956 Acknowledgement 12958 Funding for the RFC Editor function is currently provided by the 12959 Internet Society