idnits 2.17.1 draft-ietf-storm-iscsi-cons-10.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 RFC3980, 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 2910 -- Looks like a reference, but probably isn't: '0' on line 6869 -- Looks like a reference, but probably isn't: '7' on line 6869 == Missing Reference: 'MaxMissingDPDU' is mentioned on line 12086, but not defined == Missing Reference: 'MaxOutStandingR2T' is mentioned on line 12094, but not defined == Missing Reference: 'MaxMissingSPDU' is mentioned on line 12107, but not defined == Missing Reference: 'MaxSupportedConns' is mentioned on line 12117, but not defined -- Possible downref: Non-RFC (?) normative reference: ref. 'EUI' -- Possible downref: Non-RFC (?) normative reference: ref. 'FC-FS3' == Outdated reference: A later version (-04) exists of draft-ietf-storm-ipsec-ips-update-03 -- 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-10.txt 4 Intended status: Proposed Standard Julian Satran 5 Expires: January 2014 Infinidat Ltd. 6 Obsoletes: RFC3720, RFC3980, RFC4850, RFC5048 7 Updates: RFC3721 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 January 31, 2014. 38 Copyright Notice 40 Copyright (c) 2013 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with 48 respect to this document. Code Components extracted from this 49 document must include Simplified BSD License text as described in 50 Section 4.e of the Trust Legal Provisions and are provided without 51 warranty as described in the Simplified BSD License. 53 Abstract 55 This document describes a transport protocol for SCSI that works 56 on top of TCP. The iSCSI protocol aims to be fully compliant with 57 the standardized SCSI Architecture Model (SAM-2). RFC 3720 58 defined the original iSCSI protocol. RFC 3721 discusses iSCSI 59 Naming examples and discovery techniques. Subsequently, RFC 3980 60 added an additional naming format to iSCSI protocol. RFC 4850 61 followed up by adding a new public extension key to iSCSI. RFC 62 5048 offered a number of clarifications and a few improvements and 63 corrections to the original iSCSI protocol. 65 This document obsoletes RFCs 3720, 3980, 4850 and 5048 by 66 consolidating them into a single document and making additional 67 updates to the consolidated specification. This document also 68 updates RFC 3721. The text in this document thus supersedes the 69 text in all the noted RFCs wherever there is a difference in 70 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 ........................................ 24 78 2.4. Conventions ............................................... 25 79 3. UML Conventions................................................. 26 80 3.1. UML Conventions Overview .................................. 26 81 3.2. Multiplicity Notion ....................................... 26 82 3.3. Class Diagram Conventions ................................. 27 83 3.4. Class Diagram Notation for Associations ................... 28 84 3.5. Class Diagram Notation for Aggregations ................... 29 85 3.6. Class Diagram Notation for Generalizations ................ 29 86 4. Overview........................................................ 31 87 4.1. SCSI Concepts ............................................... 31 88 4.2. iSCSI Concepts and Functional Overview ...................... 32 89 4.2.1. Layers and Sessions ..................................... 33 90 4.2.2. Ordering and iSCSI Numbering ............................ 34 91 4.2.2.1. Command Numbering and Acknowledging ................. 34 92 4.2.2.2. Response/Status Numbering and Acknowledging ......... 38 93 4.2.2.3. Response Ordering ................................... 39 94 4.2.2.3.1. Need for Response Ordering ...................... 39 95 4.2.2.3.2. Response Ordering Model Description ............. 39 96 4.2.2.3.3. iSCSI Semantics with the Interface Model ........ 40 97 4.2.2.3.4. Current List of Fenced Response Use Cases ....... 41 98 4.2.2.4. Data Sequencing ..................................... 42 99 4.2.3. iSCSI Task Management ................................... 43 100 4.2.3.1. Task Management Overview ............................ 43 101 4.2.3.2. Notion of Affected Tasks ............................ 43 102 4.2.3.3. Standard Multi-task Abort Semantics ................. 44 103 4.2.3.4. FastAbort Multi-task Abort Semantics ................ 45 104 4.2.3.5. Affected Tasks Shared across Standard and FastAbort 105 Sessions ..................................................... 47 106 4.2.3.6. Rationale behind the FastAbort Semantics ............48 107 4.2.4. iSCSI Login .............................................50 108 4.2.5. iSCSI Full Feature Phase ................................51 109 4.2.5.1. Command Connection Allegiance .......................52 110 4.2.5.2. Data Transfer Overview ..............................53 111 4.2.5.3. Tags and Integrity Checks ...........................54 112 4.2.5.4. Task Management .....................................55 113 4.2.6. iSCSI Connection Termination ............................55 114 4.2.7. iSCSI Names .............................................56 115 4.2.7.1. iSCSI Name Properties ...............................57 116 4.2.7.2. iSCSI Name Encoding .................................59 117 4.2.7.3. iSCSI Name Structure ................................60 118 4.2.7.4. Type "iqn." (iSCSI Qualified Name) ..................61 119 4.2.7.5. Type "eui." (IEEE EUI-64 format) ....................63 120 4.2.7.6. Type "naa." - Network Address Authority .............63 121 4.2.8. Persistent State ........................................64 122 4.2.9. Message Synchronization and Steering ....................65 123 4.2.9.1. Sync/Steering and iSCSI PDU Length ..................66 124 4.3. iSCSI Session Types .........................................66 125 4.4. SCSI to iSCSI Concepts Mapping Model ........................67 126 4.4.1. iSCSI Architecture Model ................................68 127 4.4.2. SCSI Architecture Model .................................71 128 4.4.3. Consequences of the Model ...............................73 129 4.4.3.1. I_T Nexus State .....................................74 130 4.4.3.2. Reservations ........................................74 131 4.5. iSCSI UML Model .............................................75 132 4.6. Request/Response Summary ....................................78 133 4.6.1. Request/Response Types Carrying SCSI Payload ............78 134 4.6.1.1. SCSI-Command ........................................78 135 4.6.1.2. SCSI-Response .......................................79 136 4.6.1.3. Task Management Function Request ....................79 137 4.6.1.4. Task Management Function Response ...................80 138 4.6.1.5. SCSI Data-out and SCSI Data-in ......................80 139 4.6.1.6. Ready To Transfer (R2T) .............................81 140 4.6.2. Requests/Responses carrying SCSI and iSCSI Payload ......82 141 4.6.2.1. Asynchronous Message ................................82 143 4.6.3. Requests/Responses Carrying iSCSI Only Payload ..........82 144 4.6.3.1. Text Request and Text Response ......................82 145 4.6.3.2. Login Request and Login Response ....................83 146 4.6.3.3. Logout Request and Response .........................84 147 4.6.3.4. SNACK Request .......................................84 148 4.6.3.5. Reject ..............................................84 149 4.6.3.6. NOP-Out Request and NOP-In Response .................85 150 5. SCSI Mode Parameters for iSCSI................................. 86 152 6. Login and Full Feature Phase Negotiation....................... 87 153 6.1. Text Format ................................................ 88 154 6.2. Text Mode Negotiation ...................................... 92 155 6.2.1. List negotiations ...................................... 96 156 6.2.2. Simple-value Negotiations .............................. 97 157 6.3. Login Phase ................................................ 97 158 6.3.1. Login Phase Start ..................................... 101 159 6.3.2. iSCSI Security Negotiation ............................ 104 160 6.3.3. Operational Parameter Negotiation During the Login Phase105 161 6.3.4. Connection Reinstatement .............................. 106 162 6.3.5. Session Reinstatement, Closure, and Timeout ........... 106 163 6.3.5.1. Loss of Nexus Notification ........................ 107 164 6.3.6. Session Continuation and Failure ...................... 107 165 6.4. Operational Parameter Negotiation Outside the Login Phase . 108 166 7. iSCSI Error Handling and Recovery............................. 110 167 7.1. Overview .................................................. 110 168 7.1.1. Background ............................................ 110 169 7.1.2. Goals ................................................. 110 170 7.1.3. Protocol Features and State Expectations .............. 111 171 7.1.4. Recovery Classes ...................................... 112 172 7.1.4.1. Recovery Within-command ........................... 113 173 7.1.4.2. Recovery Within-connection ........................ 114 174 7.1.4.3. Connection Recovery ............................... 115 175 7.1.4.4. Session Recovery .................................. 116 176 7.1.5. Error Recovery Hierarchy .............................. 116 177 7.2. Retry and Reassign in Recovery ............................ 118 178 7.2.1. Usage of Retry ....................................... 118 179 7.2.2. Allegiance Reassignment .............................. 119 180 7.3. Usage Of Reject PDU in Recovery .......................... 120 181 7.4. Error Recovery Considerations for Discovery Sessions ..... 121 182 7.4.1. ErrorRecoveryLevel for Discovery Sessions ............ 121 183 7.4.2. Reinstatement Semantics for Discovery Sessions ....... 121 184 7.4.2.1. Unnamed Discovery Sessions ....................... 122 185 7.4.2.2. Named Discovery Session .......................... 123 186 7.4.3. Target PDUs During Discovery ......................... 123 187 7.5. Connection Timeout Management ............................ 123 188 7.5.1. Timeouts on Transport Exception Events ............... 124 189 7.5.2. Timeouts on Planned Decommissioning .................. 124 190 7.6. Implicit Termination of Tasks ............................ 124 191 7.7. Format Errors ............................................ 125 192 7.8. Digest Errors ............................................ 126 193 7.9. Sequence Errors .......................................... 128 194 7.10. Message Error Checking .................................. 128 195 7.11. SCSI Timeouts ........................................... 129 196 7.12. Negotiation Failures .................................... 130 197 7.13. Protocol Errors ......................................... 130 198 7.14. Connection Failures ..................................... 131 199 7.15. Session Errors .......................................... 132 200 8. State Transitions............................................. 133 201 8.1. Standard Connection State Diagrams ....................... 133 202 8.1.1. State Descriptions for Initiators and Targets ........ 133 203 8.1.2. State Transition Descriptions for Initiators and Targets134 204 8.1.3. Standard Connection State Diagram for an Initiator .....138 205 8.1.4. Standard Connection State Diagram for a Target .........140 206 8.2. Connection Cleanup State Diagram for Initiators and Targets 142 207 8.2.1. State Descriptions for Initiators and Targets ..........144 208 8.2.2. State Transition Descriptions for Initiators and Targets145 209 8.3. Session State Diagrams .....................................147 210 8.3.1. Session State Diagram for an Initiator .................147 211 8.3.2. Session State Diagram for a Target .....................148 212 8.3.3. State Descriptions for Initiators and Targets ..........149 213 8.3.4. State Transition Descriptions for Initiators and Targets 150 214 9. Security Considerations...................................... 152 215 9.1. iSCSI Security Mechanisms ............................... 152 216 9.2. In-band Initiator-Target Authentication ................. 153 217 9.2.1. CHAP Considerations ................................. 155 218 9.2.2. SRP Considerations .................................. 158 219 Kerberos Considerations ................................... 158 220 9.2.3. ..................................................... 158 221 9.3. IPsec ................................................... 159 222 9.3.1. Data Integrity and Authentication ................... 159 223 9.3.2. Confidentiality ..................................... 160 224 9.3.3. Policy, Security Associations, and Cryptographic Key 225 Management ................................................. 161 226 9.4. Security Considerations for the X#NodeArchitecture Key .. 163 227 9.5. SCSI Access Control Considerations ...................... 165 228 10. Notes to Implementers....................................... 166 229 10.1. Multiple Network Adapters ............................... 166 230 10.1.1. Conservative Reuse of ISIDs ......................... 166 231 10.1.2. iSCSI Name, ISID, and TPGT Use ...................... 167 232 10.2. Autosense and Auto Contingent Allegiance (ACA) .......... 169 233 10.3. iSCSI Timeouts .......................................... 169 234 10.4. Command Retry and Cleaning Old Command Instances ........ 170 235 10.5. Synch and Steering Layer and Performance ................ 171 236 10.6. Considerations for State-dependent Devices and Long-lasting 237 SCSI Operations ............................................... 171 238 10.6.1. Determining the Proper ErrorRecoveryLevel ........... 172 239 10.7. Multi-task Abort Implementation Considerations .......... 173 240 11. iSCSI PDU Formats........................................... 174 241 11.1. iSCSI PDU Length and Padding ........................... 174 242 11.2. PDU Template, Header, and Opcodes ...................... 174 243 11.2.1. Basic Header Segment (BHS) ......................... 175 244 11.2.1.1. I .............................................. 176 245 11.2.1.2. Opcode ......................................... 176 246 11.2.1.3. Final (F) bit .................................. 178 247 11.2.1.4. Opcode-specific Fields ......................... 178 248 11.2.1.5. TotalAHSLength ................................. 178 249 11.2.1.6. DataSegmentLength .............................. 178 250 11.2.1.7. LUN ............................................ 178 251 11.2.1.8. Initiator Task Tag ............................. 179 252 11.2.2. Additional Header Segment (AHS) ................... 179 253 11.2.2.1. AHSType ....................................... 179 254 11.2.2.2. AHSLength ..................................... 180 255 11.2.2.3. Extended CDB AHS .............................. 180 256 11.2.2.4. Bidirectional Expected Read-Data Length AHS ... 180 257 11.2.3. Header Digest and Data Digest ..................... 181 258 11.2.4. Data Segment ...................................... 181 259 11.3. SCSI Command .......................................... 181 260 11.3.1. Flags and Task Attributes (byte 1) ................ 182 261 11.3.2. CmdSN - Command Sequence Number ................... 183 262 11.3.3. ExpStatSN ......................................... 184 263 11.3.4. Expected Data Transfer Length ..................... 184 264 11.3.5. CDB - SCSI Command Descriptor Block ............... 185 265 11.3.6. Data Segment - Command Data ....................... 185 266 11.4. SCSI Response ......................................... 185 267 11.4.1. Flags (byte 1) .................................... 186 268 11.4.2. Status ............................................ 187 269 11.4.3. Response .......................................... 188 270 11.4.4. SNACK Tag ......................................... 189 271 11.4.5. Residual Count .................................... 189 272 11.4.5.1. Field Semantics ............................... 189 273 11.4.5.2. Residuals Concepts Overview ................... 190 274 11.4.5.3. SCSI REPORT LUNS and Residual Overflow ........ 190 275 11.4.6. Bidirectional Read Residual Count ................. 192 276 11.4.7. Data Segment - Sense and Response Data Segment .... 192 277 11.4.7.1. SenseLength ................................... 193 278 11.4.7.2. Sense Data .................................... 193 279 11.4.8. ExpDataSN ......................................... 194 280 11.4.9. StatSN - Status Sequence Number ................... 194 281 11.4.10. ExpCmdSN - Next Expected CmdSN from this Initiator 195 282 11.4.11. MaxCmdSN - Maximum CmdSN from this Initiator ...... 195 284 11.5. Task Management Function Request ....................... 196 285 11.5.1. Function ........................................... 196 286 11.5.2. TotalAHSLength and DataSegmentLength ............... 200 287 11.5.3. LUN ................................................ 200 288 11.5.4. Referenced Task Tag ................................ 200 289 11.5.5. RefCmdSN ........................................... 200 290 11.5.6. ExpDataSN .......................................... 201 291 11.6. Task Management Function Response ...................... 201 292 11.6.1. Response ........................................... 202 293 11.6.2. TotalAHSLength and DataSegmentLength ............... 204 294 11.7. SCSI Data-out & SCSI Data-in ........................... 204 295 11.7.1. F (Final) Bit ...................................... 207 296 11.7.2. A (Acknowledge) bit ................................ 207 297 11.7.3. Flags (byte 1) ..................................... 208 298 11.7.4. Target Transfer Tag and LUN ........................ 209 299 11.7.5. DataSN ............................................. 209 300 11.7.6. Buffer Offset ...................................... 209 301 11.7.7. DataSegmentLength .................................. 210 302 11.8. Ready To Transfer (R2T) ................................ 211 303 11.8.1. TotalAHSLength and DataSegmentLength ............... 213 304 11.8.2. R2TSN .............................................. 213 305 11.8.3. StatSN ............................................. 213 306 11.8.4. Desired Data Transfer Length and Buffer Offset ..... 213 307 11.8.5. Target Transfer Tag ................................ 213 308 11.9. Asynchronous Message ................................... 214 309 11.9.1. AsyncEvent ......................................... 215 310 11.9.2. AsyncVCode ......................................... 218 311 11.9.3. LUN ................................................ 218 312 11.9.4. Sense Data and iSCSI Event Data .................... 218 313 11.9.4.1. SenseLength .................................... 219 314 11.10. Text Request .......................................... 219 315 11.10.1. F (Final) Bit ..................................... 221 316 11.10.2. C (Continue) Bit .................................. 221 317 11.10.3. Initiator Task Tag ................................ 221 318 11.10.4. Target Transfer Tag ............................... 221 319 11.10.5. Text .............................................. 222 321 11.11. Text Response ....................................... 223 322 11.11.1. F (Final) Bit ................................... 224 323 11.11.2. C (Continue) Bit ................................ 225 324 11.11.3. Initiator Task Tag .............................. 225 325 11.11.4. Target Transfer Tag ............................. 225 326 11.11.5. StatSN .......................................... 226 327 11.11.6. Text Response Data .............................. 226 328 11.12. Login Request ....................................... 226 329 11.12.1. T (Transit) Bit ................................. 227 330 11.12.2. C (Continue) Bit ................................ 228 331 11.12.3. CSG and NSG ..................................... 228 332 11.12.4. Version ......................................... 228 333 11.12.4.1. Version-max .................................. 228 334 11.12.4.2. Version-min .................................. 229 335 11.12.5. ISID ............................................ 229 336 11.12.6. TSIH ............................................ 231 337 11.12.7. Connection ID - CID ............................. 231 338 11.12.8. CmdSN ........................................... 231 339 11.12.9. ExpStatSN ....................................... 232 340 11.12.10. Login Parameters ............................... 232 341 11.13. Login Response ...................................... 232 342 11.13.1. Version-max ..................................... 233 343 11.13.2. Version-active .................................. 234 344 11.13.3. TSIH ............................................ 234 345 11.13.4. StatSN .......................................... 234 346 11.13.5. Status-Class and Status-Detail .................. 234 347 11.13.6. T (Transit) bit ................................. 238 348 11.13.7. C (Continue) Bit ................................ 239 349 11.13.8. Login Parameters ................................ 239 350 11.14. Logout Request ...................................... 239 351 11.14.1. Reason Code ..................................... 242 352 11.14.2. TotalAHSLength and DataSegmentLength ............ 243 353 11.14.3. CID ............................................. 243 354 11.14.4. ExpStatSN ....................................... 243 355 11.14.5. Implicit termination of tasks ................... 243 356 11.15. Logout Response ..................................... 244 357 11.15.1. Response ........................................ 245 358 11.15.2. TotalAHSLength and DataSegmentLength ............ 246 359 11.15.3. Time2Wait ....................................... 246 360 11.15.4. Time2Retain ..................................... 246 361 11.16. SNACK Request ....................................... 247 362 11.16.1. Type ............................................ 248 363 11.16.2. Data Acknowledgement ............................ 249 364 11.16.3. Resegmentation .................................. 249 365 11.16.4. Initiator Task Tag .............................. 250 366 11.16.5. Target Transfer Tag or SNACK Tag ................ 250 367 11.16.6. BegRun .......................................... 251 368 11.16.7. RunLength ....................................... 251 369 11.17. Reject .............................................. 252 370 11.17.1. Reason .......................................... 253 371 11.17.2. DataSN/R2TSN .................................... 254 372 11.17.3. StatSN, ExpCmdSN and MaxCmdSN ................... 254 373 11.17.4. Complete Header of Bad PDU ...................... 255 374 11.18. NOP-Out ............................................. 255 375 11.18.1. Initiator Task Tag .............................. 256 376 11.18.2. Target Transfer Tag ............................. 256 377 11.18.3. Ping Data ....................................... 257 378 11.19. NOP-In .............................................. 258 379 11.19.1. Target Transfer Tag ............................. 259 380 11.19.2. StatSN .......................................... 259 381 11.19.3. LUN ............................................. 259 382 12. iSCSI Security Text Keys and Authentication Methods......... 260 383 12.1. AuthMethod ........................................... 260 384 12.1.1. Kerberos ......................................... 262 385 12.1.2. Secure Remote Password (SRP) ..................... 263 386 12.1.3. Challenge Handshake Authentication Protocol (CHAP) 265 387 13. Login/Text Operational Text Keys............................ 267 388 13.1. HeaderDigest and DataDigest .......................... 267 389 13.2. MaxConnections ....................................... 270 390 13.3. SendTargets .......................................... 270 391 13.4. TargetName ........................................... 270 392 13.5. InitiatorName ......................................... 271 393 13.6. TargetAlias ........................................... 272 394 13.7. InitiatorAlias ........................................ 272 395 13.8. TargetAddress ......................................... 273 396 13.9. TargetPortalGroupTag .................................. 274 397 13.10. InitialR2T ........................................... 274 398 13.11. ImmediateData ........................................ 275 399 13.12. MaxRecvDataSegmentLength ............................. 276 400 13.13. MaxBurstLength ....................................... 277 401 13.14. FirstBurstLength ..................................... 277 402 13.15. DefaultTime2Wait ..................................... 278 403 13.16. DefaultTime2Retain ................................... 278 404 13.17. MaxOutstandingR2T .................................... 279 405 13.18. DataPDUInOrder ....................................... 279 406 13.19. DataSequenceInOrder .................................. 280 407 13.20. ErrorRecoveryLevel ................................... 280 408 13.21. SessionType .......................................... 281 409 13.22. The Private Extension Key Format ..................... 282 410 13.23. TaskReporting ........................................ 282 411 13.24. iSCSIProtocolLevel Negotiation ....................... 283 412 13.25. Obsoleted Keys ....................................... 283 413 13.26. X#NodeArchitecture ................................... 284 414 13.26.1. Definition ....................................... 284 415 13.26.2. Implementation Requirements ...................... 285 416 14. Rationale for revised IANA Considerations................... 286 418 15. IANA Considerations......................................... 288 420 Appendix A. Examples ........................................... 295 421 Read Operation Example ...................................... 295 422 Write Operation Example ..................................... 296 423 R2TSN/DataSN Use Examples ................................... 296 424 CRC Examples ................................................ 300 425 Appendix B. Login Phase Examples ............................... 302 427 Appendix C. SendTargets Operation .............................. 312 428 Appendix D. Algorithmic Presentation of Error Recovery Classes . 317 429 D.2.1. Procedure Descriptions ............................... 319 430 Appendix E. Clearing Effects of Various Events on Targets ...... 336 431 1. Introduction 433 The Small Computer Systems Interface (SCSI) is a popular family of 434 protocols for communicating with I/O devices, especially storage 435 devices. SCSI is a client-server architecture. Clients of a SCSI 436 interface are called "initiators". Initiators issue SCSI 437 "commands" to request services from components, logical units of a 438 server known as a "target". A "SCSI transport" maps the client- 439 server SCSI protocol to a specific interconnect. An Initiator is 440 one endpoint of a SCSI transport and a target is the other 441 endpoint. 443 The SCSI protocol has been mapped over various transports, 444 including Parallel SCSI, IPI, IEEE-1394 (firewire) and Fibre 445 Channel. These transports are I/O specific and have limited 446 distance capabilities. 448 The iSCSI protocol defined in this document describes a means of 449 transporting of the SCSI packets over TCP/IP, providing for an 450 interoperable solution which can take advantage of existing 451 Internet infrastructure, Internet management facilities and 452 address distance limitations. 454 2. Acronyms, Definitions and Document Summary 456 2.1. Acronyms 458 Acronym Definition 459 -------------------------------------------------------------- 460 3DES Triple Data Encryption Standard 461 ACA Auto Contingent Allegiance 462 AEN Asynchronous Event Notification 463 AES Advanced Encryption Standard 464 AH Additional Header (not the IPsec AH!) 465 AHS Additional Header Segment 466 API Application Programming Interface 467 ASC Additional Sense Code 468 ASCII American Standard Code for Information Interchange 469 ASCQ Additional Sense Code Qualifier 470 BHS Basic Header Segment 471 CBC Cipher Block Chaining 472 CD Compact Disk 473 CDB Command Descriptor Block 474 CHAP Challenge Handshake Authentication Protocol 475 CID Connection ID 476 CO Connection Only 477 CRC Cyclic Redundancy Check 478 CRL Certificate Revocation List 479 CSG Current Stage 480 CSM Connection State Machine 481 DES Data Encryption Standard 482 DNS Domain Name Server 483 DOI Domain of Interpretation 484 DVD Digital Versatile Disk 485 EDTL Expected Data Transfer Length 486 ESP Encapsulating Security Payload 487 EUI Extended Unique Identifier 488 FFP Full Feature Phase 489 FFPO Full Feature Phase Only 490 Gbps Gigabits per Second 491 HBA Host Bus Adapter 492 HMAC Hashed Message Authentication Code 493 I_T Initiator_Target 495 I_T_L Initiator_Target_LUN 496 IANA Internet Assigned Numbers Authority 497 IB InfiniBand 498 ID Identifier 499 IDN Internationalized Domain Name 500 IEEE Institute of Electrical & Electronics Engineers 501 IETF Internet Engineering Task Force 502 IKE Internet Key Exchange 503 I/O Input-Output 504 IO Initialize Only 505 IP Internet Protocol 506 IPsec Internet Protocol Security 507 IPv4 Internet Protocol Version 4 508 IPv6 Internet Protocol Version 6 509 IQN iSCSI Qualified Name 510 iSCSI Internet SCSI 511 iSER iSCSI Extensions for RDMA 512 ISID Initiator Session ID 513 iSNS Internet Storage Name Service (see [RFC4171]) 514 ITN iSCSI Target Name 515 ITT Initiator Task Tag 516 KRB5 Kerberos V5 517 LFL Lower Functional Layer 518 LTDS Logical-Text-Data-Segment 519 LO Leading Only 520 LU Logical Unit 521 LUN Logical Unit Number 522 MAC Message Authentication Codes 523 NA Not Applicable 524 NAA Network Address Authority 525 NIC Network Interface Card 526 NOP No Operation 527 NSG Next Stage 528 OS Operating System 529 PDU Protocol Data Unit 530 PKI Public Key Infrastructure 531 R2T Ready To Transfer 532 R2TSN Ready To Transfer Sequence Number 533 RDMA Remote Direct Memory Access 534 RFC Request For Comments 535 SAM SCSI Architecture Model 536 SAM2 SCSI Architecture Model - 2 537 SAN Storage Area Network 538 SAS Serial Attached SCSI 539 SCSI Small Computer Systems Interface 540 SLP Service Location Protocol 541 SN Sequence Number 542 SNACK Selective Negative Acknowledgment - also 543 Sequence Number Acknowledgement for data 544 SPDTL SCSI-Presented Data Transfer Length 545 SPKM Simple Public-Key Mechanism 546 SRP Secure Remote Password 547 SSID Session ID 548 SW Session-Wide 549 TCB Task Control Block 550 TCP Transmission Control Protocol 551 TMF Task Management Function 552 TPGT Target Portal Group Tag 553 TSIH Target Session Identifying Handle 554 TTT Target Transfer Tag 555 UA Unit Attention 556 UFL Upper Functional Layer 557 ULP Upper Level Protocol 558 URN Uniform Resource Names 559 UTF Universal Transformation Format 560 WG Working Group 562 2.2. Definitions 564 - Alias: An alias string can also be associated with an iSCSI 565 Node. The alias allows an organization to associate a user- 566 friendly string with the iSCSI Name. However, the alias string is 567 not a substitute for the iSCSI Name. 569 - CID (Connection ID): Connections within a session are identified 570 by a connection ID. It is a unique ID for this connection within 571 the session for the initiator. It is generated by the initiator 572 and presented to the target during login requests and during 573 logouts that close connections. 575 - Connection: A connection is a TCP connection. Communication 576 between the initiator and target occurs over one or more TCP 578 connections. The TCP connections carry control messages, SCSI 579 commands, parameters, and data within iSCSI Protocol Data Units 580 (iSCSI PDUs). 582 - I/O Buffer:A buffer that is used in a SCSI Read or Write 583 operation so SCSI data may be sent from or received into that 584 buffer. For a read or write data transfer to take place for a 585 task, an I/O Buffer is required on the initiator and at least one 586 is required on the 587 target. 589 - INCITS: INCITS stands for InterNational Committee of Information 590 Technology Standards. The INCITS has a broad standardization scope 591 within the field of Information and Communications Technologies 592 (ICT), encompassing storage, processing, transfer, display, 593 management, organization, and retrieval of information. INCITS 594 serves as ANSI's Technical Advisory Group for the ISO/IEC Joint 595 Technical Committee 1 (JTC 1). See http://www.incits.org. 597 - InfiniBand: An I/O architecture originally intended to replace 598 PCI and to address high performance server interconnectivity [IB]. 600 - iSCSI Device: A SCSI Device using an iSCSI service delivery 601 subsystem. Service Delivery Subsystem is defined by [SAM2] as a 602 transport mechanism for SCSI commands and responses. 604 - iSCSI Initiator Name: The iSCSI Initiator Name specifies the 605 worldwide unique name of the initiator. 607 - iSCSI Initiator Node: The "initiator" device. The word 608 "initiator" has been appropriately qualified as either a port or a 609 device in the rest of the document when the context is ambiguous. 610 All unqualified usages of "initiator" refer to an initiator port 611 (or device) depending on the context. 613 - iSCSI Layer: This layer builds/receives iSCSI PDUs and 614 relays/receives them to/from one or more TCP connections that form 615 an initiator-target "session". 617 - iSCSI Name: The name of an iSCSI initiator or iSCSI target. 619 - iSCSI Node: The iSCSI Node represents a single iSCSI initiator 620 or iSCSI target or a single instance of each. There are one or 621 more iSCSI Nodes within a Network Entity. The iSCSI Node is 622 accessible via one or more Network Portals. An iSCSI Node is 623 identified by its iSCSI Name. The separation of the iSCSI Name 624 from the addresses used by and for the iSCSI Node allows multiple 625 iSCSI nodes to use the same address, and the same iSCSI node to 626 use multiple addresses. 628 - iSCSI Target Name: The iSCSI Target Name specifies the worldwide 629 unique name of the target. 631 - iSCSI Target Node: The "target" device. The word "target" has 632 been appropriately qualified as either a port or a device in the 633 rest of the document when the context is ambiguous. All 634 unqualified usages of "target" refer to a target port (or device) 635 depending on the context. 637 - iSCSI Task: An iSCSI task is an iSCSI request for which a 638 response is expected. 640 - iSCSI Transfer Direction: The iSCSI transfer direction is 641 defined with regard to the initiator. Outbound or outgoing 642 transfers are transfers from the initiator to the target, while 643 inbound or incoming transfers are from the target to the 644 initiator. 646 - ISID: The initiator part of the Session Identifier. It is 647 explicitly specified by the initiator during Login. 649 - I_T nexus: According to [SAM2], the I_T nexus is a relationship 650 between a SCSI Initiator Port and a SCSI Target Port. For iSCSI, 651 this relationship is a session, defined as a relationship between 652 an iSCSI Initiator's end of the session (SCSI Initiator Port) and 653 the iSCSI Target's Portal Group. The I_T nexus can be identified 654 by the conjunction of the SCSI port names; that is, the I_T nexus 655 identifier is the tuple (iSCSI Initiator Name + ',i,'+ ISID, iSCSI 656 Target Name + ',t,'+ Portal Group Tag). 658 - I_T_L nexus: An I_T_L nexus is a SCSI concept, and is defined as 659 the relationship between a SCSI Initiator Port, a SCSI Target 660 Port, and a Logical Unit (LU). 662 - NAA: Network Address Authority, a naming format defined by the 663 INCITS T11 Fibre Channel protocols [FC-FS3]. 665 - Network Entity: The Network Entity represents a device or 666 gateway that is accessible from the IP network. A Network Entity 667 must have one or more Network Portals, each of which can be used 668 to gain access to the IP network by some iSCSI Nodes contained in 669 that Network Entity. 671 - Network Portal: The Network Portal is a component of a Network 672 Entity that has a TCP/IP network address and that may be used by 673 an iSCSI Node within that Network Entity for the connection(s) 674 within one of its iSCSI sessions. A Network Portal in an initiator 675 is identified by its IP address. A Network Portal in a target is 676 identified by its IP address and its listening TCP port. 678 - Originator: In a negotiation or exchange, the party that 679 initiates the negotiation or exchange. 681 - PDU (Protocol Data Unit): The initiator and target divide their 682 communications into messages. The term "iSCSI protocol data unit" 683 (iSCSI PDU) is used for these messages. 685 - Portal Groups: iSCSI supports multiple connections within the 686 same session; some implementations will have the ability to 687 combine connections in a session across multiple Network Portals. 688 A Portal Group defines a set of Network Portals within an iSCSI 689 Network Entity that collectively supports the capability of 690 coordinating a session with connections spanning these portals. 691 Not all Network Portals within a Portal Group need participate in 692 every session connected through that Portal Group. One or more 693 Portal Groups may provide access to an iSCSI Node. Each Network 694 Portal, as utilized by a given iSCSI Node, belongs to exactly one 695 portal group within that node. 697 - Portal Group Tag: This 16-bit quantity identifies a Portal Group 698 within an iSCSI Node. All Network Portals with the same portal 699 group tag in the context of a given iSCSI Node are in the same 700 Portal Group. 702 - Recovery R2T: An R2T generated by a target upon detecting the 703 loss of one or more Data-Out PDUs through one of the following 704 means: a digest error, a sequence error, or a sequence reception 705 timeout. A recovery R2T carries the next unused R2TSN, but 706 requests all or part of the data burst that an earlier R2T (with a 707 lower R2TSN) had already requested. 709 - Responder: In a negotiation or exchange, the party that responds 710 to the originator of the negotiation or exchange. 712 - SAS: Serial Attached SCSI. The Serial Attached SCSI (SAS) 713 standard contains both a physical layer compatible with Serial 714 ATA, and protocols for transporting SCSI commands to SAS devices 715 and ATA commands to SATA devices [SAS]. 717 - SCSI Device: This is the SAM2 term for an entity that contains 718 one or more SCSI ports that are connected to a service delivery 719 subsystem and supports a SCSI application protocol. For example, a 720 SCSI Initiator Device contains one or more SCSI Initiator Ports 721 and zero or more application clients. A Target Device contains one 722 or more SCSI Target Ports and one or more device servers and 723 associated logical units. For iSCSI, the SCSI Device is the 724 component within an iSCSI Node that provides the SCSI 725 functionality. As such, there can be, at most, one SCSI Device 726 within a given iSCSI Node. Access to the SCSI Device can only be 727 achieved in an iSCSI normal operational session. The SCSI Device 728 Name is defined to be the iSCSI Name of the node. 730 - SCSI Layer: This builds/receives SCSI CDBs (Command Descriptor 731 Blocks) and relays/receives them with the remaining command 732 execute [SAM2] parameters to/from the iSCSI Layer. 734 - Session: The group of TCP connections that link an initiator 735 with a target form a session (loosely equivalent to a SCSI I-T 736 nexus). TCP connections can be added and removed from a session. 738 Across all connections within a session, an initiator sees one and 739 the same target. 741 - SCSI Port: This is the SAM2 term for an entity in a SCSI Device 742 that provides the SCSI functionality to interface with a service 743 delivery subsystem. For iSCSI, the definition of the SCSI 744 Initiator Port and the SCSI Target Port are different. 746 - SCSI Initiator Port: This maps to the endpoint of an iSCSI 747 normal operational session. An iSCSI normal operational session is 748 negotiated through the login process between an iSCSI initiator 749 node and an iSCSI target node. At successful completion of this 750 process, a SCSI Initiator Port is created within the SCSI 751 Initiator Device. The SCSI Initiator Port Name and SCSI Initiator 752 Port Identifier are both defined to be the iSCSI Initiator Name 753 together with (a) a label that identifies it as an initiator port 754 name/identifier and (b) the ISID portion of the session 755 identifier. 757 - SCSI Port Name: A name consisting of UTF-8 [RFC3629] encoding of 758 Unicode [UNICODE] characters and includes the iSCSI Name + 'i' or 759 't' + ISID or Portal Group Tag. 761 - SCSI-Presented Data Transfer Length (SPDTL): SPDTL is the 762 aggregate data length of the data that the SCSI layer logically 763 "presents" to the iSCSI layer for a Data-In or Data-Out transfer 764 in the context of a SCSI task. For a bidirectional task, there are 765 two SPDTL values -- one for Data-In and one for Data-Out. Note 766 that the notion of "presenting" includes immediate data per the 767 data transfer model in [SAM2], and excludes overlapping data 768 transfers, if any, requested by the SCSI layer. 770 - SCSI Target Port: This maps to an iSCSI Target Portal Group. 772 - SCSI Target Port Name and SCSI Target Port Identifier: These are 773 both defined to be the iSCSI Target Name together with (a) a label 774 that identifies it as a target port name/identifier and (b) the 775 portal group tag. 777 - SSID (Session ID): A session between an iSCSI initiator and an 778 iSCSI target is defined by a session ID that is a tuple composed 779 of an initiator part (ISID) and a target part (Target Portal Group 780 Tag). The ISID is explicitly specified by the initiator at session 781 establishment. The Target Portal Group Tag is implied by the 782 initiator through the selection of the TCP endpoint at connection 783 establishment. The TargetPortalGroupTag key must also be returned 784 by the target as a confimation during connection establishment. 786 - T10: A technical committee within INCITS that develops standards 787 and technical reports on I/O interfaces, particularly the series 788 of SCSI (Small Computer Systems Interface) standards. See 789 http://www.t10.org. 791 - T11: A technical committee within INCITS responsible for 792 standards development in the areas of Intelligent Peripheral 793 Interface (IPI), High-Performance Parallel Interface (HIPPI) and 794 Fibre Channel (FC). See http://www.t11.org. 796 - Target Portal Group Tag: A numerical identifier (16-bit) for an 797 iSCSI Target Portal Group. 799 -Target Transfer Tag (TTT): An iSCSI protocol field used in a few 800 iSCSI PDUs (e.g. R2T, NOP-In) which is always sent from the target 801 to the initiator first and then quoted as a reference in 802 initiator-sent PDUs back to the target relating to the same 803 task/exchange. So effectively, TTT acts as an opaque handle to an 804 existing task/exchange to help target associate the incoming PDUs 805 from the initiator to the proper execution context. 807 - Third-party: A term used in this document as a qualifier to 808 nexus objects (I_T or I_T_L) and iSCSI sessions, to indicate that 809 these objects and sessions reap the side effects of actions that 810 take place in the context of a separate iSCSI session. One 811 example of a third-party session is an iSCSI session discovering 812 that its I_T_L nexus to an LU got reset due to an LU Reset 813 operation orchestrated via a separate I_T nexus. 815 - TSIH (Target Session Identifying Handle): A target assigned tag 816 for a session with a specific named initiator. The target 817 generates it during session establishment. Other than defining it 818 as a 16 bit binary string, its internal format and content are not 819 defined by this protocol but for the all 0 value that is reserved 820 and used by the initiator to indicate a new session. It is given 821 to the target during additional connection establishment for the 822 same session. 824 2.3. Summary of Changes 826 1) Consolidated RFCs 3720, 3980, 4850 and 5048, and made the 827 necessary editorial changes 828 2) iSCSIProtocolLevel is specified as "1" in Section 13.24, and 829 added a related normative reference to [iSCSI-SAM] draft 830 3) Markers and related keys were removed 831 4) SPKM authentication and related keys were removed 832 5) Added a new Section 13.25 on responding to obsoleted keys 833 6) Have explicitly allowed initiator+target implementations 834 throughout the text 835 7) Clarified in Section 4.2.7 that implementations SHOULD NOT 836 rely on SLP-based discovery 837 8) Added UML diagrams and related conventions in Section 3 838 9) FastAbort implementation is made a "SHOULD" requirement in 839 Section 4.2.3.4 from the previous "MUST" requirement. 840 10) Required in Section 4.2.7.1 that iSCSI Target Name must be 841 the same as iSCSI Initiator Name for SCSI (composite) devices 842 with both roles 843 11) Changed the "MUST NOT" to "should avoid" in Section 4.2.7.2 844 regarding usage of characters such as punctuation marks in 845 iSCSI Names. 846 12) Updated Section 9.3 to require the following: MUST implement 847 IPsec, 2400-series RFCs (IPsec v2, IKEv1) and SHOULD implement 848 IPsec, 4300-series RFCs (IPsec v3, IKEv2). 849 13) Clarified in Section 10.2 that ACA is a SHOULD requirement 850 only for iSCSI targets 851 14) Prohibited usage of X# name prefix for new public keys in 852 Section 6.2 853 15) Prohibited usage of Y# name prefix for new digest extensions 854 in Section 13.1, and Z# name prefix for new authentication 855 method extensions in Section 12.1 856 16) Added a SHOULD requirement in Section 6.2 that initiators and 857 targets support at least six (6) exchanges during text 858 negotiation. 859 17) Added a clarification that Appendix.C is normative. 861 18) Added a normative requirement on [IPSEC-IPS] draft, and made 862 a few related changes in Section 9.3 to align the text in this 863 document with that of [IPSEC-IPS] 864 19) Added a new Section 9.2.3 covering Kerberos authentication 865 considerations 867 2.4. Conventions 869 In examples, "I->" and "T->" show iSCSI PDUs sent by the initiator 870 and target respectively. 872 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL 873 NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" 874 in this document are to be interpreted as described in RFC 2119 875 [RFC2119]. 877 3. UML Conventions 879 3.1. UML Conventions Overview 881 The SCSI Architecture Model (SAM) uses class diagrams and object 882 diagrams with notation that is based on the Unified Modeling 883 Language [UML]. Therefore, this document also uses UML to model 884 the relationships for SCSI and iSCSI objects. 886 A treatise on the graphical notation used in UML is beyond the 887 scope of this document. However, given the use of ASCII drawing 888 for UML static class diagrams, a description of the notational 889 conventions used in this document is included in the remainder of 890 this Section. 892 3.2. Multiplicity Notion 894 Not specified The number of instances of an attribute is not 895 specified. 897 1 One instance of the class or attribute exists. 899 0..* Zero or more instances of the class or attribute exist. 901 1..* One or more instances of the class or attribute exist. 903 0..1 Zero or one instance of the class or attribute exists. 905 n..m n to m instances of the class or attribute exist 906 (e.g., 2..8). 908 x, n..m Multiple disjoint instances of the class or 909 attribute exist (e.g., 2, 8..15). 911 3.3. Class Diagram Conventions 913 +--------------+ +--------------+ +--------------+ 914 | Class Name | | Class Name | | Class Name | 915 +--------------+ +--------------+ +--------------+ 916 | | | | 917 +--------------+ +--------------+ 918 | | 919 +--------------+ 920 The previous three diagrams are examples of a class with no 921 attributes and with no operations. 923 +-------------------+ +-------------------+ 924 | Class Name | | Class Name | 925 +-------------------+ +-------------------+ 926 | attribute 01[1] | | attribute 01[1] | 927 | attribute 02[1] | | attribute 02[1] | 928 +-------------------+ +-------------------+ 929 | | 930 +-------------------+ 931 The preceding two diagrams are examples of a class with attributes 932 and with no operations. 934 +------------------------+ 935 | Class Name | 936 +------------------------+ 937 | attribute 01[1..*] | 938 | attribute 02[1] | 939 +------------------------+ 940 | operation 01() | 941 | operation 02() | 942 +------------------------+ 943 The preceding diagram is an example of a class with attributes 944 that have a specified multiplicity and operations. 946 3.4. Class Diagram Notation for Associations 948 +-----------------+ 949 | Class A | 950 +-----------------+ association_name +-----------------+ 951 | attribute 01[1] |<------------------>| Class B | 952 | attribute 02[1] | 1..* 0..1 +-----------------+ 953 +-----------------+ | attribute 03[1] | 954 | operation 1() | +-----------------+ 955 +-----------------+ 956 The preceding diagram is an example where Class A knows about 957 Class B (i.e., read as "Class A association_name ClassB") and 958 Class B knows about Class A (i.e., read as "Class B 959 association_name Class A"). The use of association_name is 960 optional. The multiplicity notation (1..* and 0..1) indicates the 961 number of instances of the object. 963 +--------------------+ 964 | Class A | 965 +--------------------+ +--------------------+ 966 | attribute 01[1] |<-------------| Class B | 967 | attribute 02[1] | 1 0..1 +--------------------+ 968 +--------------------+ | attribute 03[1] | 969 | operation 1() | +--------------------+ 970 +--------------------+ 971 The preceding diagram is an example where Class B knows about 972 Class A (i.e., read as "Class B knows about Class A") but Class A 973 does not know about Class B. 975 +----------------------+ 976 | Class A | 977 +----------------------+ +--------------------+ 978 | attribute 01[1] |----------->| Class B | 979 | attribute 02[1] | 0..* 1 +--------------------+ 980 +----------------------+ | attribute 03[1] | 981 | operation 1() | +--------------------+ 982 +----------------------+ 983 The preceding diagram is an example where Class A knows about 984 Class B (i.e., read as "Class A knows about Class B") but Class B 985 does not know about Class A. 987 3.5. Class Diagram Notation for Aggregations 989 +---------------+ +--------------+ 990 | Class whole |o------------| Class part | 991 +---------------+ +--------------+ 992 The preceding diagram is an example where Class whole is an 993 aggregate that contains Class part and where Class part may 994 continue to exist even if Class whole is removed (i.e., read as 995 "the whole contains the part"). 997 +---------------+ +--------------+ 998 | Class whole |@------------| Class part | 999 +---------------+ +--------------+ 1000 The preceding diagram is an example where Class whole is an 1001 aggregate that contains Class part where Class part only belongs 1002 to one Class whole, and the Class part does not continue to exist 1003 if the Class whole is removed (i.e., read as "the whole contains 1004 the part"). 1006 +-------------+ 1007 | | 1008 +-------------+ 1009 | | 1010 + =(a)= + 1011 | | 1012 The preceding diagram is an example where there is a constraint 1013 between the associations where the (a) footnote describes the 1014 constraint. 1016 3.6. Class Diagram Notation for Generalizations 1018 +---------------+ 1019 | Superclass | 1020 +-------^-------+ 1021 /_\ 1022 | 1023 +---------------+ 1024 | Subclass | 1025 +---------------+ 1026 The preceding diagram is an example where the subclass is a kind 1027 of superclass. A subclass shares all the attributes and 1028 operations of the superclass (i.e., the subclass inherits from the 1029 superclass). 1031 4. Overview 1033 4.1. SCSI Concepts 1035 The SCSI Architecture Model-2 [SAM2] describes in detail the 1036 architecture of the SCSI family of I/O protocols. This Section 1037 provides a brief background of the SCSI architecture and is 1038 intended to familiarize readers with its terminology. 1040 At the highest level, SCSI is a family of interfaces for 1041 requesting services from I/O devices, including hard drives, tape 1042 drives, CD and DVD drives, printers, and scanners. In SCSI 1043 terminology, an individual I/O device is called a "logical unit" 1044 (LU). 1046 SCSI is a client-server architecture. Clients of a SCSI interface 1047 are called "initiators". Initiators issue SCSI "commands" to 1048 request services from components, logical units, of a server known 1049 as a "target". The "device server" on the logical unit accepts 1050 SCSI commands and processes them. 1052 A "SCSI transport" maps the client-server SCSI protocol to a 1053 specific interconnect. Initiator is one endpoint of a SCSI 1054 transport. The "target" is the other endpoint. A target can 1055 contain multiple Logical Units (LUs). Each Logical Unit has an 1056 address within a target called a Logical Unit Number (LUN). 1058 A SCSI task is a SCSI command or possibly a linked set of SCSI 1059 commands. Some LUs support multiple pending (queued) tasks, but 1060 the queue of tasks is managed by the logical unit. The target uses 1061 an initiator provided "task tag" to distinguish between tasks. 1062 Only one command in a task can be outstanding at any given time. 1064 Each SCSI command results in an optional data phase and a required 1065 response phase. In the data phase, information can travel from the 1066 initiator to target (e.g., WRITE), target to initiator (e.g., 1067 READ), or in both directions. In the response phase, the target 1068 returns the final status of the operation, including any errors. 1070 Command Descriptor Blocks (CDB) are the data structures used to 1071 contain the command parameters that an initiator sends to a 1073 target. The CDB content and structure is defined by [SAM2] and 1074 device-type specific SCSI standards. 1076 4.2. iSCSI Concepts and Functional Overview 1078 The iSCSI protocol is a mapping of the SCSI command, event and 1079 task management model (see [SAM2]) over the TCP protocol. SCSI 1080 commands are carried by iSCSI requests and SCSI responses and 1081 status are carried by iSCSI responses. iSCSI also uses the request 1082 response mechanism for iSCSI protocol mechanisms. 1084 For the remainder of this document, the terms "initiator" and 1085 "target" refer to "iSCSI initiator node" and "iSCSI target node", 1086 respectively (see iSCSI) unless otherwise qualified. 1088 As its title suggests, Section 4 presents an overview of the iSCSI 1089 concepts, and later Sections in the rest of the specification 1090 contain the normative requirements - in many cases covering the 1091 same concepts discussed in Section 4. Such normative requirements 1092 text overrides the overview text in Section 4 if there is a 1093 disagreement between the two. 1095 In keeping with similar protocols, the initiator and target divide 1096 their communications into messages. This document uses the term 1097 "iSCSI protocol data unit" (iSCSI PDU) for these messages. 1099 For performance reasons, iSCSI allows a "phase-collapse". A 1100 command and its associated data may be shipped together from 1101 initiator to target, and data and responses may be shipped 1102 together from targets. 1104 The iSCSI transfer direction is defined with respect to the 1105 initiator. Outbound or outgoing transfers are transfers from an 1106 initiator to a target, while inbound or incoming transfers are 1107 from a target to an initiator. 1109 An iSCSI task is an iSCSI request for which a response is 1110 expected. 1112 In this document "iSCSI request", "iSCSI command", request, or 1113 (unqualified) command have the same meaning. Also, unless 1114 otherwise specified, status, response, or numbered response have 1115 the same meaning. 1117 4.2.1. Layers and Sessions 1119 The following conceptual layering model is used to specify 1120 initiator and target actions and the way in which they relate to 1121 transmitted and received Protocol Data Units: 1123 - The SCSI layer builds/receives SCSI CDBs (Command Descriptor 1124 Blocks) and passes/receives them with the remaining command 1125 execute parameters ([SAM2]) to/from 1127 - the iSCSI layer that builds/receives iSCSI PDUs and 1128 relays/receives them to/from one or more TCP connections; 1129 the group of connections form an initiator-target "session". 1131 Communication between the initiator and target occurs over one or 1132 more TCP connections. The TCP connections carry control messages, 1133 SCSI commands, parameters, and data within iSCSI Protocol Data 1134 Units (iSCSI PDUs). The group of TCP connections that link an 1135 initiator with a target form a session (equivalent to a SCSI I_T 1136 nexus, see Section 4.4.2). A session is defined by a session ID 1137 that is composed of an initiator part and a target part. TCP 1138 connections can be added and removed from a session. Each 1139 connection within a session is identified by a connection ID 1140 (CID). 1142 Across all connections within a session, an initiator sees one 1143 "target image". All target identifying elements, such as LUN, are 1144 the same. A target also sees one "initiator image" across all 1145 connections within a session. Initiator-identifying elements, such 1146 as the Initiator Task Tag, are global across the session 1147 regardless of the connection on which they are sent or received. 1149 iSCSI targets and initiators MUST support at least one TCP 1150 connection and MAY support several connections in a session. For 1151 error recovery purposes, targets and initiators that support a 1152 single active connection in a session SHOULD support two 1153 connections during recovery. 1155 4.2.2. Ordering and iSCSI Numbering 1157 iSCSI uses Command and Status numbering schemes and a Data 1158 sequencing scheme. 1160 Command numbering is session-wide and is used for ordered command 1161 delivery over multiple connections. It can also be used as a 1162 mechanism for command flow control over a session. 1164 Status numbering is per connection and is used to enable missing 1165 status detection and recovery in the presence of transient or 1166 permanent communication errors. 1168 Data sequencing is per command or part of a command (R2T-triggered 1169 sequence) and is used to detect missing data and/or R2T PDUs due 1170 to header digest errors. 1172 Typically, fields in the iSCSI PDUs communicate the Sequence 1173 Numbers between the initiator and target. During periods when 1174 traffic on a connection is unidirectional, iSCSI NOP-Out/In PDUs 1175 may be utilized to synchronize the command and status ordering 1176 counters of the target and initiator. 1178 The iSCSI session abstraction is equivalent to the SCSI I_T nexus, 1179 and the iSCSI session provides an ordered command delivery from 1180 the SCSI initiator to the SCSI target. For detailed design 1181 considerations that led to the iSCSI session model as it is 1182 defined here and how it relates the SCSI command ordering features 1183 defined in SCSI specifications to the iSCSI concepts see 1184 [RFC3783]. 1186 4.2.2.1. Command Numbering and Acknowledging 1188 iSCSI performs ordered command delivery within a session. All 1189 commands (initiator-to-target PDUs) in transit from the initiator 1190 to the target are numbered. 1192 iSCSI considers a task to be instantiated on the target in 1193 response to every request issued by the initiator. A set of task 1194 management operations including abort and reassign (see Section 1195 11.5) may be performed on an iSCSI task - however an abort 1196 operation cannot be performed on a task management operation, and 1197 usage of reassign operation has certain constraints. See Section 1198 11.5.1 for the details. 1200 Some iSCSI tasks are SCSI tasks, and many SCSI activities are 1201 related to a SCSI task ([SAM2]). In all cases, the task is 1202 identified by the Initiator Task Tag for the life of the task. 1204 The command number is carried by the iSCSI PDU as CmdSN (Command- 1205 Sequence-Number). The numbering is session-wide. Outgoing iSCSI 1206 PDUs carry this number. The iSCSI initiator allocates CmdSNs with 1207 a 32-bit unsigned counter (modulo 2**32). Comparisons and 1208 arithmetic on CmdSN use Serial Number Arithmetic as defined in 1209 [RFC1982] where SERIAL_BITS = 32. 1211 Commands meant for immediate delivery are marked with an immediate 1212 delivery flag; they MUST also carry the current CmdSN. CmdSN MUST 1213 NOT advance after a command marked for immediate delivery is sent. 1215 Command numbering starts with the first login request on the first 1216 connection of a session (the leading login on the leading 1217 connection) and CmdSN MUST be incremented by 1, in a Serial Number 1218 Arithmetic sense as defined in [RFC1982], for every non-immediate 1219 command issued afterwards. 1221 If immediate delivery is used with task management commands, these 1222 commands may reach the target before the tasks on which they are 1223 supposed to act. However their CmdSN serves as a marker of their 1224 position in the stream of commands. The initiator and target MUST 1225 ensure that the SCSI task management functions specified in [SAM2] 1226 act in accordance with the [SAM2] specification. For example, both 1227 commands and responses appear as if delivered in order. Whenever 1228 CmdSN for an outgoing PDU is not specified by an explicit rule, 1229 CmdSN will carry the current value of the local CmdSN variable 1230 (see later in this Section). 1232 The means by which an implementation decides to mark a PDU for 1233 immediate delivery or by which iSCSI decides by itself to mark a 1234 PDU for immediate delivery are beyond the scope of this document. 1236 The number of commands used for immediate delivery is not limited 1237 and their delivery to execution is not acknowledged through the 1238 numbering scheme. An iSCSI target MAY reject immediate commands, 1239 e.g., due to lack of resources to accommodate additional commands. 1240 An iSCSI target MUST be able to handle at least one immediate task 1241 management command and one immediate non-task-management iSCSI 1242 command per connection at any time. 1244 In this document, delivery for execution means delivery to the 1245 SCSI execution engine or an iSCSI protocol specific execution 1246 engine (e.g., for text requests with public or private extension 1247 keys involving an execution component). With the exception of the 1248 commands marked for immediate delivery, the iSCSI target layer 1249 MUST deliver the commands for execution in the order specified by 1250 CmdSN. Commands marked for immediate delivery may be delivered by 1251 the iSCSI target layer for execution as soon as detected. iSCSI 1252 may avoid delivering some commands to the SCSI target layer if 1253 required by a prior SCSI or iSCSI action (e.g., CLEAR TASK SET 1254 Task Management request received before all the commands on which 1255 it was supposed to act). 1257 On any connection, the iSCSI initiator MUST send the commands in 1258 increasing order of CmdSN, except for commands that are 1259 retransmitted due to digest error recovery and connection 1260 recovery. 1262 For the numbering mechanism, the initiator and target maintain the 1263 following three variables for each session: 1265 - CmdSN - the current command Sequence Number, advanced by 1 1266 on each command shipped except for commands marked for 1267 immediate delivery (see Section 4.2.2.1). CmdSN always 1268 contains the number to be assigned to the next Command PDU. 1270 - ExpCmdSN - the next expected command by the target. The 1271 target acknowledges all commands up to, but not including, 1272 this number. The initiator treats all commands with CmdSN 1273 less than ExpCmdSN as acknowledged. The target iSCSI layer 1274 sets the ExpCmdSN to the largest non-immediate CmdSN that it 1275 can deliver for execution "plus 1" per [RFC1982]. There 1276 MUST NOT be any holes in the acknowledged CmdSN sequence. 1278 - MaxCmdSN - the maximum number to be shipped. The queuing 1279 capacity of the receiving iSCSI layer is MaxCmdSN - ExpCmdSN 1280 + 1. 1282 The initiator's ExpCmdSN and MaxCmdSN are derived from target-to- 1283 initiator PDU fields. Comparisons and arithmetic on ExpCmdSN and 1284 MaxCmdSN MUST use Serial Number Arithmetic as defined in [RFC1982] 1285 where SERIAL_BITS = 32. 1287 The target MUST NOT transmit a MaxCmdSN that is less than 1288 ExpCmdSN-1. For non-immediate commands, the CmdSN field can take 1289 any value from ExpCmdSN to MaxCmdSN inclusive. The target MUST 1290 silently ignore any non-immediate command outside of this range or 1291 non-immediate duplicates within the range. The CmdSN carried by 1292 immediate commands may lie outside the ExpCmdSN to MaxCmdSN range. 1293 For example, if the initiator has previously sent a non-immediate 1294 command carrying the CmdSN equal to MaxCmdSN, the target window is 1295 closed. For group task management commands issued as immediate 1296 commands, CmdSN indicates the scope of the group action (e.g., on 1297 ABORT TASK SET indicates which commands are to be aborted). 1299 MaxCmdSN and ExpCmdSN fields are processed by the initiator as 1300 follows: 1302 -If the PDU MaxCmdSN is less than the PDU ExpCmdSN-1 (in 1303 Serial Arithmetic Sense), they are both ignored. 1305 -If the PDU MaxCmdSN is greater than the local MaxCmdSN (in 1306 Serial Arithmetic Sense), it updates the local MaxCmdSN; 1307 otherwise, it is ignored. 1309 -If the PDU ExpCmdSN is greater than the local ExpCmdSN (in 1310 Serial Arithmetic Sense), it updates the local ExpCmdSN; 1311 otherwise, it is ignored. 1313 This sequence is required because updates may arrive out of order 1314 (e.g., the updates are sent on different TCP connections). 1316 iSCSI initiators and targets MUST support the command numbering 1317 scheme. 1319 A numbered iSCSI request will not change its allocated CmdSN, 1320 regardless of the number of times and circumstances in which it is 1321 reissued (see Section 7.2.1). At the target, CmdSN is only 1322 relevant while the command has not created any state related to 1323 its execution (execution state); afterwards, CmdSN becomes 1324 irrelevant. Testing for the execution state (represented by 1325 identifying the Initiator Task Tag) MUST precede any other action 1326 at the target. If no execution state is found, it is followed by 1327 ordering and delivery. If an execution state is found, it is 1328 followed by delivery if it has not already been delivered. 1330 If an initiator issues a command retry for a command with CmdSN R 1331 on a connection when the session CmdSN value is Q, it MUST NOT 1332 advance the CmdSN past R + 2**31 -1 unless the connection is no 1333 longer operational (i.e., it has returned to the FREE state, see 1334 Section 8.1.3), the connection has been reinstated (see Section 1335 6.3.4), or a non-immediate command with CmdSN equal or greater 1336 than Q was issued subsequent to the command retry on the same 1337 connection and the reception of that command is acknowledged by 1338 the target (see Section 10.4). 1340 A target command response or Data-in PDU with status MUST NOT 1341 precede the command acknowledgement. However, the acknowledgement 1342 MAY be included in the response or the Data-in PDU. 1344 4.2.2.2. Response/Status Numbering and Acknowledging 1346 Responses in transit from the target to the initiator are 1347 numbered. The StatSN (Status Sequence Number) is used for this 1348 purpose. StatSN is a counter maintained per connection. ExpStatSN 1349 is used by the initiator to acknowledge status. The status 1350 sequence number space is 32-bit unsigned-integers and the 1351 arithmetic operations are the regular mod(2**32) arithmetic. 1353 Status numbering starts with the Login response to the first Login 1354 request of the connection. The Login response includes an initial 1355 value for status numbering (any initial value is valid). 1357 To enable command recovery, the target MAY maintain enough state 1358 information for data and status recovery after a connection 1359 failure. A target doing so can safely discard all of the state 1360 information maintained for recovery of a command after the 1361 delivery of the status for the command (numbered StatSN) is 1362 acknowledged through ExpStatSN. 1364 A large absolute difference between StatSN and ExpStatSN may 1365 indicate a failed connection. Initiators MUST undertake recovery 1366 actions if the difference is greater than an implementation 1367 defined constant that MUST NOT exceed 2**31-1. 1369 Initiators and Targets MUST support the response-numbering scheme. 1371 4.2.2.3. Response Ordering 1373 4.2.2.3.1. Need for Response Ordering 1375 Whenever an iSCSI session is composed of multiple connections, the 1376 Response PDUs (task responses or TMF responses) originating in 1377 the target SCSI layer are distributed onto the multiple 1378 connections by the target iSCSI layer according to iSCSI 1379 connection allegiance rules. This process generally may not 1380 preserve the ordering of the responses by the time they are 1381 delivered to the initiator SCSI layer. 1383 Since ordering is not expected across SCSI responses anyway, this 1384 approach works fine in the general case. However, to address the 1385 special cases where some ordering is desired by the SCSI layer, we 1386 introduce the notion of a "Response Fence": Response Fence is 1387 logically the attribute/property of a SCSI response message handed 1388 off to a target iSCSI layer which indicates that there are special 1389 SCSI-level ordering considerations associated with this particular 1390 response message - whenever Response Fence is set or required on a 1391 SCSI response message, we define the semantics in 4.2.2.3.2 with 1392 respect to target iSCSI layer's handling of such SCSI response 1393 messages. 1395 4.2.2.3.2. Response Ordering Model Description 1397 The target SCSI protocol layer hands off the SCSI response 1398 messages to the target iSCSI layer by invoking the "Send Command 1399 Complete" protocol data service ([SAM2], clause 5.4.2) and "Task 1400 Management Function Executed" ([SAM2], clause 6.9) service. On 1401 receiving the SCSI response message, the iSCSI layer exhibits the 1402 Response Fence behavior for certain SCSI response messages 1403 (Section 4.2.2.3.4 describes the specific instances where the 1404 semantics must be realized). 1406 Whenever the Response Fence behavior is required for a SCSI 1407 response message, the target iSCSI layer MUST ensure that the 1408 following conditions are met in delivering the response message to 1409 the initiator iSCSI layer: 1411 - Response with Response Fence MUST be delivered 1412 chronologically after all the "preceding" responses on the 1413 I_T_L nexus, if the preceding responses are delivered at 1414 all, to the initiator iSCSI layer. 1416 - Response with Response Fence MUST be delivered 1417 chronologically prior to all the "following" responses on 1418 the I_T_L nexus. 1420 The "preceding" and "following" notions refer to the order of 1421 handoff of a response message from the target SCSI protocol layer 1422 to the target iSCSI layer. 1424 4.2.2.3.3. iSCSI Semantics with the Interface Model 1426 Whenever the TaskReporting key (Section 13.23) is negotiated to 1427 ResponseFence or FastAbort for an iSCSI session and the Response 1428 Fence behavior is required for a SCSI response message, the target 1429 iSCSI layer MUST perform the actions described in this Section for 1430 that session. 1432 a) If it is a single-connection session, no special 1433 processing is required. The standard SCSI Response PDU 1434 build and dispatch process happens. 1435 b) If it is a multi-connection session, the target iSCSI 1436 layer takes note of the last-sent and unacknowledged 1437 StatSN on each of the connections in the iSCSI session, 1438 and waits for an acknowledgement (NOP-In PDUs MAY be used 1439 to solicit acknowledgements as needed in order to 1440 accelerate this process) of each such StatSN to clear the 1441 fence. The SCSI response requiring Response Fence 1442 behavior MUST NOT be sent to the initiator before 1443 acknowledgements are received for each of the 1444 unacknowledged StatSNs. 1445 c) The target iSCSI layer must wait for an acknowledgement 1446 of the SCSI Response PDU that carried the SCSI response 1447 requiring the Response Fence behavior. The fence MUST be 1448 considered cleared only after receiving the 1449 acknowledgement. 1450 d) All further status processing for the LU is resumed only 1451 after clearing the fence. If any new responses for the 1452 I_T_L nexus are received from the SCSI layer before the 1453 fence is cleared, those Response PDUs MUST be held and 1454 queued at the iSCSI layer until the fence is cleared. 1456 4.2.2.3.4. Current List of Fenced Response Use Cases 1458 This Section lists the situations in which fenced response 1459 behavior is REQUIRED in iSCSI target implementations. Note that 1460 the following list is an exhaustive enumeration as currently 1461 identified - it is expected that as SCSI protocol specifications 1462 evolve, the specifications will specify when response fencing is 1463 required on a case-by-case basis. 1465 Whenever the TaskReporting key (Section 13.23) is negotiated to 1466 ResponseFence or FastAbort for an iSCSI session, the target iSCSI 1467 layer MUST assume that the Response Fence is required for the 1468 following SCSI completion messages: 1470 1. The first completion message carrying the UA after the 1471 multi-task abort on issuing and third-party sessions. See 1472 Section 4.2.3.2 for related TMF discussion. 1474 2. The TMF Response carrying the multi-task TMF Response on 1475 the issuing session. 1477 3. The completion message indicating ACA establishment on the 1478 issuing session. 1480 4. The first completion message carrying the ACA ACTIVE status 1481 after ACA establishment on issuing and third-party 1482 sessions. 1484 5. The TMF Response carrying the Clear ACA response on the 1485 issuing session. 1487 6. The response to a PERSISTENT RESERVE OUT/PREEMPT AND ABORT 1488 command. 1490 Note: 1491 - Due to the absence of ACA-related fencing requirements in 1492 [RFC3720], initiator implementations SHOULD NOT use ACA on 1493 multi-connection iSCSI sessions with targets complying only 1494 with [RFC3720]. This can be determined via TaskReporting key 1495 (Section 13.23) negotiation - when the negotiation results 1496 in either "RFC3720" or "NotUnderstood". 1498 - Initiators that want to employ ACA on multi-connection iSCSI 1499 sessions SHOULD first assess response-fencing behavior via 1500 negotiating for "ResponseFence" or "FastAbort" value for the 1501 TaskReporting (Section 13.23) key. 1503 4.2.2.4. Data Sequencing 1505 Data and R2T PDUs transferred as part of some command execution 1506 MUST be sequenced. The DataSN field is used for data sequencing. 1507 For input (read) data PDUs, DataSN starts with 0 for the first 1508 data PDU of an input command and advances by 1 for each subsequent 1509 data PDU. For output data PDUs, DataSN starts with 0 for the first 1510 data PDU of a sequence (the initial unsolicited sequence or any 1511 data PDU sequence issued to satisfy an R2T) and advances by 1 for 1512 each subsequent data PDU. R2Ts are also sequenced per command. For 1513 example, the first R2T has an R2TSN of 0 and advances by 1 for 1514 each subsequent R2T. For bidirectional commands, the target uses 1515 the DataSN/R2TSN to sequence Data-In and R2T PDUs in one 1516 continuous sequence (undifferentiated). Unlike command and status, 1517 data PDUs and R2Ts are not acknowledged by a field in regular 1518 outgoing PDUs. Data-In PDUs can be acknowledged on demand by a 1519 special form of the SNACK PDU. Data and R2T PDUs are implicitly 1520 acknowledged by status for the command. The DataSN/R2TSN field 1521 enables the initiator to detect missing data or R2T PDUs. 1523 For any read or bidirectional command, a target MUST issue less 1524 than 2**32 combined R2T and Data-In PDUs. Any output data sequence 1525 MUST contain less than 2**32 Data-Out PDUs. 1527 4.2.3. iSCSI Task Management 1529 4.2.3.1. Task Management Overview 1531 iSCSI task management features allow an initiator to control the 1532 active iSCSI tasks on an operational iSCSI session that it has 1533 with an iSCSI target. Section 11.5 defines the task management 1534 function types that this specification defines - ABORT TASK, ABORT 1535 TASK SET, CLEAR ACA, CLEAR TASK SET, LOGICAL UNIT RESET, TARGET 1536 WARM RESET, TARGET COLD RESET, and TASK REASSIGN. 1538 Out of these function types, ABORT TASK and TASK REASSIGN 1539 functions manage a single active task, whereas ABORT TASK SET, 1540 CLEAR TASK SET, LOGICAL UNIT RESET, TARGET WARM RESET and TARGET 1541 COLD RESET functions can each potentially affect multiple active 1542 tasks. 1544 4.2.3.2. Notion of Affected Tasks 1546 This Section defines the notion of "affected tasks" in multi-task 1547 abort scenarios. Scope definitions in this Section apply to both 1548 the Standard Multi-task Abort semantics (Section 4.2.3.3) and the 1549 FastAbort Multi-task Abort semantics behavior (Section 4.2.3.4). 1551 ABORT TASK SET: All outstanding tasks for the I_T_L nexus 1552 identified by the LUN field in the ABORT TASK SET TMF Request PDU 1553 (Section 11.5). 1555 CLEAR TASK SET: All outstanding tasks in the task set for the LU 1556 identified by the LUN field in the CLEAR TASK SET TMF Request PDU. 1557 See [SPC3] for the definition of a "task set". 1559 LOGICAL UNIT RESET: All outstanding tasks from all initiators for 1560 the LU identified by the LUN field in the LOGICAL UNIT RESET 1561 Request PDU. 1563 TARGET WARM RESET/TARGET COLD RESET: All outstanding tasks from 1564 all initiators across all LUs to which the TMF-issuing session has 1565 access on the SCSI target device hosting the iSCSI session. 1567 Usage: An "ABORT TASK SET TMF Request PDU" in the preceding text 1568 is an iSCSI TMF Request PDU with the "Function" field set to 1569 "ABORT TASK SET" as defined in Section 11.5. Similar usage is 1570 employed for other scope descriptions. 1572 4.2.3.3. Standard Multi-task Abort Semantics 1574 All iSCSI implementations MUST support the protocol behavior 1575 defined in this Section as the default behavior. The execution of 1576 ABORT TASK SET, CLEAR TASK SET, LOGICAL UNIT RESET, TARGET WARM 1577 RESET, and TARGET COLD RESET TMF Requests consists of the 1578 following sequence of actions in the specified order on the 1579 specified party. 1581 The initiator iSCSI layer: 1582 a. MUST continue to respond to each TTT received for the 1583 affected tasks. 1584 b. SHOULD process any responses received for affected tasks in 1585 the normal fashion. This is acceptable because the 1586 responses are guaranteed to have been sent prior to the TMF 1587 response. 1588 c. SHOULD receive the TMF Response concluding all the tasks in 1589 the set of affected tasks unless the initiator has done 1590 something (e.g., LU reset, connection drop) that may 1591 prevent the TMF Response from being sent or received. The 1592 initiator MUST thus conclude all affected tasks as part of 1593 this step in either case, and MUST discard any TMF Response 1594 received after the affected tasks are concluded. 1596 The target iSCSI layer: 1597 a. MUST wait for responses on currently valid target-transfer 1598 tags of the affected tasks from the issuing initiator. MAY 1599 wait for responses on currently valid target-transfer tags 1600 of the affected tasks from third-party initiators. 1601 b. MUST wait (concurrent with the wait in Step a) for all 1602 commands of the affected tasks to be received based on the 1603 CmdSN ordering. SHOULD NOT wait for new commands on third- 1604 party affected sessions -- only the instantiated tasks have 1605 to be considered for the purpose of determining the 1606 affected tasks. In the case of target-scoped requests 1607 (i.e., TARGET WARM RESET and TARGET COLD RESET), all of the 1608 commands that are not yet received on the issuing session 1609 in the command stream however can be considered to have 1610 been received with no command waiting period -- i.e., the 1611 entire CmdSN space up to the CmdSN of the task management 1612 function can be "plugged". 1613 c. MUST propagate the TMF request to and receive the response 1614 from the target SCSI layer. 1615 d. MUST provide the Response Fence behavior for the TMF 1616 Response on the issuing session as specified in Section 1617 4.2.2.3.2. 1618 e. MUST provide the Response Fence behavior on the first post- 1619 TMF Response on third-party sessions as specified in 1620 Section 4.2.2.3.3. If some tasks originate from non-iSCSI 1621 I_T_L nexuses, then the means by which the target ensures 1622 that all affected tasks have returned their status to the 1623 initiator are defined by the specific non-iSCSI transport 1624 protocol(s). 1626 Technically, the TMF servicing is complete in Step d. Data 1627 transfers corresponding to terminated tasks may however still be 1628 in progress on third-party iSCSI sessions even at the end of Step 1629 e. The TMF Response MUST NOT be sent by the target iSCSI layer 1630 before the end of Step d, and MAY be sent at the end of Step d 1631 despite these outstanding data transfers until after Step e. 1633 4.2.3.4. FastAbort Multi-task Abort Semantics 1635 Protocol behavior defined in this Section SHOULD be implemented by 1636 all iSCSI implementations complying with this document, noting 1637 that some steps below may not be compatible with [RFC3720] 1638 semantics. However, protocol behavior defined in this Section MUST 1639 be exhibited by iSCSI implementations on an iSCSI session when 1640 they negotiate the TaskReporting (Section 13.23) key to 1641 "FastAbort" on that session. The execution of ABORT TASK SET, 1642 CLEAR TASK SET, LOGICAL UNIT RESET, TARGET WARM RESET, and TARGET 1643 COLD RESET TMF Requests consists of the following sequence of 1644 actions in the specified order on the specified party. 1646 The initiator iSCSI layer: 1648 a. MUST NOT send any more Data-Out PDUs for affected tasks on 1649 the issuing connection of the issuing iSCSI session once 1650 the TMF is sent to the target. 1651 b. SHOULD process any responses received for affected tasks in 1652 the normal fashion. This is acceptable because the 1653 responses are guaranteed to have been sent prior to the TMF 1654 response. 1655 c. MUST respond to each Async Message PDU with FAST_ABORT 1656 AsyncEvent as defined in Section 11.9. 1657 d. MUST treat the TMF response as terminating all affected 1658 tasks for which responses have not been received, and MUST 1659 discard any responses for affected tasks received after the 1660 TMF response is passed to the SCSI layer (although the 1661 semantics defined in this Section ensure that such an out- 1662 of-order scenario will never happen with a compliant target 1663 implementation). 1665 The target iSCSI layer: 1666 a. MUST wait for all commands of the affected tasks to be 1667 received based on the CmdSN ordering on the issuing 1668 session. SHOULD NOT wait for new commands on third-party 1669 affected sessions - only the instantiated tasks have to be 1670 considered for the purpose of determining the affected 1671 tasks. In the case of target-scoped requests (i.e., TARGET 1672 WARM RESET and TARGET COLD RESET), all the commands that 1673 are not yet received on the issuing session in the command 1674 stream can be considered to have been received with no 1675 command waiting period -- i.e., the entire CmdSN space up 1676 to the CmdSN of the task management function can be 1677 "plugged". 1678 b. MUST propagate the TMF request to and receive the response 1679 from the target SCSI layer. 1680 c. MUST leave all active "affected TTTs" (i.e., active TTTs 1681 associated with affected tasks) valid. 1682 d. MUST send an Asynchronous Message PDU with AsyncEvent=5 1683 (Section 11.9) on: 1684 i) each connection of each third-party session to 1685 which at least one affected task is allegiant if 1686 TaskReporting=FastAbort is operational on that third- 1687 party session, and, 1689 ii) each connection except the issuing connection of 1690 the issuing session that has at least one allegiant 1691 affected task. 1692 If there are multiple affected LUs (say, due to a target 1693 reset), then one Async Message PDU MUST be sent for each 1694 such LU on each connection that has at least one allegiant 1695 affected task. The LUN field in the Asynchronous Message PDU 1696 MUST be set to match the LUN for each such LU. 1697 e. MUST address the Response Fence flag on the TMF Response on 1698 the issuing session as defined in Section 4.2.2.3.3. 1699 f. MUST address the Response Fence flag on the first post-TMF 1700 Response on third-party sessions as defined in Section 1701 4.2.2.3.3. If some tasks originate from non-iSCSI I_T_L 1702 nexuses, then the means by which the target ensures that 1703 all affected tasks have returned their status to the 1704 initiator are defined by the specific non-iSCSI transport 1705 protocol(s). 1706 g. MUST free up the affected TTTs (and STags, if applicable) 1707 and the corresponding buffers, if any, once it receives 1708 each associated NOP-Out acknowledgement that the initiator 1709 generated in response to each Async Message. 1711 Technically, the TMF servicing is complete in Step e. Data 1712 transfers corresponding to terminated tasks may however still be 1713 in progress even at the end of Step f. A TMF Response MUST NOT be 1714 sent by the target iSCSI layer before the end of Step e, and MAY 1715 be sent at the end of Step e despite these outstanding Data 1716 transfers until Step g. Step g specifies an event to free up any 1717 such resources that may have been reserved to support outstanding 1718 data transfers. 1720 4.2.3.5. Affected Tasks Shared across Standard and FastAbort Sessions 1722 If an iSCSI target implementation is capable of supporting 1723 TaskReporting=FastAbort functionality (Section 13.23), it may end 1724 up in a situation where some sessions have TaskReporting=RFC3720 1725 operational (RFC 3720 sessions) while some other sessions have 1726 TaskReporting=FastAbort operational (FastAbort sessions) even 1727 while accessing a shared set of affected tasks (Section 4.2.3.2). 1728 If the issuing session is an RFC 3720 session, the iSCSI target 1729 implementation is FastAbort-capable, and the third-party affected 1730 session is a FastAbort session, the following behavior SHOULD be 1731 exhibited by the iSCSI target layer: 1732 a. Between Steps c and d of the target behavior in Section 1733 4.2.3.3, send an Asynchronous Message PDU with AsyncEvent=5 1734 (Section 11.9) on each connection of each third-party 1735 session to which at least one affected task is allegiant. 1736 If there are multiple affected LUs, then send one Async 1737 Message PDU for each such LU on each connection that has at 1738 least one allegiant affected task. When sent, the LUN field 1739 in the Asynchronous Message PDU MUST be set to match the 1740 LUN for each such LU. 1741 b. After Step e of the target behavior in Section 4.2.3.3, 1742 free up the affected TTTs (and STags, if applicable) and 1743 the corresponding buffers, if any, once each associated 1744 NOP-Out acknowledgement is received that the third-party 1745 initiator generated in response to each Async Message sent 1746 in Step a. 1748 If the issuing session is a FastAbort session, the iSCSI target 1749 implementation is FastAbort-capable, and the third-party affected 1750 session is an RFC 3720 session, iSCSI target layer MUST NOT send 1751 Asynchronous Message PDUs on the third-party session to prompt the 1752 FastAbort behavior. 1754 If the third-party affected session is a FastAbort session and the 1755 issuing session is a FastAbort session, the initiator in the 1756 third-party role MUST respond to each Async Message PDU with 1757 AsyncEvent=5 as defined in Section 11.9. Note that an initiator 1758 MAY thus receive these Async Messages on a third-party affected 1759 session even if the session is a single-connection session. 1761 4.2.3.6. Rationale behind the FastAbort Semantics 1763 There are fundamentally three basic objectives behind the 1764 semantics 1765 specified in Sections 4.2.3.3 and 4.2.3.4. 1766 1. Maintaining an ordered command flow I_T nexus abstraction 1767 to the target SCSI layer even with multi-connection 1768 sessions. 1769 - Target iSCSI processing of a TMF request must 1770 maintain the single flow illusion. Target behavior in 1772 Step b of Section 4.2.3.3 and Step a of Section 4.2.3.4 1773 correspond to this objective. 1774 2. Maintaining a single ordered response flow I_T nexus 1775 abstraction to the initiator SCSI layer even with multi- 1776 connection sessions when one response (i.e., TMF response) 1777 could imply the status of other unfinished tasks from the 1778 initiator's perspective. 1779 - The target must ensure that the initiator does not 1780 see "old" task responses (that were placed on the wire 1781 chronologically earlier than the TMF Response) after 1782 seeing the TMF response. The target behavior in Step d 1783 of Section 4.2.3.3 and Step e of Section 4.2.3.4 1784 correspond to this objective. 1785 - Whenever the result of a TMF action is visible across 1786 multiple I_T_L nexuses, [SAM2] requires the SCSI device 1787 server to trigger a UA on each of the other I_T_L 1788 nexuses. Once an initiator is notified of such an UA, 1789 the application client on the receiving initiator is 1790 required to clear its task state (clause 5.5 in [SAM2]) 1791 for the affected tasks. It would thus be inappropriate 1792 to deliver a SCSI Response for a task after the task 1793 state is cleared on the initiator, i.e., after the UA 1794 is notified. The UA notification contained in the first 1795 SCSI Response PDU on each affected Third-party I_T_L 1796 nexus after the TMF action thus MUST NOT pass the 1797 affected task responses on any of the iSCSI sessions 1798 accessing the LU. The target behavior in Step e of 1799 Section 4.2.3.3 and Step f of Section 4.2.3.4 1800 correspond to this objective. 1801 3. Draining all active TTTs corresponding to affected tasks in 1802 a deterministic fashion. 1803 - Data-Out PDUs with stale TTTs arriving after the 1804 tasks are terminated can create a buffer management 1805 problem even for traditional iSCSI implementations, and 1806 is fatal for the connection for iSCSI/iSER 1807 implementations. Either the termination of affected 1808 tasks should be postponed until the TTTs are retired 1809 (as in Step a of Section 4.2.3.3), or the TTTs and the 1810 buffers should stay allocated beyond task termination 1811 to be deterministically freed up later (as in Steps c 1812 and g of Section 4.2.3.4). 1814 The only other notable optimization is the plugging. If all tasks 1815 on an I_T nexus will be aborted anyway (as with a target reset), 1816 there is no need to wait to receive all commands to plug the CmdSN 1817 holes. The target iSCSI layer can simply plug all missing CmdSN 1818 slots and move on with TMF processing. The first objective 1819 (maintaining a single ordered command flow) is still met with this 1820 optimization because the target SCSI layer only sees ordered 1821 commands. 1823 4.2.4. iSCSI Login 1825 The purpose of the iSCSI login is to enable a TCP connection for 1826 iSCSI use, authentication of the parties, negotiation of the 1827 session's parameters and marking of the connection as belonging to 1828 an iSCSI session. 1830 A session is used to identify to a target all the connections with 1831 a given initiator that belong to the same I_T nexus. (For more 1832 details on how a session relates to an I_T nexus, see Section 1833 4.4.2). 1835 The targets listen on a well-known TCP port or other TCP port for 1836 incoming connections. The initiator begins the login process by 1837 connecting to one of these TCP ports. 1839 As part of the login process, the initiator and target SHOULD 1840 authenticate each other and MAY set a security association 1841 protocol for the session. This can occur in many different ways 1842 and is subject to negotiation - see Section 12. 1844 To protect the TCP connection, an IPsec security association MAY 1845 be established before the Login request. For information on using 1846 IPsec security for iSCSI see Section 9, [RFC3723] and [IPSEC-IPS}. 1848 The iSCSI Login Phase is carried through Login requests and 1849 responses. Once suitable authentication has occurred and 1850 operational parameters have been set, the session transitions to 1851 Full Feature Phase and the initiator may start to send SCSI 1852 commands. The security policy for whether, and by what means, a 1854 target chooses to authorize an initiator is beyond the scope of 1855 this document. For a more detailed description of the Login Phase, 1856 see Section 6. 1858 The login PDU includes the ISID part of the session ID (SSID). The 1859 target portal group that services the login is implied by the 1860 selection of the connection endpoint. For a new session, the TSIH 1861 is zero. As part of the response, the target generates a TSIH. 1863 During session establishment, the target identifies the SCSI 1864 initiator port (the "I" in the "I_T nexus") through the value pair 1865 (InitiatorName, ISID). We describe InitiatorName later in this 1866 Section. Any persistent state (e.g., persistent reservations) on 1867 the target that is associated with a SCSI initiator port is 1868 identified based on this value pair. Any state associated with the 1869 SCSI target port (the "T" in the "I_T nexus") is identified 1870 externally by the TargetName and portal group tag (see Section 1871 4.4.1). ISID is subject to reuse restrictions because it is used 1872 to identify a persistent state (see Section 4.4.3). 1874 Before the Full Feature Phase is established, only Login Request 1875 and Login Response PDUs are allowed. Login requests and responses 1876 MUST be used exclusively during Login. On any connection, the 1877 login phase MUST immediately follow TCP connection establishment 1878 and a subsequent Login Phase MUST NOT occur before tearing down a 1879 connection. 1881 A target receiving any PDU except a Login request before the Login 1882 phase is started MUST immediately terminate the connection on 1883 which the PDU was received. Once the Login phase has started, if 1884 the target receives any PDU except a Login request, it MUST send a 1885 Login reject (with Status "invalid during login") and then 1886 disconnect. If the initiator receives any PDU except a Login 1887 response, it MUST immediately terminate the connection. 1889 4.2.5. iSCSI Full Feature Phase 1891 Once the two sides successfully conclude the Login on the first - 1892 also called the leading - connection in the session, the iSCSI 1893 session is in the iSCSI Full Feature Phase. A connection is in 1894 Full Feature Phase if the session is in Full Feature Phase and the 1895 connection login has completed successfully. An iSCSI connection 1896 is not in Full Feature Phase 1898 a) when it does not have an established transport 1899 connection, 1900 OR 1901 b) when it has a valid transport connection, but a 1902 successful login was not performed or the connection is 1903 currently logged out. 1905 In a normal Full Feature Phase, the initiator may send SCSI 1906 commands and data to the various LUs on the target by 1907 encapsulating them in iSCSI PDUs that go over the established 1908 iSCSI session. 1910 4.2.5.1. Command Connection Allegiance 1912 For any iSCSI request issued over a TCP connection, the 1913 corresponding response and/or other related PDU(s) MUST be sent 1914 over the same connection. We call this "connection allegiance". If 1915 the original connection fails before the command is completed, the 1916 connection allegiance of the command may be explicitly reassigned 1917 to a different transport connection as described in detail in 1918 Section 7.2. 1920 Thus, if an initiator issues a READ command, the target MUST send 1921 the requested data, if any, followed by the status to the 1922 initiator over the same TCP connection that was used to deliver 1923 the SCSI command. If an initiator issues a WRITE command, the 1924 initiator MUST send the data, if any, for that command over the 1925 same TCP connection that was used to deliver the SCSI command. The 1926 target MUST return Ready To Transfer (R2T), if any, and the status 1927 over the same TCP connection that was used to deliver the SCSI 1928 command. Retransmission requests (SNACK PDUs) and the data and 1929 status that they generate MUST also use the same connection. 1931 However, consecutive commands that are part of a SCSI linked 1932 command-chain task (see [SAM2]) MAY use different connections. 1933 Connection allegiance is strictly per-command and not per-task. 1934 During the iSCSI Full Feature Phase, the initiator and target MAY 1935 interleave unrelated SCSI commands, their SCSI Data, and responses 1936 over the session. 1938 4.2.5.2. Data Transfer Overview 1940 Outgoing SCSI data (initiator to target user data or command 1941 parameters) is sent as either solicited data or unsolicited data. 1942 Solicited data are sent in response to R2T PDUs. Unsolicited data 1943 can be sent as part of an iSCSI command PDU ("immediate data") or 1944 in separate iSCSI data PDUs. 1946 Immediate data are assumed to originate at offset 0 in the 1947 initiator SCSI write-buffer (outgoing data buffer). All other Data 1948 PDUs have the buffer offset set explicitly in the PDU header. 1950 An initiator may send unsolicited data up to FirstBurstLength 1951 (see Section 13.14) as immediate (up to the negotiated maximum PDU 1952 length), in a separate PDU sequence or both. All subsequent data 1953 MUST be solicited. The maximum length of an individual data PDU or 1954 the immediate-part of the first unsolicited burst MAY be 1955 negotiated at login. 1957 The maximum amount of unsolicited data that can be sent with a 1958 command is negotiated at login through the FirstBurstLength (see 1959 Section 13.14) key. A target MAY separately enable immediate data 1960 (through the ImmediateData key) without enabling the more general 1961 (separate data PDUs) form of unsolicited data (through the 1962 InitialR2T key). 1964 Unsolicited data on write are meant to reduce the effect of 1965 latency on throughput (no R2T is needed to start sending data). In 1966 addition, immediate data is meant to reduce the protocol overhead 1967 (both bandwidth and execution time). 1969 An iSCSI initiator MAY choose not to send unsolicited data, only 1970 immediate data or FirstBurstLength bytes of unsolicited data with 1971 a command. If any non-immediate unsolicited data is sent, the 1972 total unsolicited data MUST be either FirstBurstLength, or all of 1973 the data if the total amount is less than the FirstBurstLength. 1975 It is considered an error for an initiator to send unsolicited 1976 data PDUs to a target that operates in R2T mode (only solicited 1977 data are allowed). It is also an error for an initiator to send 1978 more unsolicited data, whether immediate or as separate PDUs, than 1979 FirstBurstLength. 1981 An initiator MUST honor an R2T data request for a valid 1982 outstanding command (i.e., carrying a valid Initiator Task Tag) 1983 and deliver all the requested data provided the command is 1984 supposed to deliver outgoing data and the R2T specifies data 1985 within the command bounds. The initiator action is unspecified for 1986 receiving an R2T request that specifies data, all or part, outside 1987 of the bounds of the command. 1989 A target SHOULD NOT silently discard data and then request 1990 retransmission through R2T. Initiators SHOULD NOT keep track of 1991 the data transferred to or from the target (scoreboarding). SCSI 1992 targets perform residual count calculation to check how much data 1993 was actually transferred to or from the device by a command. This 1994 may differ from the amount the initiator sent and/or received for 1995 reasons such as retransmissions and errors. Read or bidirectional 1996 commands implicitly solicit the transmission of the entire amount 1997 of data covered by the command. SCSI data packets are matched to 1998 their corresponding SCSI commands by using tags specified in the 1999 protocol. 2001 In addition, iSCSI initiators and targets MUST enforce some 2002 ordering rules. When unsolicited data is used, the order of the 2003 unsolicited data on each connection MUST match the order in which 2004 the commands on that connection are sent. Command and unsolicited 2005 data PDUs may be interleaved on a single connection as long as the 2006 ordering requirements of each are maintained (e.g., command N+1 2007 MAY be sent before the unsolicited Data-Out PDUs for command N, 2008 but the unsolicited Data-Out PDUs for command N MUST precede the 2009 unsolicited Data-Out PDUs of command N+1). A target that receives 2010 data out of order MAY terminate the session. 2012 4.2.5.3. Tags and Integrity Checks 2014 Initiator tags for pending commands are unique initiator-wide for 2015 a session. Target tags are not strictly specified by the protocol. 2016 It is assumed that target tags are used by the target to tag 2017 (alone or in combination with the LUN) the solicited data. Target 2018 tags are generated by the target and "echoed" by the initiator. 2020 These mechanisms are designed to accomplish efficient data 2021 delivery along with a large degree of control over the data flow. 2023 As the Initiator Task Tag is used to identify a task during its 2024 execution the iSCSI initiator and target MUST verify that all 2025 other fields used in task related PDUs have values that are 2026 consistent with the values used at the task instantiation based on 2027 Initiator Task Tag (e.g., the LUN used in an R2T PDU MUST be the 2028 same as the one used in the SCSI command PDU used to instantiate 2029 the task). Using inconsistent field values is considered a 2030 protocol error. 2032 4.2.5.4. Task Management 2034 SCSI task management assumes that individual tasks and task groups 2035 can be aborted solely based on the task tags (for individual 2036 tasks) or the timing of the task management command (for task 2037 groups) and that the task management action is executed 2038 synchronously - i.e, no message involving an aborted task will be 2039 seen by the SCSI initiator after receiving the task management 2040 response. In iSCSI initiators and targets interact asynchronously 2041 over several connections. iSCSI specifies the protocol mechanism 2042 and implementation requirements needed to present a synchronous 2043 view while using an asynchronous infrastructure. 2045 4.2.6. iSCSI Connection Termination 2047 An iSCSI connection may be terminated by use of a transport 2048 connection shutdown or a transport reset. Transport reset is 2049 assumed to be an exceptional event. 2051 Graceful TCP connection shutdowns are done by sending TCP FINs. A 2052 graceful transport connection shutdown SHOULD only be initiated by 2053 either party when the connection is not in iSCSI Full Feature 2054 Phase. A target MAY terminate a Full Feature Phase connection on 2055 internal exception events, but it SHOULD announce the fact through 2056 an Asynchronous Message PDU. Connection termination with 2057 outstanding commands may require recovery actions. 2059 If a connection is terminated while in Full Feature Phase, 2060 connection cleanup (see Section 7) is required prior to recovery. 2061 By doing connection cleanup before starting recovery, the 2062 initiator and target will avoid receiving stale PDUs after 2063 recovery. 2065 4.2.7. iSCSI Names 2067 Both targets and initiators require names for the purpose of 2068 identification. In addition, names enable iSCSI storage resources 2069 to be managed regardless of location (address). An iSCSI node name 2070 is also the SCSI device name contained in the iSCSI Node. The 2071 iSCSI name of a SCSI device is the principal object used in 2072 authentication of targets to initiators and initiators to targets. 2073 This name is also used to identify and manage iSCSI storage 2074 resources. 2076 iSCSI names must be unique within the operation domain of the end 2077 user. However, because the operation domain of an IP network is 2078 potentially worldwide, the iSCSI name formats are architected to 2079 be worldwide unique. To assist naming authorities in the 2080 construction of worldwide unique names, iSCSI provides three name 2081 formats for different types of naming authorities. 2083 iSCSI names are associated with iSCSI nodes, and not iSCSI network 2084 adapter cards, to ensure that the replacement of network adapter 2085 cards does not require reconfiguration of all SCSI and iSCSI 2086 resource allocation information. 2088 Some SCSI commands require that protocol-specific identifiers be 2089 communicated within SCSI CDBs. See SCSI for the definition of the 2090 SCSI port name/identifier for iSCSI ports. 2092 An initiator may discover the iSCSI Target Names to which it has 2093 access, along with their addresses, using the SendTargets text 2094 request, or other techniques discussed in [RFC3721]. 2096 iSCSI equipment that needs discovery functions beyond SendTargets 2097 SHOULD implement iSNS (see [RFC4171]) for extended discovery 2098 management capabilities and interoperability. Although [RFC3721] 2099 implies an SLP ([RFC2608]) implementation requirement, SLP has not 2100 been widely implemented or deployed for use with iSCSI in 2101 practice. iSCSI implementations therefore SHOULD NOT rely on SLP- 2102 based discovery interoperability. 2104 4.2.7.1. iSCSI Name Properties 2106 Each iSCSI node, whether it is an initiator or target or both, 2107 MUST have an iSCSI name. Whenever an iSCSI Node contains an iSCSI 2108 Initiator Node and an iSCSI Target Node, the iSCSI Initiator Name 2109 MUST be the same as the iSCSI Target Name for the contained Nodes 2110 such that there is only one iSCSI Node Name for the iSCSI Node 2111 overall. Note the related requirements in Section 9.2.1 on how to 2112 map CHAP names to iSCSI Names in such a scenario. 2114 Initiators and targets MUST support the receipt of iSCSI names of 2115 up to the maximum length of 223 bytes. 2117 The initiator MUST present both its iSCSI Initiator Name and the 2118 iSCSI Target Name to which it wishes to connect in the first login 2119 request of a new session or connection. The only exception is if a 2120 discovery session (see Section 4.3) is to be established. In this 2121 case, the iSCSI Initiator Name is still required, but the iSCSI 2122 Target Name MAY be omitted. 2124 iSCSI names have the following properties: 2126 - iSCSI names are globally unique. No two initiators or 2127 targets can have the same name. 2129 - iSCSI names are permanent. An iSCSI initiator node or target 2130 node has the same name for its lifetime. 2132 - iSCSI names do not imply a location or address. An iSCSI 2133 initiator or target can move, or have multiple addresses. A 2134 change of address does not imply a change of name. 2136 - iSCSI names do not rely on a central name broker; the naming 2137 authority is distributed. 2139 - iSCSI names support integration with existing unique naming 2140 schemes. 2142 - iSCSI names rely on existing naming authorities. iSCSI does 2143 not create any new naming authority. 2145 The encoding of an iSCSI name has the following properties: 2147 - iSCSI names have the same encoding method regardless of the 2148 underlying protocols. 2150 - iSCSI names are relatively simple to compare. The algorithm 2151 for comparing two iSCSI names for equivalence does not rely 2152 on an external server. 2154 - iSCSI names are composed only of printable ASCII and Unicode 2155 characters. iSCSI names allow the use of international 2156 character sets but uppercase characters are prohibited. The 2157 iSCSI stringprep profile [RFC3722] maps uppercase characters 2158 to lowercase and SHOULD be used to prepare iSCSI names from 2159 input that may include uppercase characters. No whitespace 2160 characters are used in iSCSI names, see [RFC3722] for 2161 details. 2163 - iSCSI names may be transported using both binary and ASCII- 2164 based protocols. 2166 An iSCSI name really names a logical software entity, and is not 2167 tied to a port or other hardware that can be changed. For 2168 instance, an initiator name should name the iSCSI initiator node, 2169 not a particular NIC or HBA. When multiple NICs are used, they 2170 should generally all present the same iSCSI initiator name to the 2171 targets, because they are simply paths to the same SCSI layer. In 2172 most operating systems, the named entity is the operating system 2173 image. 2175 Similarly, a target name should not be tied to hardware interfaces 2176 that can be changed. A target name should identify the logical 2177 target and must be the same for the target regardless of the 2178 physical portion being addressed. This assists iSCSI initiators in 2179 determining that the two targets it has discovered are really two 2180 paths to the same target. 2182 The iSCSI name is designed to fulfill the functional requirements 2183 for Uniform Resource Names (URN) [RFC1737]. For example, it is 2184 required that the name have a global scope, be independent of 2185 address or location, and be persistent and globally unique. Names 2186 must be extensible and scalable with the use of naming 2187 authorities. The name encoding should be both human and machine 2188 readable. See [RFC1737] for further requirements. 2190 4.2.7.2. iSCSI Name Encoding 2192 An iSCSI name MUST be a UTF-8 (see [RFC3629]) encoding of a string 2193 of Unicode characters with the following properties: 2195 - It is in Normalization Form C (see "Unicode Normalization 2196 Forms" [UNICODE]). 2198 - It only contains characters allowed by the output of the 2199 iSCSI stringprep template (described in [RFC3722]). 2201 - The following characters are used for formatting iSCSI 2202 names: 2204 - dash ('-'=U+002d) 2205 - dot ('.'=U+002e) 2206 - colon (':'=U+003a) 2208 - The UTF-8 encoding of the name is not larger than 223 bytes. 2210 The stringprep process is described in [RFC3454]; iSCSI's use of 2211 the stringprep process is described in [RFC3722]. Stringprep is a 2212 method designed by the Internationalized Domain Name (IDN) working 2213 group to translate human-typed strings into a format that can be 2214 compared as opaque strings. iSCSI names are expected to be used by 2215 administrators for purposes such as system configuration - for 2216 this reason, characters that may lead to human confusion among 2217 different iSCSI names (e.g., punctuation, spacing, diacritical 2218 marks) should be avoided, even when such characters are allowed as 2219 stringprep processing output by [RFC3722]. The stringprep process 2220 also converts strings into equivalent strings of lower-case 2221 characters. 2223 The stringprep process does not need to be implemented if the 2224 names are generated using only characters allowed as output by the 2225 stringprep processing specified in [RFC3722]. Those allowed 2226 characters include all ASCII lowercase and numeric characters, as 2227 well as lowercase Unicode characters as specified in [RFC3722]. 2228 Once iSCSI names encoded in UTF-8 are "normalized" as described in 2229 this Section, they may be safely compared byte-for-byte. 2231 4.2.7.3. iSCSI Name Structure 2233 An iSCSI name consists of two parts--a type designator followed by 2234 a unique name string. 2236 iSCSI uses three existing naming authorities in constructing 2237 globally unique iSCSI names. Type designator in an iSCSI name 2238 indicates the naming authority on which the name is based. The 2239 three iSCSI name formats are the following: 2241 a) iSCSI-Qualified Name: it is based on domain names to 2242 identify a naming authority, 2243 b) NAA format Name: it is based on a naming format defined 2244 by [FC-FS3] for constructing globally unique identifiers, 2245 referred to as the Network Address Authority (NAA), and, 2246 c) EUI format Name: it is based on EUI names where the IEEE 2247 Registration Authority assists in the formation of 2248 worldwide unique names (EUI-64 format). 2250 The corresponding type designator strings currently defined are: 2252 a) iqn. - iSCSI Qualified name 2254 b) naa. - Remainder of the string is an INCITS T11-defined 2255 Network Address Authority identifier, in ASCII-encoded 2256 hexadecimal. 2258 c) eui. - Remainder of the string is an IEEE EUI-64 2259 identifier, in ASCII-encoded hexadecimal. 2261 These three naming authority designators were considered 2262 sufficient at the time of writing this document. The creation of 2263 additional naming type designators for iSCSI may be considered by 2264 the IETF and detailed in separate RFCs. 2266 The following table summarizes the current SCSI transport 2267 protocols and their naming formats. 2269 SCSI Transport Protocol Naming Format 2270 +----------------------------+-------+-----+----+ 2271 | | EUI-64| NAA |IQN | 2272 |----------------------------|-------|-----|----| 2273 | iSCSI (Internet SCSI) | X | X | X | 2274 |----------------------------|-------|-----|----| 2275 | FCP (Fibre Channel) | | X | | 2276 |----------------------------|-------|-----|----| 2277 | SAS (Serial Attached SCSI) | | X | | 2278 +----------------------------+-------+-----+----+ 2280 4.2.7.4. Type "iqn." (iSCSI Qualified Name) 2282 This iSCSI name type can be used by any organization that owns a 2283 domain name. This naming format is useful when an end user or 2284 service provider wishes to assign iSCSI names for targets and/or 2285 initiators. 2287 To generate names of this type, the person or organization 2288 generating the name must own a registered domain name. This domain 2289 name does not have to resolve to an address; it just needs to be 2290 reserved to prevent others from generating iSCSI names using the 2291 same domain name. 2293 Since a domain name can expire, be acquired by another entity, or 2294 may be used to generate iSCSI names by both owners, the domain 2295 name must be additionally qualified by a date during which the 2296 naming authority owned the domain name. A date code is provided as 2297 part of the "iqn." format for this reason. 2299 The iSCSI qualified name string consists of: 2301 - The string "iqn.", used to distinguish these names from 2302 "eui." formatted names. 2304 - A date code, in yyyy-mm format. This date MUST be a date 2305 during which the naming authority owned the domain name used 2306 in this format, and SHOULD be the first month in which the 2307 domain name was owned by this naming authority at 00:01 GMT 2308 of the first day of the month. This date code uses the 2309 Gregorian calendar. All four digits in the year must be 2310 present. Both digits of the month must be present, with 2311 January == "01" and December == "12". The dash must be 2312 included. 2314 - A dot "." 2316 - The reversed domain name of the naming authority (person or 2317 organization) creating this iSCSI name. 2319 - An optional, colon (:) prefixed, string within the character 2320 set and length boundaries that the owner of the domain name 2321 deems appropriate. This may contain product types, serial 2322 numbers, host identifiers, or software keys (e.g, it may 2323 include colons to separate organization boundaries). With 2324 the exception of the colon prefix, the owner of the domain 2325 name can assign everything after the reversed domain name as 2326 desired. It is the responsibility of the entity that is the 2327 naming authority to ensure that the iSCSI names it assigns 2328 are worldwide unique. For example, "Example Storage Arrays, 2329 Inc.", might own the domain name "example.com". 2331 The following are examples of iSCSI qualified names that might be 2332 generated by "EXAMPLE Storage Arrays, Inc." 2334 Naming String defined by 2335 Type Date Auth "example.com" naming authority 2336 +--++-----+ +---------+ +--------------------------------+ 2337 | || | | | | | 2339 iqn.2001-04.com.example:storage:diskarrays-sn-a8675309 2340 iqn.2001-04.com.example 2341 iqn.2001-04.com.example:storage.tape1.sys1.xyz 2342 iqn.2001-04.com.example:storage.disk2.sys1.xyz 2344 4.2.7.5. Type "eui." (IEEE EUI-64 format) 2346 The IEEE Registration Authority provides a service for assigning 2347 globally unique identifiers [EUI]. The EUI-64 format is used to 2348 build a global identifier in other network protocols. For example, 2349 Fibre Channel defines a method of encoding it into a 2350 WorldWideName. For more information on registering for EUI 2351 identifiers, see [OUI]. 2353 The format is "eui." followed by an EUI-64 identifier (16 ASCII- 2354 encoded hexadecimal digits). 2356 Example iSCSI name: 2358 Type EUI-64 identifier (ASCII-encoded hexadecimal) 2360 +--++--------------+ 2362 | || | 2364 eui.02004567A425678D 2366 The IEEE EUI-64 iSCSI name format might be used when a 2367 manufacturer is already registered with the IEEE Registration 2368 Authority and uses EUI-64 formatted worldwide unique names for its 2369 products. 2371 More examples of name construction are discussed in [RFC3721]. 2373 4.2.7.6. Type "naa." - Network Address Authority 2375 The INCITS T11 Framing and Signaling Specification [FC-FS3] 2376 defines a format called the Network Address Authority (NAA) format 2377 for constructing worldwide unique identifiers that use various 2378 identifier registration authorities. This identifier format is 2379 used by the Fibre Channel and SAS SCSI transport protocols. As FC 2380 and SAS constitute a large fraction of networked SCSI ports, the 2381 NAA format is a widely used format for SCSI transports. The 2382 objective behind iSCSI supporting a direct representation of an 2383 NAA-format name is to facilitate construction of a target device 2384 name that translates easily across multiple namespaces for a SCSI 2385 storage device containing ports served by different transports. 2386 More specifically, this format allows implementations wherein one 2387 NAA identifier can be assigned as the basis for the SCSI device 2388 name for a SCSI target with both SAS ports and iSCSI ports. 2390 The iSCSI NAA naming format is "naa.", followed by an NAA 2391 identifier represented in ASCII-encoded hexadecimal digits. 2393 An example of an iSCSI name with a 64-bit NAA value follows: 2395 Type NAA identifier (ASCII-encoded hexadecimal) 2396 +--++--------------+ 2397 | || | 2398 naa.52004567BA64678D 2400 An example of an iSCSI name with a 128-bit NAA value follows: 2402 Type NAA identifier (ASCII-encoded hexadecimal) 2403 +--++------------------------------+ 2404 | || | 2405 naa.62004567BA64678D0123456789ABCDEF 2407 The iSCSI NAA naming format might be used in an implementation 2408 when the infrastructure for generating NAA worldwide unique names 2409 is already in place because the device contains both SAS and iSCSI 2410 SCSI ports. 2412 The NAA identifier formatted in an ASCII-hexadecimal 2413 representation has a maximum size of 32 characters (128 bit NAA 2414 format). As a result, there is no issue with this naming format 2415 exceeding the maximum size for iSCSI node names. 2417 4.2.8. Persistent State 2419 iSCSI does not require any persistent state maintenance across 2420 sessions. However, in some cases, SCSI requires persistent 2421 identification of the SCSI initiator port name (See Section 4.4.2 2422 and Section 4.4.3). 2424 iSCSI sessions do not persist through power cycles and boot 2425 operations. 2427 All iSCSI session and connection parameters are re-initialized on 2428 session and connection creation. 2430 Commands persist beyond connection termination if the session 2431 persists and command recovery within the session is supported. 2432 However, when a connection is dropped, command execution, as 2433 perceived by iSCSI (i.e., involving iSCSI protocol exchanges for 2434 the affected task), is suspended until a new allegiance is 2435 established by the 'task reassign' task management function. (See 2436 Section 11.5.) 2438 4.2.9. Message Synchronization and Steering 2440 iSCSI presents a mapping of the SCSI protocol onto TCP. This 2441 encapsulation is accomplished by sending iSCSI PDUs of varying 2442 lengths. Unfortunately, TCP does not have a built-in mechanism for 2443 signaling message boundaries at the TCP layer. iSCSI overcomes 2444 this obstacle by placing the message length in the iSCSI message 2445 header. This serves to delineate the end of the current message as 2446 well as the beginning of the next message. 2448 In situations where IP packets are delivered in order from the 2449 network, iSCSI message framing is not an issue and messages are 2450 processed one after the other. In the presence of IP packet 2451 reordering (i.e., frames being dropped), legacy TCP 2452 implementations store the "out of order" TCP segments in temporary 2453 buffers until the missing TCP segments arrive, upon which the data 2454 must be copied to the application buffers. In iSCSI, it is 2455 desirable to steer the SCSI data within these out of order TCP 2456 segments into the pre-allocated SCSI buffers rather than store 2457 them in temporary buffers. This decreases the need for dedicated 2458 reassembly buffers as well as the latency and bandwidth related to 2459 extra copies. 2461 Relying solely on the "message length" information from the iSCSI 2462 message header may make it impossible to find iSCSI message 2463 boundaries in subsequent TCP segments due to the loss of a TCP 2464 segment that contains the iSCSI message length. The missing TCP 2465 segment(s) must be received before any of the following segments 2466 can be steered to the correct SCSI buffers (due to the inability 2467 to determine the iSCSI message boundaries). Since these segments 2468 cannot be steered to the correct location, they must be saved in 2469 temporary buffers that must then be copied to the SCSI buffers. 2471 Different schemes can be used to recover synchronization. The 2472 details of any such schemes are beyond this protocol 2473 specification, but it suffices to note that [RFC4297] provides an 2474 overview of the direct data placement problem on IP networks, and 2475 [RFC5046] specifies a protocol extension for iSCSI that 2476 facilitates this direct data placement objective. Rest of this 2477 document refers to any such direct data placement protocol usage 2478 as an example of a "Synch and Steering layer". 2480 Under normal circumstances (no PDU loss or data reception out of 2481 order), iSCSI data steering can be accomplished by using the 2482 identifying tag and the data offset fields in the iSCSI header in 2483 addition to the TCP sequence number from the TCP header. The 2484 identifying tag helps associate the PDU with a SCSI buffer address 2485 while the data offset and TCP sequence number are used to 2486 determine the offset within the buffer. 2488 4.2.9.1. Sync/Steering and iSCSI PDU Length 2490 When a large iSCSI message is sent, the TCP segment(s) that 2491 contain the iSCSI header may be lost. The remaining TCP segment(s) 2492 up to the next iSCSI message must be buffered (in temporary 2493 buffers) because the iSCSI header that indicates to which SCSI 2494 buffers the data are to be steered was lost. To minimize the 2495 amount of buffering, it is recommended that the iSCSI PDU length 2496 be restricted to a small value (perhaps a few TCP segments in 2497 length). During login, each end of the iSCSI session specifies the 2498 maximum iSCSI PDU length it will accept. 2500 4.3. iSCSI Session Types 2502 iSCSI defines two types of sessions: 2504 a) Normal operational session - an unrestricted session. 2506 b) Discovery-session - a session only opened for target 2507 discovery. The target MUST ONLY accept text requests with 2508 the SendTargets key and a logout request with reason 2509 "close the session". All other requests MUST be rejected. 2511 The session type is defined during login with SessionType=value 2512 parameter in the login command. 2514 4.4. SCSI to iSCSI Concepts Mapping Model 2516 The following diagram shows an example of how multiple iSCSI Nodes 2517 (targets in this case) can coexist within the same Network Entity 2518 and can share Network Portals (IP addresses and TCP ports). Other 2519 more complex configurations are also possible. For detailed 2520 descriptions of the components of these diagrams, see Section 2521 4.4.1. 2523 +-----------------------------------+ 2524 | Network Entity (iSCSI Client) | 2525 | | 2526 | +-------------+ | 2527 | | iSCSI Node | | 2528 | | (Initiator) | | 2529 | +-------------+ | 2530 | | | | 2531 | +--------------+ +--------------+ | 2532 | |Network Portal| |Network Portal| | 2533 | | 192.0.2.4 | | 192.0.2.5 | | 2534 +-+--------------+-+--------------+-+ 2535 | | 2536 | IP Networks | 2537 | | 2538 +-+--------------+-+--------------+-+ 2539 | |Network Portal| |Network Portal| | 2540 | |198.51.100.21 | |198.51.100.3 | | 2541 | | TCP Port 3260| | TCP Port 3260| | 2542 | +--------------+ +--------------+ | 2543 | | | | 2544 | ----------------- | 2545 | | | | 2546 | +-------------+ +--------------+ | 2547 | | iSCSI Node | | iSCSI Node | | 2548 | | (Target) | | (Target) | | 2549 | +-------------+ +--------------+ | 2550 | | 2551 | Network Entity (iSCSI Server) | 2552 +-----------------------------------+ 2554 4.4.1. iSCSI Architecture Model 2556 This Section describes the part of the iSCSI architecture model 2557 that has the most bearing on the relationship between iSCSI and 2558 the SCSI Architecture Model. 2560 - Network Entity - represents a device or gateway that is 2561 accessible from the IP network. A Network Entity must have 2562 one or more Network Portals (see a following item), each of 2563 which can be used by some iSCSI Nodes (see the following 2564 item) contained in that Network Entity to gain access to the 2566 IP network. 2568 - iSCSI Node - represents a single iSCSI initiator or iSCSI 2569 target or an instance of each. There are one or more iSCSI 2570 Nodes within a Network Entity. The iSCSI Node is accessible 2571 via one or more Network Portals (see item d). An iSCSI Node 2572 is identified by its iSCSI Name (see Section 4.2.7 and 2573 Section 13). The separation of the iSCSI Name from the 2574 addresses used by and for the iSCSI node allows multiple 2575 iSCSI nodes to use the same addresses, and the same iSCSI 2576 node to use multiple addresses. 2578 - An alias string may also be associated with an iSCSI Node. 2579 The alias allows an organization to associate a user 2580 friendly string with the iSCSI Name. However, the alias 2581 string is not a substitute for the iSCSI Name. 2583 - Network Portal - a component of a Network Entity that has a 2584 TCP/IP network address and that may be used by an iSCSI Node 2585 within that Network Entity for the connection(s) within one 2586 of its iSCSI sessions. In an initiator, it is identified by 2587 its IP address. In a target, it is identified by its IP 2588 address and its listening TCP port. 2590 - Portal Groups - iSCSI supports multiple connections within 2591 the same session; some implementations will have the ability 2592 to combine connections in a session across multiple Network 2593 Portals. A Portal Group defines a set of Network Portals 2594 within an iSCSI Node that collectively supports the 2595 capability of coordinating a session with connections that 2596 span these portals. Not all Network Portals within a Portal 2597 Group need to participate in every session connected through 2598 that Portal Group. One or more Portal Groups may provide 2599 access to an iSCSI Node. Each Network Portal, as utilized by 2600 a given iSCSI Node, belongs to exactly one portal group 2601 within that node. Portal Groups are identified within an 2602 iSCSI Node by a portal group tag, a simple unsigned-integer 2603 between 0 and 65535 (see Section 13.3). All Network Portals 2604 with the same portal group tag in the context of a given 2605 iSCSI Node are in the same Portal Group. 2607 Both iSCSI Initiators and iSCSI Targets have portal groups, 2608 though only the iSCSI Target Portal Groups are used directly 2609 in the iSCSI protocol (e.g., in SendTargets). For references 2610 to the Initiator Portal Groups, see Section 10.1.1. 2612 - Portals within a Portal Group should support similar session 2613 parameters, because they may participate in a common 2614 session. 2616 The following diagram shows an example of one such configuration 2617 on a target and how a session that shares Network Portals within a 2618 Portal Group may be established. 2620 ----------------------------IP Network--------------------- 2621 | | | 2622 +----|----------------|----+ +----|---------+ 2623 | +---------+ +---------+ | | +---------+ | 2624 | | Network | | Network | | | | Network | | 2625 | | Portal | | Portal | | | | Portal | | 2626 | +--|------+ +---------+ | | +---------+ | 2627 | | | | | | | 2628 | | Portal | | | | Portal | 2629 | | Group 1 | | | | Group 2 | 2630 +--------------------------+ +--------------+ 2631 | | | 2632 +--------|----------------|------------------|------------------+ 2633 | | | | | 2634 | +----------------------------+ +----------------------------+ | 2635 | | iSCSI Session (Target side)| | iSCSI Session (Target side)| | 2636 | | | | | | 2637 | | (TSIH = 56) | | (TSIH = 48) | | 2638 | +----------------------------+ +----------------------------+ | 2639 | | 2640 | iSCSI Target Node | 2641 | (within Network Entity, not shown) | 2642 +---------------------------------------------------------------+ 2644 4.4.2. SCSI Architecture Model 2646 This Section describes the relationship between the SCSI 2647 Architecture Model [SAM2] and constructs of the SCSI device, SCSI 2648 port and I_T nexus, and the iSCSI constructs described in Section 2649 4.4.1. 2651 This relationship implies implementation requirements in order to 2652 conform to the SAM2 model and other SCSI operational functions. 2653 These requirements are detailed in Section 4.4.3. 2655 The following list outlines mappings of SCSI architectural 2656 elements to iSCSI. 2658 a) SCSI Device - the SAM2 term for an entity that contains 2659 one or more SCSI ports that are connected to a service 2660 delivery subsystem and supports a SCSI application 2661 protocol. For example, a SCSI Initiator Device contains 2662 one or more SCSI Initiator Ports and zero or more 2663 application clients. A SCSI Target Device contains one or 2664 more SCSI Target Ports and one or more logical units. For 2665 iSCSI, the SCSI Device is the component within an iSCSI 2666 Node that provides the SCSI functionality. As such, there 2667 can be one SCSI Device, at most, within an iSCSI Node. 2668 Access to the SCSI Device can only be achieved in an 2669 iSCSI normal operational session (see Section 4.3). The 2670 SCSI Device Name is defined to be the iSCSI Name of the 2671 node and MUST be used in the iSCSI protocol. 2673 b) SCSI Port - the SAM2 term for an entity in a SCSI Device 2674 that provides the SCSI functionality to interface with a 2675 service delivery subsystem or transport. For iSCSI, the 2676 definition of SCSI Initiator Port and SCSI Target Port 2677 are different. 2679 SCSI Initiator Port: This maps to one endpoint of an 2680 iSCSI normal operational session (see Section 4.3). An 2681 iSCSI normal operational session is negotiated through 2682 the login process between an iSCSI initiator node and an 2683 iSCSI target node. At successful completion of this 2684 process, a SCSI Initiator Port is created within the SCSI 2685 Initiator Device. The SCSI Initiator Port Name and SCSI 2686 Initiator Port Identifier are both defined to be the 2687 iSCSI Initiator Name together with (a) a label that 2688 identifies it as an initiator port name/identifier and 2689 (b) the ISID portion of the session identifier. 2691 SCSI Target Port: This maps to an iSCSI Target Portal 2692 Group. The SCSI Target Port Name and the SCSI Target Port 2693 Identifier are both defined to be the iSCSI Target Name 2694 together with (a) a label that identifies it as a target 2695 port name/identifier and (b) the portal group tag. 2697 The SCSI Port Name MUST be used in iSCSI. When used in 2698 SCSI parameter data, the SCSI port name MUST be encoded 2699 as: 2700 1. The iSCSI Name in UTF-8 format, followed by 2701 2. a comma separator (1 byte), followed by 2702 3. the ASCII character 'i' (for SCSI Initiator Port) 2703 or the ASCII character 't' (for SCSI Target Port) 2704 (1 byte), followed by 2705 4. a comma separator (1 byte), followed by 2706 5. a text encoding as a hex-constant (see Section 6.1) 2707 of the ISID (for SCSI initiator port) or the 2708 portal group tag (for SCSI target port) including 2709 the initial 0X or 0x and the terminating null (14 2710 bytes). 2712 The ASCII character 'i' or 't' is the label that 2713 identifies this port as either a SCSI Initiator 2714 Port or a SCSI Target Port. 2716 c) I_T nexus - a relationship between a SCSI Initiator Port 2717 and a SCSI Target Port, according to [SAM2]. For iSCSI, 2718 this relationship is a session, defined as a relationship 2719 between an iSCSI Initiator's end of the session (SCSI 2720 Initiator Port) and the iSCSI Target's Portal Group. The 2721 I_T nexus can be identified by the conjunction of the 2722 SCSI port names or by the iSCSI session identifier SSID. 2723 iSCSI defines the I_T nexus identifier to be the tuple 2724 (iSCSI Initiator Name + ",i,0x" + ISID in text format, 2725 iSCSI Target Name + ",t,0x" + Portal Group Tag in text 2726 format) - an upper case hex prefix "0X" may alternatively 2727 be used in place of "0x". 2729 NOTE: The I_T nexus identifier is not equal to the 2730 session identifier (SSID). 2732 4.4.3. Consequences of the Model 2734 This Section describes implementation and behavioral requirements 2735 that result from the mapping of SCSI constructs to the iSCSI 2736 constructs defined above. Between a given SCSI initiator port and 2737 a given SCSI target port, only one I_T nexus (session) can exist. 2738 No more than one nexus relationship (parallel nexus) is allowed by 2739 [SAM2]. Therefore, at any given time, only one session with the 2740 same session identifier (SSID) can exist between a given iSCSI 2741 initiator node and an iSCSI target node. 2743 These assumptions lead to the following conclusions and 2744 requirements: 2746 ISID RULE: Between a given iSCSI Initiator and iSCSI Target Portal 2747 Group (SCSI target port), there can only be one session with a 2748 given value for ISID that identifies the SCSI initiator port. See 2749 Section 11.12.5. 2751 The structure of the ISID that contains a naming authority 2752 component (see Section 11.12.5 and [RFC3721]) provides a mechanism 2753 to facilitate compliance with the ISID rule. (See Section 10.1.1) 2755 The iSCSI Initiator Node should manage the assignment of ISIDs 2756 prior to session initiation. The "ISID RULE" does not preclude the 2757 use of the same ISID from the same iSCSI Initiator with different 2758 Target Portal Groups on the same iSCSI target or on other iSCSI 2759 targets (see Section 10.1.1). Allowing this would be analogous to 2760 a single SCSI Initiator Port having relationships (nexus) with 2761 multiple SCSI target ports on the same SCSI target device or SCSI 2762 target ports on other SCSI target devices. It is also possible to 2763 have multiple sessions with different ISIDs to the same Target 2764 Portal Group. Each such session would be considered to be with a 2765 different initiator even when the sessions originate from the same 2766 initiator device. The same ISID may be used by a different iSCSI 2767 initiator because it is the iSCSI Name together with the ISID that 2768 identifies the SCSI Initiator Port. 2770 NOTE: A consequence of the ISID RULE and the specification for the 2771 I_T nexus identifier is that two nexus with the same identifier 2772 should never exist at the same time. 2774 TSIH RULE: The iSCSI Target selects a non-zero value for the TSIH 2775 at session creation (when an initiator presents a 0 value at 2776 Login). After being selected, the same TSIH value MUST be used 2777 whenever initiator or target refers to the session and a TSIH is 2778 required. 2780 4.4.3.1. I_T Nexus State 2782 Certain nexus relationships contain an explicit state (e.g., 2783 initiator-specific mode pages) that may need to be preserved by 2784 the device server [SAM2] in a logical unit through changes or 2785 failures in the iSCSI layer (e.g., session failures). In order for 2786 that state to be restored, the iSCSI initiator should reestablish 2787 its session (re-login) to the same Target Portal Group using the 2788 previous ISID. That is, it should reinstate the session via iSCSI 2789 session reinstatement (Section 6.3.5) or continue via session 2790 continuation (Section 6.3.6). This is because the SCSI initiator 2791 port identifier and the SCSI target port identifier (or relative 2792 target port) form the datum that the SCSI logical unit device 2793 server uses to identify the I_T nexus. 2795 4.4.3.2. Reservations 2797 There are two reservation management methods defined in the SCSI 2798 standards, reserve/release reservations, based on the RESERVE and 2799 RELEASE commands [SPC2], and persistent reservations, based on the 2800 PERSISTENT RESERVE IN and PERSISTENT RESERVE OUT commands [SPC3]. 2801 Reserve/release reservations are obsolete [SPC3] and should not be 2802 used; persistent reservations are suggested as an alternative, see 2803 Annex B of [SPC4]. 2805 State for persistent reservations is required to persist through 2806 changes and failures at the iSCSI layer that result in I_T nexus 2807 failures, see [SPC3] for details and specific requirements. 2809 In contrast, [SPC2] does not specify detailed persistence 2810 requirements for reserve/release reservation state after an I_T 2811 nexus failure. Nonetheless, when reserve/release reservations are 2812 supported by an iSCSI target, the preferred implementation 2813 approach is to preserve reserve/release reservation state for 2814 iSCSI session reinstatement (see Section 6.3.5) or session 2815 continuation (see Section 6.3.6). 2817 Two additional caveats apply to reserve/release reservations: 2819 - Retention of a failed session's reserve/release reservation 2820 state by an iSCSI target, even after that failed iSCSI 2821 session is not reinstated or continued, may require an 2822 initiator to issue a reset (e.g., LOGICAL UNIT RESET, see 2823 Section 11.5) in order to remove that reservation state. 2825 - Reserve/release reservations may not behave as expected when 2826 persistent reservations are also used on the same logical 2827 unit; see the discussion of "Exceptions to SPC-2 RESERVE and 2828 RELEASE behavior" in [SPC4]. 2830 4.5. iSCSI UML Model 2832 This Section presents the application of the UML modeling concepts 2833 discussed in Section 3 to the iSCSI and SCSI architecture model 2834 discussed in Section 4.4. 2836 +----------------+ 2837 | Network Entity | 2838 +----------------+ 2839 @ 1 @ 1 2840 | | 2841 +--------------------+ | 2842 | | 2843 | | 0..* 2844 | +------------------+ 2845 | | iSCSI Node | 2846 | +------------------+ 2847 | @ @ 2848 | | | 2849 | +-----------+ =(a)= +-----------+ 2850 | | | 2851 | | 0..1 | 0..1 2852 | +------------------------+ +----------------------+ 2853 | | iSCSI Target Node | | iSCSI Initiator Node | 2854 | +------------------------+ +----------------------+ 2855 | @ 1 @ 1 2856 | +--------------+ | 2857 | 1..* | | 1..* 2858 | +-----------------------------+ 2859 | | Portal Group | 2860 | +-----------------------------+ 2861 | O 1 2862 | | 2863 | | 1..* 2864 | 1..* +------------------------+ 2865 +--------------------| Network Portal | 2866 +------------------------+ 2868 (a) Each instance of an iSCSI Node class MUST contain one iSCSI 2869 Target Node instance or one iSCSI Initiator Node instance, or 2870 both. 2872 +----------------+ 2873 | Network Entity | 2874 +----------------+ 2875 @ 1 @ 1 2876 | | +-------------------+ 2877 +---------------------+ | | iSCSI Session | 2878 | | +-------------------+ 2879 | | 0..* | SSID[1] | 2880 | +--------------------+ | ISID[1] | 2881 | | iSCSI Node | +-------------------+ 2882 | +--------------------+ @ 1 2883 | | iSCSI Node Name[1] | | 2884 | | Alias [0..1] | | 0..* 2885 | +--------------------+ +------------------+ 2886 | | | | iSCSI Connection | 2887 | +--------------------+ +------------------+ 2888 | @ 1 @ 1 | CID[1] | 2889 | | | +------------------+ 2890 | +-------------+ ==(b)== +----------+ 0..* | 2891 | | 1 | 1 | 2892 | +------------------------+ +------------------------+ | 2893 | | iSCSI Target Node | | iSCSI Initiator Node | | 2894 | +------------------------+ +------------------------+ | 2895 | | iSCSI Target name [1] | |iSCSI Initiator Name [1]| | 2896 | +------------------------+ +------------------------+ | 2897 | @ 1 @ 1 | 2898 | | 1..* | 1..* | 2899 | +--------------------------+ +------------------------+ | 2900 | | Target Portal Group | | Initiator Portal Group | | 2901 | +--------------------------+ +------------------------+ | 2902 | |Target Portal Group Tag[1]| | Portal group tag[1] | | 2903 | +--------------------------+ +------------------------+ | 2904 | o 1 o 1 | 2905 | +------------+ +---------+ | 2906 | 1..* | | 1..* | 2907 | +-------------------------+ | 2908 | | Network Portal | | 2909 | +-------------------------+ | 2910 | 1..* | IP Address [1] | 1 | 2911 +----------------| TCP Port [0..1] |<----------------------+ 2912 +-------------------------+ 2914 (b) Each instance of an iSCSI Node class MUST contain one iSCSI 2915 Target Node instance or one iSCSI Initiator Node instance, or 2916 both. However, in all scenarios, note that an iSCSI Node MUST 2917 only have a single iSCSI Name. Note the related requirement in 2918 Section 4.2.7.1. 2920 4.6. Request/Response Summary 2922 This Section lists and briefly describes all the iSCSI PDU types 2923 (request and responses). 2925 All iSCSI PDUs are built as a set of one or more header segments 2926 (basic and auxiliary) and zero or one data segments. The header 2927 group and the data segment may each be followed by a CRC (digest) 2928 (see [CRC]). 2930 The basic header segment has a fixed length of 48 bytes. 2932 4.6.1. Request/Response Types Carrying SCSI Payload 2934 4.6.1.1. SCSI-Command 2936 This request carries the SCSI CDB and all the other SCSI execute 2937 command procedure call (see [SAM2]) IN arguments such as task 2938 attributes, Expected Data Transfer Length for one or both transfer 2939 directions (the latter for bidirectional commands), and Task Tag 2940 (as part of the I_T_L_x nexus). The I_T_L nexus is derived by the 2941 initiator and target from the LUN field in the request and the I_T 2942 nexus is implicit in the session identification. 2944 In addition, the SCSI-command PDU carries information required for 2945 the proper operation of the iSCSI protocol - the command sequence 2946 number (CmdSN) and the expected status number (ExpStatSN) on the 2947 connection it is issued. 2949 All or part of the SCSI output (write) data associated with the 2950 SCSI command may be sent as part of the SCSI-Command PDU as a data 2951 segment. 2953 4.6.1.2. SCSI-Response 2955 The SCSI-Response carries all the SCSI execute-command procedure 2956 call (see [SAM2]) OUT arguments and the SCSI execute-command 2957 procedure call return value. 2959 The SCSI-Response contains the residual counts from the operation, 2960 if any, an indication of whether the counts represent an overflow 2961 or an underflow, and the SCSI status if the status is valid or a 2962 response code (a non-zero return value for the execute-command 2963 procedure call) if the status is not valid. 2965 For a valid status that indicates that the command has been 2966 processed, but resulted in an exception (e.g., a SCSI CHECK 2967 CONDITION), the PDU data segment contains the associated sense 2968 data. The use of Autosense ([SAM2]) is REQUIRED by iSCSI. 2970 Some data segment content may also be associated (in the data 2971 segment) with a non-zero response code. 2973 In addition, the SCSI-Response PDU carries information required 2974 for the proper operation of the iSCSI protocol: 2976 - The number of Data-In PDUs that a target has sent (to enable 2977 the initiator to check that all have arrived). 2979 - StatSN - the Status Sequence Number on this connection. 2981 - ExpCmdSN - the next Expected Command Sequence Number at the 2982 target. 2984 - MaxCmdSN - the maximum CmdSN acceptable at the target from 2985 this initiator. 2987 4.6.1.3. Task Management Function Request 2989 The Task Management function request provides an initiator with a 2990 way to explicitly control the execution of one or more SCSI Tasks 2991 or iSCSI functions. The PDU carries a function identifier (which 2992 task management function to perform) and enough information to 2993 unequivocally identify the task or task-set on which to perform 2994 the action, even if the task(s) to act upon has not yet arrived or 2995 has been discarded due to an error. 2997 The referenced tag identifies an individual task if the function 2998 refers to an individual task. 3000 The I_T_L nexus identifies task sets. In iSCSI the I_T_L nexus is 3001 identified by the LUN and the session identification (the session 3002 identifies an I_T nexus). 3004 For task sets, the CmdSN of the Task Management function request 3005 helps identify the tasks upon which to act, namely all tasks 3006 associated with a LUN and having a CmdSN preceding the Task 3007 Management function request CmdSN. 3009 For a Task Management function, the coordination between responses 3010 to the tasks affected and the Task Management function response is 3011 done by the target. 3013 4.6.1.4. Task Management Function Response 3015 The Task Management function response carries an indication of 3016 function completion for a Task Management function request 3017 including how it completed (response and qualifier) and additional 3018 information for failure responses. 3020 After the Task Management response indicates Task Management 3021 function completion, the initiator will not receive any additional 3022 responses from the affected tasks. 3024 4.6.1.5. SCSI Data-out and SCSI Data-in 3026 SCSI Data-out and SCSI Data-in are the main vehicles by which SCSI 3027 data payload is carried between initiator and target. Data payload 3028 is associated with a specific SCSI command through the Initiator 3029 Task Tag. For target convenience, outgoing solicited data also 3030 carries a Target Transfer Tag (copied from R2T) and the LUN. Each 3031 PDU contains the payload length and the data offset relative to 3032 the buffer address contained in the SCSI execute command procedure 3033 call. 3035 In each direction, the data transfer is split into "sequences". An 3036 end-of-sequence is indicated by the F bit. 3038 An outgoing sequence is either unsolicited (only the first 3039 sequence can be unsolicited) or consists of all the Data-Out PDUs 3040 sent in response to an R2T. 3042 Input sequences enable the switching of direction for 3043 bidirectional commands as required. 3045 For input, the target may request positive acknowledgement of 3046 input data. This is limited to sessions that support error 3047 recovery and is implemented through the A bit in the SCSI Data-in 3048 PDU header. 3050 Data-in and Data-out PDUs also carry the DataSN to enable the 3051 initiator and target to detect missing PDUs (discarded due to an 3052 error). 3054 In addition, StatSN is carried by the Data-In PDUs. 3056 To enable a SCSI command to be processed while involving a minimum 3057 number of messages, the last SCSI Data-in PDU passed for a command 3058 may also contain the status if the status indicates termination 3059 with no exceptions (no sense or response involved). 3061 4.6.1.6. Ready To Transfer (R2T) 3063 R2T is the mechanism by which the SCSI target "requests" the 3064 initiator for output data. R2T specifies to the initiator the 3065 offset of the requested data relative to the buffer address from 3066 the execute command procedure call and the length of the solicited 3067 data. 3069 To help the SCSI target associate the resulting Data-out with an 3070 R2T, the R2T carries a Target Transfer Tag that will be copied by 3071 the initiator in the solicited SCSI Data-out PDUs. There are no 3072 protocol specific requirements with regard to the value of these 3073 tags, but it is assumed that together with the LUN, they will 3074 enable the target to associate data with an R2T. 3076 R2T also carries information required for proper operation of the 3077 iSCSI protocol, such as: 3079 - R2TSN (to enable an initiator to detect a missing R2T) 3081 - StatSN 3083 - ExpCmdSN 3085 - MaxCmdSN 3087 4.6.2. Requests/Responses carrying SCSI and iSCSI Payload 3089 4.6.2.1. Asynchronous Message 3091 Asynchronous Messages are used to carry SCSI asynchronous events 3092 (AEN) and iSCSI asynchronous messages. 3094 When carrying an AEN, the event details are reported as sense data 3095 in the data segment. 3097 4.6.3. Requests/Responses Carrying iSCSI Only Payload 3099 4.6.3.1. Text Request and Text Response 3101 Text requests and responses are designed as a parameter 3102 negotiation vehicle and as a vehicle for future extension. 3104 In the data segment Text Requests/Responses carry text information 3105 using a simple "key=value" syntax. 3107 Text Request/Responses may form extended sequences using the same 3108 Initiator Task Tag. The initiator uses the F (Final) flag bit in 3109 the text request header to indicate its readiness to terminate a 3110 sequence. The target uses the F (Final) flag bit in the text 3111 response header to indicate its consent to sequence termination. 3113 Text Request and Responses also use the Target Transfer Tag to 3114 indicate continuation of an operation or a new beginning. A target 3115 that wishes to continue an operation will set the Target Transfer 3116 Tag in a Text Response to a value different from the default 3117 0xffffffff. An initiator willing to continue will copy this value 3118 into the Target Transfer Tag of the next Text Request. If the 3119 initiator wants to restart the current target negotiation (start 3120 fresh) will set the Target Transfer Tag to 0xffffffff. 3122 Although a complete exchange is always started by the initiator, 3123 specific parameter negotiations may be initiated by the initiator 3124 or target. 3126 4.6.3.2. Login Request and Login Response 3128 Login Requests and Responses are used exclusively during the Login 3129 Phase of each connection to set up the session and connection 3130 parameters. (The Login Phase consists of a sequence of login 3131 requests and responses carrying the same Initiator Task Tag.) 3133 A connection is identified by an arbitrarily selected connection- 3134 ID (CID) that is unique within a session. 3136 Similar to the Text Requests and Responses, Login 3137 Requests/Responses carry key=value text information with a simple 3138 syntax in the data segment. 3140 The Login Phase proceeds through several stages (security 3141 negotiation, operational parameter negotiation) that are selected 3142 with two binary coded fields in the header -- the "current stage" 3143 (CSG) and the "next stage" (NSG) with the appearance of the latter 3144 being signaled by the "transit" flag (T). 3146 The first Login Phase of a session plays a special role, called 3147 the leading login, which determines some header fields (e.g., the 3148 version number, the maximum number of connections, and the session 3149 identification). 3151 The CmdSN initial value is also set by the leading login. 3153 StatSN for each connection is initiated by the connection login. 3155 A login request may indicate an implied logout (cleanup) of the 3156 connection to be logged in (a connection restart) by using the 3157 same Connection ID (CID) as an existing connection as well as the 3158 same session identifying elements of the session to which the old 3159 connection was associated. 3161 4.6.3.3. Logout Request and Response 3163 Logout Requests and Responses are used for the orderly closing of 3164 connections for recovery or maintenance. The logout request may be 3165 issued following a target prompt (through an asynchronous message) 3166 or at an initiators initiative. When issued on the connection to 3167 be logged out no other request may follow it. 3169 The Logout response indicates that the connection or session 3170 cleanup is completed and no other responses will arrive on the 3171 connection (if received on the logging out connection). In 3172 addition, the Logout Response indicates how long the target will 3173 continue to hold resources for recovery (e.g., command execution 3174 that continues on a new connection) in the Time2Retain field and 3175 how long the initiator must wait before proceeding with recovery 3176 in the Time2Wait field. 3178 4.6.3.4. SNACK Request 3180 With the SNACK Request, the initiator requests retransmission of 3181 numbered-responses or data from the target. A single SNACK request 3182 covers a contiguous set of missing items, called a run, of a given 3183 type of items. The type is indicated in a type field in the PDU 3184 header. The run is composed of an initial item (StatSN, DataSN, 3185 R2TSN) and the number of missed Status, Data, or R2T PDUs. For 3186 long data-in sequences, the target may request (at predefined 3187 minimum intervals) a positive acknowledgement for the data sent. A 3188 SNACK request with a type field that indicates ACK and the number 3189 of Data-In PDUs acknowledged conveys this positive 3190 acknowledgement. 3192 4.6.3.5. Reject 3194 Reject enables the target to report an iSCSI error condition 3195 (e.g., protocol, unsupported option) that uses a Reason field in 3196 the PDU header and includes the complete header of the bad PDU in 3197 the Reject PDU data segment. 3199 4.6.3.6. NOP-Out Request and NOP-In Response 3201 This request/response pair may be used by an initiator and target 3202 as a "ping" mechanism to verify that a connection/session is still 3203 active and all of its components are operational. Such a ping may 3204 be triggered by the initiator or target. The triggering party 3205 indicates that it wants a reply by setting a value different from 3206 the default 0xffffffff in the corresponding Initiator/Target 3207 Transfer Tag. 3209 NOP-In/NOP-Out may also be used "unidirectional" to convey to the 3210 initiator/target command, status or data counter values when there 3211 is no other "carrier" and there is a need to update the 3212 initiator/target. 3214 5. SCSI Mode Parameters for iSCSI 3216 There are no iSCSI specific mode pages. 3218 6. Login and Full Feature Phase Negotiation 3220 iSCSI parameters are negotiated at session or connection 3221 establishment by using Login Requests and Responses (see Section 3222 4.2.4) and during Full Feature Phase (Section 4.2.5) by using Text 3223 Requests and Responses. In both cases the mechanism used is an 3224 exchange of iSCSI-text-key=value pairs. For brevity, iSCSI-text- 3225 keys are called just keys in the rest of this document. 3227 Keys are either declarative or require negotiation and the key 3228 description indicates if the key is declarative or requires 3229 negotiation. 3231 For the declarative keys the declaring party sets a value for the 3232 key. The key specification indicates if the key can be declared by 3233 the initiator, target or both. 3235 For the keys that require negotiation, one of the parties (the 3236 proposing party) proposes a value or set of values by including 3237 the key=value in the data part of a Login or Text Request or 3238 Response. The other party (the accepting party) makes a selection 3239 based on the value or list of values proposed and includes the 3240 selected value in a key=value in the data part of the following 3241 Login or Text Response or Request. For most of the keys, both the 3242 initiator and target can be proposing parties. 3244 The login process proceeds in two stages - the security 3245 negotiation stage and the operational parameter negotiation stage. 3246 Both stages are optional but at least one of them has to be 3247 present to enable setting some mandatory parameters. 3249 If present, the security negotiation stage precedes the 3250 operational parameter negotiation stage. 3252 Progression from stage to stage is controlled by the T 3253 (Transition) bit in the Login Request/Response PDU header. Through 3254 the T bit set to 1, the initiator indicates that it would like to 3255 transition. The target agrees to the transition (and selects the 3256 next stage) when ready. A field in the Login PDU header indicates 3257 the current stage (CSG) and during transition, another field 3258 indicates the next stage (NSG) proposed (initiator) and selected 3259 (target). 3261 The Text negotiation process is used to negotiate or declare 3262 operational parameters. The negotiation process is controlled by 3263 the F (final) bit in the PDU header. During text negotiations, the 3264 F bit is used by the initiator to indicate that it is ready to 3265 finish the negotiation and by the Target to acquiesce the end of 3266 negotiation. 3268 Since some key=value pairs may not fit entirely in a single PDU, 3269 the C (continuation) bit is used (both in Login and Text) to 3270 indicate that "more follows". 3272 The text negotiation uses an additional mechanism by which a 3273 target may deliver larger amounts of data to an enquiring 3274 initiator. The target sets a Target Task Tag to be used as a 3275 bookmark which when returned by the initiator, means "go on". If 3276 reset to a "neutral value", it means "forget about the rest". 3278 This Section details types of keys and values used, the syntax 3279 rules for parameter formation, and the negotiation schemes to be 3280 used with different types of parameters. 3282 6.1. Text Format 3284 The initiator and target send a set of key=value pairs encoded in 3285 UTF-8 Unicode. All the text keys and text values specified in this 3286 document are to be presented and interpreted in the case in which 3287 they appear in this document. They are case sensitive. 3289 The following character symbols are used in this document for text 3290 items (the hexadecimal values represent Unicode code points): 3292 (a-z, A-Z) ) (0x61-0x7a, 0x41-0x5a) - letters 3293 (0-9) (0x30-0x39) - digits 3294 " " (0x20) - space 3295 "." (0x2e) - dot 3296 "-" (0x2d) - minus 3297 "+" (0x2b) - plus 3298 "@" (0x40) - commercial at 3299 "_" (0x5f) - underscore 3300 "=" (0x3d) - equal 3301 ":" (0x3a) - colon 3303 "/" (0x2f) - solidus or slash 3304 "[" (0x5b) - left bracket 3305 "]" (0x5d) - right bracket 3306 null (0x00) - null separator 3307 "," (0x2c) - comma 3308 "~" (0x7e) - tilde 3310 Key=value pairs may span PDU boundaries. An initiator or target 3311 that sends partial key=value text within a PDU indicates that more 3312 text follows by setting the C bit in the Text or Login Request or 3313 Text or Login Response to 1. Data segments in a series of PDUs 3314 that have the C bit set to 1 and end with a PDU that have the C 3315 bit set to 0, or include a single PDU that has the C bit set to 0 3316 have to be considered as forming a single logical-text-data- 3317 segment (LTDS). 3319 Every key=value pair, including the last or only pair in a LTDS, 3320 MUST be followed by one null (0x00) delimiter. 3322 A key-name is whatever precedes the first = in the key=value pair. 3323 The term key is used frequently in this document in place of key- 3324 name. 3326 A value is whatever follows the first = in the key=value pair up 3327 to the end of the key=value pair, but not including the null 3328 delimiter. 3330 The following definitions will be used in the rest of this 3331 document: 3333 - standard-label: A string of one or more characters that 3334 consist of letters, digits, dot, minus, plus, commercial at, 3335 or underscore. A standard-label MUST begin with a capital 3336 letter and must not exceed 63 characters. 3338 - key-name: A standard-label. 3340 - text-value: A string of zero or more characters that consist 3341 of letters, digits, dot, minus, plus, commercial at, 3342 underscore, slash, left bracket, right bracket, or colon. 3344 - iSCSI-name-value: A string of one or more characters that 3345 consist of minus, dot, colon, or any character allowed by 3346 the output of the iSCSI string-prep template as specified in 3347 [RFC3722] (see also Section 4.2.7.2). 3349 - iSCSI-local-name-value: A UTF-8 string; no null characters 3350 are allowed in the string. This encoding is to be used for 3351 localized (internationalized) aliases. 3353 - boolean-value: The string "Yes" or "No". 3355 - hex-constant: A hexadecimal constant encoded as a string 3356 that starts with "0x" or "0X" followed by one or more digits 3357 or the letters a, b, c, d, e, f, A, B, C, D, E, or F. Hex- 3358 constants are used to encode numerical values or binary 3359 strings. When used to encode numerical values, the excessive 3360 use of leading 0 digits is discouraged. The string following 3361 0X (or 0x) represents a base16 number that starts with the 3362 most significant base16 digit, followed by all other digits 3363 in decreasing order of significance and ending with the 3364 least-significant base16 digit. When used to encode binary 3365 strings, hexadecimal constants have an implicit byte-length 3366 that includes four bits for every hexadecimal digit of the 3367 constant, including leading zeroes. For example, a hex- 3368 constant of n hexadecimal digits has a byte-length of (the 3369 integer part of) (n+1)/2. 3371 - decimal-constant: An unsigned decimal number with the digit 3372 0 or a string of one or more digits that start with a non- 3373 zero digit. Decimal-constants are used to encode numerical 3374 values or binary strings. Decimal constants can only be used 3375 to encode binary strings if the string length is explicitly 3376 specified. There is no implicit length for decimal strings. 3377 Decimal-constant MUST NOT be used for parameter values if 3378 the values can be equal or greater than 2**64 (numerical) or 3379 for binary strings that can be longer than 64 bits. 3381 - base64-constant: base64 constant encoded as a string that 3382 starts with "0b" or "0B" followed by 1 or more digits or 3383 letters or plus or slash or equal. The encoding is done 3384 according to [RFC4648]. 3386 - numerical-value: An unsigned integer always less than 2**64 3387 encoded as a decimal-constant or a hex-constant. Unsigned 3388 integer arithmetic applies to numerical-values. 3390 - large-numerical-value: An unsigned integer that can be 3391 larger than or equal to 2**64 encoded as a hex constant, or 3392 base64-constant. Unsigned integer arithmetic applies to 3393 large-numeric-values. 3395 - numeric-range: Two numerical-values separated by a tilde 3396 where the value to the right of tilde must not be lower than 3397 the value to the left. 3399 - regular-binary-value: A binary string not longer than 64 3400 bits encoded as a decimal constant, hex constant, or base64- 3401 constant. The length of the string is either specified by 3402 the key definition or is the implicit byte-length of the 3403 encoded string. 3405 - large-binary-value: A binary string longer than 64 bits 3406 encoded as a hex-constant or base64-constant. The length of 3407 the string is either specified by the key definition or is 3408 the implicit byte-length of the encoded string. 3410 - binary-value: A regular-binary-value or a large-binary- 3411 value. Operations on binary values are key specific. 3413 - simple-value: Text-value, iSCSI-name-value, boolean-value, 3414 numeric-value, a numeric-range, or a binary-value. 3416 - list-of-values: A sequence of text-values separated by a 3417 comma. 3419 If not otherwise specified, the maximum length of a simple-value 3420 (not its encoded representation) is 255 bytes not including the 3421 delimiter (comma or zero byte). 3423 Any iSCSI target or initiator MUST support receiving at least 8192 3424 bytes of key=value data in a negotiation sequence. When proposing 3425 or accepting authentication methods that explicitly require 3426 support for very long authentication items, the initiator and 3427 target MUST support receiving of at least 64 kilobytes of 3428 key=value data. 3430 6.2. Text Mode Negotiation 3432 During login, and thereafter, some session or connection 3433 parameters are either declared or negotiated through an exchange 3434 of textual information. 3436 The initiator starts the negotiation and/or declaration through a 3437 Text or Login request and indicates when it is ready for 3438 completion (by setting the F bit to 1 and keeping it to 1 in a 3439 Text Request or the T bit in the Login Request). As negotiation 3440 text may span PDU boundaries, a Text or Login Request or Text or 3441 Login Response PDU that have the C bit set to 1 MUST NOT have the 3442 F/T bit set to 1. 3444 A target receiving a Text or Login Request with the C bit set to 1 3445 MUST answer with a Text or Login Response with no data segment 3446 (DataSegmentLength 0). An initiator receiving a Text or Login 3447 Response with the C bit set to 1 MUST answer with a Text or Login 3448 Request with no data segment (DataSegmentLength 0). 3450 A target or initiator SHOULD NOT use a Text or Login Response or 3451 Text or Login Request with no data segment (DataSegmentLength 0) 3452 unless explicitly required by a general or a key-specific 3453 negotiation rule. 3455 There MUST NOT be more than one outstanding Text Request, or Text 3456 Response PDU on an iSCSI connection. An outstanding PDU in this 3457 context is one that has not been acknowledged by the remote iSCSI 3458 side. 3460 The format of a declaration is: 3462 Declarer-> = 3464 The general format of text negotiation is: 3466 Proposer-> = 3468 Acceptor-> ={|NotUnderstood|Irrelevant|Reject} 3470 Thus a declaration is a one-way textual exchange (unless the key 3471 is not understood by the receiver) while a negotiation is a two- 3472 way exchange. 3474 The proposer or declarer can either be the initiator or the 3475 target, and the acceptor can either be the target or initiator, 3476 respectively. Targets are not limited to respond to key=value 3477 pairs as proposed by the initiator. The target may propose 3478 key=value pairs of its own. 3480 All negotiations are explicit (i.e., the result MUST only be based 3481 on newly exchanged or declared values). There are no implicit 3482 proposals. If a proposal is not made, then a reply cannot be 3483 expected. Conservative design also requires that default values 3484 should not be relied upon when use of some other value has serious 3485 consequences. 3487 The value proposed or declared can be a numerical-value, a 3488 numerical-range defined by lower and upper value with both 3489 integers separated by tilde, a binary value, a text-value, an 3490 iSCSI-name-value, an iSCSI-local-name-value, a boolean-value (Yes 3491 or No), or a list of comma separated text-values. A range, a 3492 large-numerical-value, an iSCSI-name-value and an iSCSI-local- 3493 name-value MAY ONLY be used if it is explicitly allowed. An 3494 accepted value can be a numerical-value, a large-numerical-value, 3495 a text-value, or a boolean-value. 3497 If a specific key is not relevant for the current negotiation, the 3498 acceptor may answer with the constant "Irrelevant" for all types 3499 of negotiation. However the negotiation is not considered as 3500 failed if the answer is "Irrelevant". The "Irrelevant" answer is 3501 meant for those cases in which several keys are presented by a 3502 proposing party but the selection made by the acceptor for one of 3503 the keys makes other keys irrelevant. The following example 3504 illustrates the use of "Irrelevant": 3506 I->T InitialR2T=No,ImmediateData=Yes,FirstBurstLength=4192 3507 T->I InitialR2T=Yes,ImmediateData=No,FirstBurstLength=Irrelevant 3508 I->T X-rdname-vkey1=(bla,alb,None), X-rdname-vkey2=(bla,alb) 3509 T->I X-rdname-vkey1=None, X-rdname-vkey2=Irrelevant 3511 Any key not understood by the acceptor may be ignored by the 3512 acceptor without affecting the basic function. However, the answer 3513 for a key not understood MUST be key=NotUnderstood. Note that 3514 NotUnderstood is a valid answer for both declarative and 3515 negotiated keys. The general iSCSI philosophy is that 3516 comprehension precedes processing for any iSCSI key. A proposer 3517 of an iSCSI key, negotiated or declarative, in a text key exchange 3518 MUST thus be able to properly handle a NotUnderstood response. 3520 The proper way to handle a NotUnderstood response depends on where 3521 the key is specified and whether the key is declarative vs. 3522 negotiated. An iSCSI implementation MUST comprehend all text keys 3523 defined in this document. Returning a NotUnderstood response on 3524 any of these text keys therefore MUST be considered a protocol 3525 error and handled accordingly. For all other "later" keys, i.e. 3526 text keys defined in later specifications, a NotUnderstood answer 3527 concludes the negotiation for a negotiated key whereas for a 3528 declarative key, a NotUnderstood answer simply informs the 3529 declarer of a lack of comprehension by the receiver. 3531 In either case, a NotUnderstood answer always requires that the 3532 protocol behavior associated with that key not be used within the 3533 scope of the key (connection/session) by either side. 3535 The constants "None", "Reject", "Irrelevant", and "NotUnderstood" 3536 are reserved and MUST ONLY be used as described here. Violation of 3537 this rule is a protocol error (in particular the use of "Reject", 3538 "Irrelevant", and "NotUnderstood" as proposed values). 3540 Reject or Irrelevant are legitimate negotiation options where 3541 allowed but their excessive use is discouraged. A negotiation is 3542 considered complete when the acceptor has sent the key value pair 3543 even if the value is "Reject", "Irrelevant", or "NotUnderstood". 3544 Sending the key again would be a re-negotiation and is forbidden 3545 for many keys. 3547 If the acceptor sends "Reject" as an answer the negotiated key is 3548 left at its current value (or default if no value was set). If the 3549 current value is not acceptable to the proposer on the connection 3550 or to the session it is sent, the proposer MAY choose to terminate 3551 the connection or session. 3553 All keys in this document MUST be supported by iSCSI initiators 3554 and targets when used as specified here. If used as specified, 3555 these keys MUST NOT be answered with NotUnderstood. 3557 Implementers may introduce new private keys by prefixing them with 3558 X- followed by their (reversed) domain name, or with new public 3559 keys registered with IANA. For example, the entity owning the 3560 domain example.com can issue: 3562 X-com.example.bar.foo.do_something=3 3564 Each new public key in the course of standardization MUST define 3565 the acceptable responses to the key, including NotUnderstood as 3566 appropriate. Unlike [RFC3720], note that this document prohibits 3567 the X# prefix for new public keys. Based on iSCSI implementation 3568 experience, we know that there is no longer a need for a standard 3569 name prefix for keys that allow NotUnderstood response. Note that 3570 NotUnderstood will generally have to be allowed for new public 3571 keys for backwards compatibility, as well as for private X- keys. 3572 Thus the name prefix "X#" in new public key names does not carry 3573 any significance. New public key names MUST NOT begin with "X#" 3574 prefix to avoid confusion. 3576 Implementers MAY also introduce new values, but ONLY for new keys 3577 or authentication methods (see Section 12), or digests (see 3578 Section 13.1). 3580 Whenever parameter action or acceptance are dependent on other 3581 parameters, the dependency rules and parameter sequence must be 3582 specified with the parameters. 3584 In the Login Phase (see Section 6.3), every stage is a separate 3585 negotiation. In the FullFeaturePhase, a Text Request Response 3586 sequence is a negotiation. Negotiations MUST be handled as atomic 3587 operations. For example, all negotiated values go into effect 3588 after the negotiation concludes in agreement or are ignored if the 3589 negotiation fails. 3591 Some parameters may be subject to integrity rules (e.g., 3592 parameter-x must not exceed parameter-y or parameter-u not 1 3593 implies parameter-v be Yes). Whenever required, integrity rules 3594 are specified with the keys. Checking for compliance with the 3595 integrity rule must only be performed after all the parameters are 3596 available (the existent and the newly negotiated). An iSCSI target 3597 MUST perform integrity checking before the new parameters take 3598 effect. An initiator MAY perform integrity checking. 3600 An iSCSI initiator or target MAY terminate a negotiation that does 3601 not terminate within an implementation-specific reasonable time or 3602 number of exchanges, but SHOULD allow at least six (6) exchanges. 3604 6.2.1. List negotiations 3606 In list negotiation, the originator sends a list of values (which 3607 may include "None") in its order of preference. 3609 The responding party MUST respond with the same key and the first 3610 value that it supports (and is allowed to use for the specific 3611 originator) selected from the originator list. 3613 The constant "None" MUST always be used to indicate a missing 3614 function. However, "None" is only a valid selection if it is 3615 explicitly proposed. When "None" is proposed as a selection item 3616 in a negotiation for a key, it indicates to the responder that not 3617 supporting any functionality related to that key is legal, and if 3618 "None" is the negotiation result for such a key, it means that 3619 key-specific semantics are not operational for the negotiation 3620 scope (connection or session) of that key. 3622 If an acceptor does not understand any particular value in a list, 3623 it MUST ignore it. If an acceptor does not support, does not 3624 understand, or is not allowed to use any of the proposed options 3625 with a specific originator, it may use the constant "Reject" or 3626 terminate the negotiation. The selection of a value not proposed 3627 MUST be handled by the originator as a protocol error. 3629 6.2.2. Simple-value Negotiations 3631 For simple-value negotiations, the accepting party MUST answer 3632 with the same key. The value it selects becomes the negotiation 3633 result. 3635 Proposing a value not admissible (e.g., not within the specified 3636 bounds) MAY be answered with the constant "Reject", otherwise the 3637 acceptor MUST select an admissible value. 3639 The selection, by the acceptor, of a value not admissible under 3640 the selection rules is considered a protocol error. The selection 3641 rules are key-specific. 3643 For a numerical range the value selected MUST be an integer within 3644 the proposed range or "Reject" (if the range is unacceptable). 3646 For Boolean negotiations (i.e., keys taking the values Yes or No), 3647 the accepting party MUST answer with the same key and the result 3648 of the negotiation when the received value does not determine that 3649 result by itself. The last value transmitted becomes the 3650 negotiation result. The rules for selecting the value to answer 3651 with are expressed as Boolean functions of the value received, and 3652 the value that the accepting party would have selected if given a 3653 choice. 3655 Specifically, the two cases in which answers are OPTIONAL are: 3657 - The Boolean function is "AND" and the value "No" is 3658 received. The outcome of the negotiation is "No". 3660 - The Boolean function is "OR" and the value "Yes" is 3661 received. The outcome of the negotiation is "Yes". 3663 Responses are REQUIRED in all other cases, and the value chosen 3664 and sent by the acceptor becomes the outcome of the negotiation. 3666 6.3. Login Phase 3668 The Login Phase establishes an iSCSI connection between an 3669 initiator and a target; it creates also a new session or 3671 associates the connection to an existing session. The Login Phase 3672 sets the iSCSI protocol parameters, security parameters, and 3673 authenticates the initiator and target to each other. 3675 The Login Phase is only implemented via Login request and 3676 responses. The whole Login Phase is considered as a single task 3677 and has a single Initiator Task Tag (similar to the linked SCSI 3678 commands). 3680 There MUST NOT be more than one outstanding Login Request, or 3681 Login Response on an iSCSI connection. An outstanding PDU in this 3682 context is one that has not been acknowledged by the remote iSCSI 3683 side. 3685 The default MaxRecvDataSegmentLength is used during Login. 3687 The Login Phase sequence of requests and responses proceeds as 3688 follows: 3690 - Login initial request 3692 - Login partial response (optional) 3694 - More Login requests and responses (optional) 3696 - Login Final-Response (mandatory) 3698 The initial login request of any connection MUST include the 3699 InitiatorName key=value pair. The initial login request of the 3700 first connection of a session MAY also include the SessionType 3701 key=value pair. For any connection within a session whose type is 3702 not "Discovery", the first login request MUST also include the 3703 TargetName key=value pair. 3705 The Login Final-response accepts or rejects the Login request. 3707 The Login Phase MAY include a SecurityNegotiation stage and a 3708 LoginOperationalNegotiation stage and MUST include at least one of 3709 them, but the included stage MAY be empty except for the mandatory 3710 names. 3712 The login requests and responses contain a field (CSG) that 3713 indicates the current negotiation stage (SecurityNegotiation or 3714 LoginOperationalNegotiation). If both stages are used, the 3715 SecurityNegotiation MUST precede the LoginOperationalNegotiation. 3717 Some operational parameters can be negotiated outside the login 3718 through Text requests and responses. 3720 Authentication-related security keys (Section 12 ) MUST be 3721 completely negotiated within the Login Phase. The use of 3722 underlying IPsec security is specified in Section 9.3, in 3723 [RFC3723], and in [IPSEC-IPS}. iSCSI support for security within 3724 the protocol only consists of authentication in the Login Phase. 3726 In some environments, a target or an initiator is not interested 3727 in authenticating its counterpart. It is possible to bypass 3728 authentication through the Login request and response. 3730 The initiator and target MAY want to negotiate iSCSI 3731 authentication parameters. Once this negotiation is completed, the 3732 channel is considered secure. 3734 Most of the negotiation keys are only allowed in a specific stage. 3735 The SecurityNegotiation keys appear in Section 12 and the 3736 LoginOperationalNegotiation keys appear in Section 13. Only a 3737 limited set of keys (marked as Any-Stage in Section 13) may be 3738 used in any of the two stages. 3740 Any given Login request or response belongs to a specific stage; 3741 this determines the negotiation keys allowed with the request or 3742 response. It is considered to be a protocol error to send a key 3743 not allowed in the current stage. 3745 Stage transition is performed through a command exchange 3746 (request/response) that carries the T bit and the same CSG code. 3747 During this exchange, the next stage is selected by the target 3748 through the "next stage" code (NSG). The selected NSG MUST NOT 3749 exceed the value stated by the initiator. The initiator can 3750 request a transition whenever it is ready, but a target can only 3751 respond with a transition after one is proposed by the initiator. 3753 In a negotiation sequence, the T bit settings in one pair of login 3754 request-responses have no bearing on the T bit settings of the 3755 next pair. An initiator that has a T bit set to 1 in one pair and 3756 is answered with a T bit setting of 0 may issue the next request 3757 with T bit set to 0. 3759 When a transition is requested by the initiator and acknowledged 3760 by the target, both the initiator and target switch to the 3761 selected stage. 3763 Targets MUST NOT submit parameters that require an additional 3764 initiator login request in a login response with the T bit set to 3765 1. 3767 Stage transitions during login (including entering and exit) are 3768 only possible as outlined in the following table: 3770 +-----------------------------------------------------------+ 3771 |From To -> | Security | Operational | FullFeature | 3772 | | | | | | 3773 | V | | | | 3774 +-----------------------------------------------------------+ 3775 | (start) | yes | yes | no | 3776 +-----------------------------------------------------------+ 3777 | Security | no | yes | yes | 3778 +-----------------------------------------------------------+ 3779 | Operational | no | no | yes | 3780 +-----------------------------------------------------------+ 3782 The Login Final-Response that accepts a Login Request can only 3783 come as a response to a Login request with the T bit set to 1, and 3784 both the request and response MUST indicate FullFeaturePhase as 3785 the next phase via the NSG field. 3787 Neither the initiator nor the target should attempt to declare or 3788 negotiate a parameter more than once during login except for 3789 responses to specific keys that explicitly allow repeated key 3790 declarations (e.g., TargetAddress). An attempt to 3791 renegotiate/redeclare parameters not specifically allowed MUST be 3792 detected by the initiator and target. If such an attempt is 3793 detected by the target, the target MUST respond with Login reject 3794 (initiator error); if detected by the initiator, the initiator 3795 MUST drop the connection. 3797 6.3.1. Login Phase Start 3799 The Login Phase starts with a login request from the initiator to 3800 the target. The initial login request includes: 3802 -Protocol version supported by the initiator. 3804 -iSCSI Initiator Name and iSCSI Target Name 3806 -ISID, TSIH, and connection Ids 3808 -Negotiation stage that the initiator is ready to enter. 3810 A login may create a new session or it may add a connection to an 3811 existing session. Between a given iSCSI Initiator Node (selected 3812 only by an InitiatorName) and a given iSCSI target defined by an 3813 iSCSI TargetName and a Target Portal Group Tag, the login results 3814 are defined by the following table: 3816 +----------------------------------------------------------------+ 3817 |ISID | TSIH | CID | Target action | 3818 +----------------------------------------------------------------+ 3819 |new | non-zero | any | fail the login | 3820 | | | | ("session does not exist") | 3821 +----------------------------------------------------------------+ 3822 |new | zero | any | instantiate a new session | 3823 +----------------------------------------------------------------+ 3824 |existing| zero | any | do session reinstatement | 3825 | | | | (see Section 6.3.5) | 3826 +----------------------------------------------------------------+ 3827 |existing| non-zero | new | add a new connection to | 3828 | | existing | | the session | 3829 +----------------------------------------------------------------+ 3830 |existing| non-zero |existing| do connection reinstatement| 3831 | | existing | | (see Section 7.1.4.3) | 3832 +----------------------------------------------------------------+ 3833 |existing| non-zero | any | fail the login | 3834 | | new | | ("session does not exist") | 3835 +----------------------------------------------------------------+ 3837 Determination of "existing" or "new" are made by the target. 3839 Optionally, the login request may include: 3841 -Security parameters 3842 OR 3844 -iSCSI operational parameters 3845 AND/OR 3847 -The next negotiation stage that the initiator is ready to 3848 enter. 3850 The target can answer the login in the following ways: 3852 -Login Response with Login reject. This is an immediate 3853 rejection from the target that causes the connection to 3854 terminate and the session to terminate if this is the first 3855 (or only) connection of a new session. The T bit and the CSG 3856 and NSG fields are reserved. 3858 -Login Response with Login accept as a final response (T bit 3859 set to 1 and the NSG in both request and response are set to 3860 FullFeaturePhase). The response includes the protocol 3861 version supported by the target and the session ID, and may 3862 include iSCSI operational or security parameters (that 3863 depend on the current stage). 3865 -Login Response with Login Accept as a partial response (NSG 3866 not set to FullFeaturePhase in both request and response) 3867 that indicates the start of a negotiation sequence. The 3868 response includes the protocol version supported by the 3869 target and either security or iSCSI parameters (when no 3870 security mechanism is chosen) supported by the target. 3872 If the initiator decides to forego the SecurityNegotiation stage, 3873 it issues the Login with the CSG set to 3874 LoginOperationalNegotiation and the target may reply with a Login 3875 Response that indicates that it is unwilling to accept the 3876 connection (see Section 11.13) without SecurityNegotiation and 3877 will terminate the connection with a response of Authentication 3878 failure (see Section 11.13.5). 3880 If the initiator is willing to negotiate iSCSI security, but is 3881 unwilling to make the initial parameter proposal and may accept a 3882 connection without iSCSI security, it issues the Login with the T 3883 bit set to 1, the CSG set to SecurityNegotiation, and NSG set to 3884 LoginOperationalNegotiation. If the target is also ready to skip 3885 security, the login response only contains the 3886 TargetPortalGroupTag key (see Section 13.9), the T bit set to 1, 3887 the CSG set to SecurityNegotiation, and NSG set to 3888 LoginOperationalNegotiation. 3890 An initiator that chooses to operate without iSCSI security and 3891 with all the operational parameters taking the default values 3892 issues the Login with the T bit set to 1, the CSG set to 3893 LoginOperationalNegotiation, and NSG set to FullFeaturePhase. If 3894 the target is also ready to forego security and can finish its 3895 LoginOperationalNegotiation, the Login response has T bit set to 3896 1, the CSG set to LoginOperationalNegotiation, and NSG set to 3897 FullFeaturePhase in the next stage. 3899 During the Login Phase the iSCSI target MUST return the 3900 TargetPortalGroupTag key with the first Login Response PDU with 3901 which it is allowed to do so (i.e., the first Login Response 3902 issued after the first Login Request with the C bit set to 0) for 3903 all session types. The TargetPortalGroupTag key value indicates 3904 the iSCSI portal group servicing the Login Request PDU. If the 3905 reconfiguration of iSCSI portal groups is a concern in a given 3906 environment, the iSCSI initiator should use this key to ascertain 3907 that it had indeed initiated the Login Phase with the intended 3908 target portal group. 3910 6.3.2. iSCSI Security Negotiation 3912 The security exchange sets the security mechanism and 3913 authenticates the initiator user and the target to each other. The 3914 exchange proceeds according to the authentication method chosen in 3915 the negotiation phase and is conducted using the login requests' 3916 and responses' key=value parameters. 3918 An initiator directed negotiation proceeds as follows: 3920 -The initiator sends a login request with an ordered list of 3921 the options it supports (authentication algorithm). The 3922 options are listed in the initiator's order of preference. 3923 The initiator MAY also send private or public extension 3924 options. 3925 -The target MUST reply with the first option in the list it 3926 supports and is allowed to use for the specific initiator 3927 unless it does not support any in which case it MUST answer 3928 with "Reject" (see Section 6.2). The parameters are encoded 3929 in UTF8 as key=value. For security parameters, see Section 3930 12. 3932 -When the initiator considers that it is ready to conclude the 3933 SecurityNegotiation stage, it sets the T bit to 1 and the 3934 NSG to what it would like the next stage to be. The target 3935 will then set the T bit to 1 and set NSG to the next stage 3936 in the Login response when it finishes sending its security 3937 keys. The next stage selected will be the one the target 3938 selected. If the next stage is FullFeaturePhase, the target 3939 MUST respond with a Login Response with the TSIH value. 3941 If the security negotiation fails at the target, then the target 3942 MUST send the appropriate Login Response PDU. If the security 3943 negotiation fails at the initiator, the initiator SHOULD close the 3944 connection. 3946 It should be noted that the negotiation might also be directed by 3947 the target if the initiator does support security, but is not 3948 ready to direct the negotiation (propose options) - see Appendix B 3949 for an example. 3951 6.3.3. Operational Parameter Negotiation During the Login Phase 3953 Operational parameter negotiation during the login MAY be done: 3955 - Starting with the first Login request if the initiator does 3956 not propose any security/ integrity option. 3958 - Starting immediately after the security negotiation if the 3959 initiator and target perform such a negotiation. 3961 Operational parameter negotiation MAY involve several Login 3962 request-response exchanges started and terminated by the 3963 initiator. The initiator MUST indicate its intent to terminate the 3964 negotiation by setting the T bit to 1; the target sets the T bit 3965 to 1 on the last response. 3967 Even when the initiator indicates its intent to switch stage by 3968 setting the T bit to 1 in a Login request, the target MAY respond 3969 with a Login response with the T bit set to 0. In that case, the 3970 initiator SHOULD continue to set the T bit to 1 in subsequent 3971 Login requests (even empty) that it sends, until target sends a 3972 Login response with the T bit set to 1 or sends a key that 3973 requires initiator to set the T bit to 0. 3975 Some session specific parameters can only be specified during the 3976 Login Phase of the first connection of a session (i.e., begun by a 3977 login request that contains a zero-valued TSIH) - the leading 3978 Login Phase (e.g., the maximum number of connections that can be 3979 used for this session). 3981 A session is operational once it has at least one connection in 3982 FullFeaturePhase. New or replacement connections can only be added 3983 to a session after the session is operational. 3985 For operational parameters, see Section 13. 3987 6.3.4. Connection Reinstatement 3989 Connection reinstatement is the process of an initiator logging in 3990 with a ISID-TSIH-CID combination that is possibly active from the 3991 target's perspective, which causes the implicit logging out of the 3992 connection corresponding to the CID and reinstating a new Full 3993 Feature Phase iSCSI connection in its place (with the same CID). 3994 Thus, the TSIH in the Login Request PDU MUST be non-zero and CID 3995 does not change during a connection reinstatement. The Login 3996 request performs the logout function of the old connection if an 3997 explicit logout was not performed earlier. In sessions with a 3998 single connection, this may imply the opening of a second 3999 connection with the sole purpose of cleaning up the first. Targets 4000 MUST support opening a second connection even when they do not 4001 support multiple connections in Full Feature Phase if 4002 ErrorRecoveryLevel is 2 and SHOULD support opening a second 4003 connection if ErrorRecoveryLevel is less than 2. 4005 If the operational ErrorRecoveryLevel is 2, connection 4006 reinstatement enables future task reassignment. If the operational 4007 ErrorRecoveryLevel is less than 2, connection reinstatement is the 4008 replacement of the old CID without enabling task reassignment. In 4009 this case, all the tasks that were active on the old CID must be 4010 immediately terminated without further notice to the initiator. 4012 The initiator connection state MUST be CLEANUP_WAIT (Section 4013 8.1.3) when the initiator attempts a connection reinstatement. 4015 In practical terms, in addition to the implicit logout of the old 4016 connection, reinstatement is equivalent to a new connection login. 4018 6.3.5. Session Reinstatement, Closure, and Timeout 4020 Session reinstatement is the process of the initiator logging in 4021 with an ISID that is possibly active from the target's 4022 perspective. Thus implicitly logging out the session that 4023 corresponds to the ISID and reinstating a new iSCSI session in its 4024 place (with the same ISID). Therefore, the TSIH in the Login PDU 4025 MUST be zero to signal session reinstatement. Session 4026 reinstatement causes all the tasks that were active on the old 4027 session to be immediately terminated by the target without further 4028 notice to the initiator. 4030 The initiator session state MUST be FAILED (Section 8.3) when the 4031 initiator attempts a session reinstatement. 4033 Session closure is an event defined to be one of the following: 4035 - A successful "session close" logout. 4037 - A successful "connection close" logout for the last Full 4038 Feature Phase connection when no other connection in the 4039 session is waiting for cleanup (Section 8.2) and no tasks in 4040 the session are waiting for reassignment. 4042 Session timeout is an event defined to occur when the last 4043 connection state timeout expires and no tasks are waiting for 4044 reassignment. This takes the session to the FREE state (N6 4045 transition in the session state diagram). 4047 6.3.5.1. Loss of Nexus Notification 4049 The iSCSI layer provides the SCSI layer with the "I_T nexus loss" 4050 notification when any one of the following events happens: 4052 Successful completion of session reinstatement. 4053 Session closure event. 4054 Session timeout event. 4056 Certain SCSI object clearing actions may result due to the 4057 notification in the SCSI end nodes, as documented in Appendix E. 4059 6.3.6. Session Continuation and Failure 4061 Session continuation is the process by which the state of a 4062 preexisting session continues to be used by connection 4063 reinstatement (Section 6.3.4), or by adding a connection with a 4064 new CID. Either of these actions associates the new transport 4065 connection with the session state. 4067 Session failure is an event where the last Full Feature Phase 4068 connection reaches the CLEANUP_WAIT state (Section 8.2), or 4069 completes a successful recovery logout thus causing all active 4070 tasks (that are formerly allegiant to the connection) to start 4071 waiting for task reassignment. 4073 6.4. Operational Parameter Negotiation Outside the Login Phase 4075 Some operational parameters MAY be negotiated outside (after) the 4076 Login Phase. 4078 Parameter negotiation in Full Feature Phase is done through Text 4079 requests and responses. Operational parameter negotiation MAY 4080 involve several Text request-response exchanges, which the 4081 initiator always starts, terminates, and uses the same Initiator 4082 Task Tag. The initiator MUST indicate its intent to finish the 4083 negotiation by setting the F bit to 1; the target sets the F bit 4084 to 1 on the last response. 4086 If the target responds to a Text request with the F bit set to 1 4087 with a Text response with the F bit set to 0, the initiator should 4088 keep sending the Text request (even empty) with the F bit set to 4089 1, while it still wants to finish the negotiation, until it 4090 receives the Text response with the F bit set to 1. Responding to 4091 a Text request with the F bit set to 1 with an empty (no key=value 4092 pairs) response with the F bit set to 0 is discouraged. 4094 Even when the initiator indicates its intent to finish the 4095 negotiation by setting the F bit to 1 in a Text request, the 4096 target MAY respond with a Text response with the F bit set to 0. 4097 In that case, the initiator SHOULD continue to set the F bit to 1 4098 in subsequent Text requests (even empty) that it sends, until 4099 target sends the final Text response with the F bit set to 1. Note 4100 that in the same case of Text request with the F bit set to 1, 4101 target SHOULD NOT respond with an empty (no key=value pairs) Text 4102 response with the F bit set to 0, because such a response may 4103 cause the initiator to abandon negotiation. 4105 Targets MUST NOT submit parameters that require an additional 4106 initiator Text request in a Text response with the F bit set to 1. 4108 In a negotiation sequence, the F bit settings in one pair of Text 4109 request-responses have no bearing on the F bit settings of the 4110 next pair. An initiator that has the F bit set to 1 in a request 4111 and is being answered with an F bit setting of 0 may issue the 4112 next request with the F bit set to 0. 4114 Whenever the target responds with the F bit set to 0, it MUST set 4115 the Target Transfer Tag to a value other than the default 4116 0xffffffff. 4118 An initiator MAY reset an operational parameter negotiation by 4119 issuing a Text request with the Target Transfer Tag set to the 4120 value 0xffffffff after receiving a response with the Target 4121 Transfer Tag set to a value other than 0xffffffff. A target may 4122 reset an operational parameter negotiation by answering a Text 4123 request with a Reject PDU. 4125 Neither the initiator nor the target should attempt to declare or 4126 negotiate a parameter more than once during any negotiation 4127 sequence, except for responses to specific keys that explicitly 4128 allow repeated key declarations (e.g., TargetAddress). If detected 4129 by the target, this MUST result in a Reject PDU with a reason of 4130 "protocol error". The initiator MUST reset the negotiation as 4131 outlined above. 4133 Parameters negotiated by a text exchange negotiation sequence only 4134 become effective after the negotiation sequence is completed. 4136 7. iSCSI Error Handling and Recovery 4138 7.1. Overview 4140 7.1.1. Background 4142 The following two considerations prompted the design of much of 4143 the error recovery functionality in iSCSI: 4145 An iSCSI PDU may fail the digest check and be dropped, despite 4146 being received by the TCP layer. The iSCSI layer must 4147 optionally be allowed to recover such dropped PDUs. 4149 A TCP connection may fail at any time during the data 4150 transfer. All the active tasks must optionally be allowed 4151 to be continued on a different TCP connection within the 4152 same session. 4154 Implementations have considerable flexibility in deciding what 4155 degree of error recovery to support, when to use it and by which 4156 mechanisms to achieve the required behavior. Only the externally 4157 visible actions of the error recovery mechanisms must be 4158 standardized to ensure interoperability. 4160 This Section describes a general model for recovery in support of 4161 interoperability. See Appendix D for further detail on how the 4162 described model may be implemented. Compliant implementations do 4163 not have to match the implementation details of this model as 4164 presented, but the external behavior of such implementations must 4165 correspond to the externally observable characteristics of the 4166 presented model. 4168 7.1.2. Goals 4170 The major design goals of the iSCSI error recovery scheme are as 4171 follows: 4173 Allow iSCSI implementations to meet different requirements by 4174 defining a collection of error recovery mechanisms that 4175 implementations may choose from. 4177 Ensure interoperability between any two implementations 4178 supporting different sets of error recovery capabilities. 4180 Define the error recovery mechanisms to ensure command 4181 ordering even in the face of errors, for initiators that 4182 demand ordering. 4184 Do not make additions in the fast path, but allow moderate 4185 complexity in the error recovery path. 4187 Prevent both the initiator and target from attempting to 4188 recover the same set of PDUs at the same time. For example, 4189 there must be a clear "error recovery functionality 4190 distribution" between the initiator and target. 4192 7.1.3. Protocol Features and State Expectations 4194 The initiator mechanisms defined in connection with error recovery 4195 are: 4197 a) NOP-OUT to probe sequence numbers of the target (Section 4198 11.18) 4199 b) Command retry (Section 7.2.1) 4200 c) Recovery R2T support (Section 7.8) 4201 d) Requesting retransmission of status/data/R2T using the 4202 SNACK facility (Section 11.16) 4203 e) Acknowledging the receipt of the data (Section 11.16) 4204 f) Reassigning the connection allegiance of a task to a 4205 different TCP connection (Section 7.2.2) 4206 g) Terminating the entire iSCSI session to start afresh 4207 (Section 7.1.4.4) 4209 The target mechanisms defined in connection with error recovery 4210 are: 4212 a) NOP-IN to probe sequence numbers of the initiator (Section 4213 11.19) 4214 b) Requesting retransmission of data using the recovery R2T 4215 feature (Section 7) 4216 c) SNACK support (Section 11.16) 4217 d) Requesting that parts of read data be acknowledged (Section 4218 11.7.2) 4219 e) Allegiance reassignment support (Section 7.2.2) 4220 f) Terminating the entire iSCSI session to force the initiator 4221 to start over (Section 7.1.4.4) 4223 For any outstanding SCSI command, it is assumed that iSCSI, in 4224 conjunction with SCSI at the initiator, is able to keep enough 4225 information to be able to rebuild the command PDU, and that 4226 outgoing data is available (in host memory) for retransmission 4227 while the command is outstanding. It is also assumed that at the 4228 target, incoming data (read data) MAY be kept for recovery or it 4229 can be reread from a device server. 4231 It is further assumed that a target will keep the "status & sense" 4232 for a command it has executed if it supports status 4233 retransmission. 4235 A target that agrees to support data retransmission is expected to 4236 be prepared to retransmit the outgoing data (i.e., Data-In) on 4237 request until either the status for the completed command is 4238 acknowledged, or the data in question has been separately 4239 acknowledged. 4241 7.1.4. Recovery Classes 4243 iSCSI enables the following classes of recovery (in the order of 4244 increasing scope of affected iSCSI tasks): 4246 - Within a command (i.e., without requiring command restart). 4248 - Within a connection (i.e., without requiring the connection 4249 to be rebuilt, but perhaps requiring command restart). 4251 - Connection recovery (i.e., perhaps requiring connections to 4252 be rebuilt and commands to be reissued). 4254 - Session recovery. 4256 The recovery scenarios detailed in the rest of this Section are 4257 representative rather than exclusive. In every case, they detail 4258 the lowest class recovery that MAY be attempted. The implementer 4259 is left to decide under which circumstances to escalate to the 4260 next recovery class and/or what recovery classes to implement. 4261 Both the iSCSI target and initiator MAY escalate the error 4262 handling to an error recovery class, which impacts a larger number 4263 of iSCSI tasks in any of the cases identified in the following 4264 discussion. 4266 In all classes, the implementer has the choice of deferring errors 4267 to the SCSI initiator (with an appropriate response code), in 4268 which case the task, if any, has to be removed from the target and 4269 all the side-effects, such as ACA, must be considered. 4271 Use of within-connection and within-command recovery classes MUST 4272 NOT be attempted before the connection is in Full Feature Phase. 4274 In the detailed description of the recovery classes, the mandating 4275 terms (MUST, SHOULD, MAY, etc.) indicate normative actions to be 4276 executed if the recovery class is supported (see Section 7.1.5 for 4277 the related negotiation semantics) and used. 4279 7.1.4.1. Recovery Within-command 4281 At the target, the following cases lend themselves to within- 4282 command recovery: 4284 a) Lost data PDU - realized through one of the following: 4285 b) Data digest error - dealt with as specified in Section 7.8, 4286 using the option of a recovery R2T. 4287 c) Sequence reception timeout (no data or partial-data-and-no-F- 4288 bit) - considered an implicit sequence error and dealt with 4289 as specified in Section 7.9, using the option of a recovery 4290 R2T. 4291 d) Header digest error, which manifests as a sequence reception 4292 timeout or a sequence error - dealt with as specified in 4293 Section 7.9, using the option of a recovery R2T. 4295 At the initiator, the following cases lend themselves to within- 4296 command recovery: 4298 a) Lost data PDU or lost R2T - realized through one of the 4299 following: 4300 b) Data digest error - dealt with as specified in Section 7.8, 4301 using the option of a SNACK. 4302 c) Sequence reception timeout (no status) or response reception 4303 timeout - dealt with as specified in Section 7.9, using the 4304 option of a SNACK. 4305 d) Header digest error, which manifests as a sequence reception 4306 timeout or a sequence error - dealt with as specified in 4307 Section 7.9, using the option of a SNACK. 4309 To avoid a race with the target, which may already have a recovery 4310 R2T or a termination response on its way, an initiator SHOULD NOT 4311 originate a SNACK for an R2T based on its internal timeouts (if 4312 any). Recovery in this case is better left to the target. 4314 The timeout values used by the initiator and target are outside 4315 the scope of this document. Sequence reception timeout is 4316 generally a large enough value to allow the data sequence transfer 4317 to be complete. 4319 7.1.4.2. Recovery Within-connection 4321 At the initiator, the following cases lend themselves to within- 4322 connection recovery: 4324 a) Requests not acknowledged for a long time. Requests are 4325 acknowledged explicitly through ExpCmdSN or implicitly by 4326 receiving data and/or status. The initiator MAY retry non- 4327 acknowledged commands as specified in Section 7.2. 4328 b) Lost iSCSI numbered Response. It is recognized by either 4329 identifying a data digest error on a Response PDU or a Data- 4330 In PDU carrying the status, or by receiving a Response PDU 4331 with a higher StatSN than expected. In the first case, digest 4332 error handling is done as specified in Section 7.8 using the 4333 option of a SNACK. In the second case, sequence error 4334 handling is done as specified in Section 7.9, using the 4335 option of a SNACK. 4337 At the target, the following cases lend themselves to within- 4338 connection recovery: 4340 - Status/Response not acknowledged for a long time. The target 4341 MAY issue a NOP-IN (with a valid Target Transfer Tag or 4342 otherwise) that carries the next status sequence number it 4343 is going to use in the StatSN field. This helps the 4344 initiator detect any missing StatSN(s) and issue a SNACK for 4345 the status. 4347 The timeout values used by the initiator and the target are 4348 outside the scope of this document. 4350 7.1.4.3. Connection Recovery 4352 At an iSCSI initiator, the following cases lend themselves to 4353 connection recovery: 4355 a) TCP connection failure: The initiator MUST close the 4356 connection. It then MUST either implicitly or explicitly 4357 logout the failed connection with the reason code "remove the 4358 connection for recovery" and reassign connection allegiance 4359 for all commands still in progress associated with the failed 4360 connection on one or more connections (some or all of which 4361 MAY be newly established connections) using the "Task 4362 reassign" task management function (see Section 11.5.1). For 4363 an initiator, a command is in progress as long as it has not 4364 received a response or a Data-In PDU including status. 4366 Note: The logout function is mandatory. However, a new 4367 connection establishment is only mandatory if the failed 4368 connection was the last or only connection in the session. 4369 b) Receiving an Asynchronous Message that indicates one or all 4370 connections in a session has been dropped. The initiator 4371 MUST handle it as a TCP connection failure for the 4372 connection(s) referred to in the Message. 4374 At an iSCSI target, the following cases lend themselves to 4375 connection recovery: 4377 - TCP connection failure. The target MUST close the connection 4378 and, if more than one connection is available, the target 4379 SHOULD send an Asynchronous Message that indicates it has 4380 dropped the connection. Then, the target will wait for the 4381 initiator to continue recovery. 4383 7.1.4.4. Session Recovery 4385 Session recovery should be performed when all other recovery 4386 attempts have failed. Very simple initiators and targets MAY 4387 perform session recovery on all iSCSI errors and rely on recovery 4388 on the SCSI layer and above. 4390 Session recovery implies the closing of all TCP connections, 4391 internally aborting all executing and queued tasks for the given 4392 initiator at the target, terminating all outstanding SCSI commands 4393 with an appropriate SCSI service response at the initiator, and 4394 restarting a session on a new set of connection(s) (TCP connection 4395 establishment and login on all new connections). 4397 For possible clearing effects of session recovery on SCSI and 4398 iSCSI objects, refer to Appendix E. 4400 7.1.5. Error Recovery Hierarchy 4402 The error recovery classes described so far are organized into a 4403 hierarchy for ease in understanding and to limit the 4404 implementation complexity. With few and well defined recovery 4405 levels interoperability is easier to achieve. The attributes of 4406 this hierarchy are as follows: 4408 a) Each level is a superset of the capabilities of the 4409 previous level. For example, Level 1 support implies 4410 supporting all capabilities of Level 0 and more. 4411 b) As a corollary, supporting a higher error recovery level 4412 means increased sophistication and possibly an increase 4413 in resource requirements. 4414 c) Supporting error recovery level "n" is advertised and 4415 negotiated by each iSCSI entity by exchanging the text 4416 key "ErrorRecoveryLevel=n". The lower of the two 4417 exchanged values is the operational ErrorRecoveryLevel 4418 for the session. 4420 The following diagram represents the error recovery hierarchy. 4422 + 4423 / \ 4424 / 2 \ <-- Connection recovery 4425 +-----+ 4426 / 1 \ <-- Digest failure recovery 4427 +---------+ 4428 / 0 \ <-- Session failure recovery 4429 +-------------+ 4431 The following table lists the error recovery capabilities expected 4432 from the implementations that support each error recovery level. 4434 +-------------------+--------------------------------------------+ 4435 |ErrorRecoveryLevel | Associated Error recovery capabilities | 4436 +-------------------+--------------------------------------------+ 4437 | 0 | Session recovery class | 4438 | | (Session Recovery) | 4439 +-------------------+--------------------------------------------+ 4440 | 1 | Digest failure recovery (See Note below.) | 4441 | | plus the capabilities of ER Level 0 | 4442 +-------------------+--------------------------------------------+ 4443 | 2 | Connection recovery class | 4444 | | (Connection Recovery) | 4445 | | plus the capabilities of ER Level 1 | 4446 +-------------------+--------------------------------------------+ 4448 Note: Digest failure recovery is comprised of two recovery 4449 classes: Within-Connection recovery class (Recovery Within- 4450 connection) and Within-Command recovery class (Recovery Within- 4451 command). 4453 When a defined value of ErrorRecoveryLevel is proposed by an 4454 originator in a text negotiation, the originator MUST support the 4455 functionality defined for the proposed value and additionally, 4456 functionality corresponding to any defined value numerically less 4457 than the proposed. When a defined value of ErrorRecoveryLevel is 4458 returned by a responder in a text negotiation, the responder MUST 4459 support the functionality corresponding to the ErrorRecoveryLevel 4460 it is accepting. 4462 When either party attempts to use error recovery functionality 4463 beyond what is negotiated, the recovery attempts MAY fail unless 4464 an apriori agreement outside the scope of this document exists 4465 between the two parties to provide such support. 4467 Implementations MUST support error recovery level "0", while the 4468 rest are OPTIONAL to implement. In implementation terms, the 4469 above striation means that the following incremental 4470 sophistication with each level is required. 4472 +-------------------+--------------------------------------------+ 4473 |Level transition | Incremental requirement | 4474 +-------------------+--------------------------------------------+ 4475 | 0->1 | PDU retransmissions on the same connection| 4476 +-------------------+--------------------------------------------+ 4477 | 1->2 | Retransmission across connections and | 4478 | | allegiance reassignment | 4479 +-------------------+--------------------------------------------+ 4481 7.2. Retry and Reassign in Recovery 4483 This Section summarizes two important and somewhat related iSCSI 4484 protocol features used in error recovery. 4486 7.2.1. Usage of Retry 4488 By resending the same iSCSI command PDU ("retry") in the absence 4489 of a command acknowledgement (by way of an ExpCmdSN update) or a 4490 response, an initiator attempts to "plug" (what it thinks are) the 4491 discontinuities in CmdSN ordering on the target end. Discarded 4492 command PDUs, due to digest errors, may have created these 4493 discontinuities. 4495 Retry MUST NOT be used for reasons other than plugging command 4496 sequence gaps, and in particular, cannot be used for requesting 4497 PDU retransmissions from a target. Any such PDU retransmission 4498 requests for a currently allegiant command in progress may be made 4499 using the SNACK mechanism described in Section 11.16, although the 4500 usage of SNACK is OPTIONAL. 4502 If initiators, as part of plugging command sequence gaps as 4503 described above, inadvertently issue retries for allegiant 4504 commands already in progress (i.e., targets did not see the 4505 discontinuities in CmdSN ordering), the duplicate commands are 4506 silently ignored by targets as specified in Section 4.2.2.1. 4508 When an iSCSI command is retried, the command PDU MUST carry the 4509 original Initiator Task Tag and the original operational 4510 attributes (e.g., flags, function names, LUN, CDB etc.) as well as 4511 the original CmdSN. The command being retried MUST be sent on the 4512 same connection as the original command unless the original 4513 connection was already successfully logged out. 4515 7.2.2. Allegiance Reassignment 4517 By issuing a "task reassign" task management request (Section 4518 11.5.1), the initiator signals its intent to continue an already 4519 active command (but with no current connection allegiance) as part 4520 of connection recovery. This means that a new connection 4521 allegiance is requested for the command, which seeks to associate 4522 it to the connection on which the task management request is being 4523 issued. Before the allegiance reassignment is attempted for a 4524 task, an implicit or explicit Logout with the reason code "remove 4525 the connection for recovery" (see Section 11.14.1) MUST be 4526 successfully completed for the previous connection to which the 4527 task was allegiant. 4529 In reassigning connection allegiance for a command, the targets 4530 SHOULD continue the command from its current state. For example, 4531 when reassigning read commands, the target SHOULD take advantage 4532 of the ExpDataSN field provided by the Task Management function 4533 request (which must be set to zero if there was no data transfer) 4534 and bring the read command to completion by sending the remaining 4535 data and sending (or resending) the status. ExpDataSN 4536 acknowledges all data sent up to, but not including, the Data-In 4537 PDU and or R2T with DataSN (or R2TSN) equal to ExpDataSN. However, 4538 targets may choose to send/receive all unacknowledged data or all 4539 of the data on a reassignment of connection allegiance if unable 4540 to recover or maintain accurate state. Initiators MUST NOT 4541 subsequently request data retransmission through Data SNACK for 4542 PDUs numbered less than ExpDataSN (i.e., prior to the acknowledged 4543 sequence number). For all types of commands, a reassignment 4544 request implies that the task is still considered in progress by 4545 the initiator and the target must conclude the task appropriately 4546 if the target returns the "Function Complete" response to the 4547 reassignment request. This might possibly involve retransmission 4548 of data/R2T/status PDUs as necessary, but MUST involve the 4549 (re)transmission of the status PDU. 4551 It is OPTIONAL for targets to support the allegiance reassignment. 4552 This capability is negotiated via the ErrorRecoveryLevel text key 4553 during the login time. When a target does not support allegiance 4554 reassignment, it MUST respond with a Task Management response code 4555 of "Allegiance reassignment not supported". If allegiance 4556 reassignment is supported by the target, but the task is still 4557 allegiant to a different connection, or a successful recovery 4558 Logout of the previously allegiant connection was not performed, 4559 the target MUST respond with a Task Management response code of 4560 "Task still allegiant". 4562 If allegiance reassignment is supported by the target, the Task 4563 Management response to the reassignment request MUST be issued 4564 before the reassignment becomes effective. 4566 If a SCSI Command that involves data input is reassigned, any 4567 SNACK Tag it holds for a final response from the original 4568 connection is deleted and the default value of 0 MUST be used 4569 instead. 4571 7.3. Usage Of Reject PDU in Recovery 4573 Targets MUST NOT implicitly terminate an active task by sending a 4574 Reject PDU for any PDU exchanged during the life of the task. If 4575 the target decides to terminate the task, a Response PDU (SCSI, 4576 Text, Task, etc.) must be returned by the target to conclude the 4577 task. If the task had never been active before the Reject (i.e., 4578 the Reject is on the command PDU), targets should not send any 4579 further responses because the command itself is being discarded. 4581 The above rule means that the initiator can eventually expect a 4582 response on receiving Rejects, if the received Reject is for a PDU 4583 other than the command PDU itself. The non-command Rejects only 4584 have diagnostic value in logging the errors, and they can be used 4585 for retransmission decisions by the initiators. 4587 The CmdSN of the rejected command PDU (if it is a non-immediate 4588 command) MUST NOT be considered received by the target (i.e., a 4589 command sequence gap must be assumed for the CmdSN), even though 4590 the CmdSN of the rejected command PDU may be reliably ascertained. 4591 Upon receiving the Reject, the initiator MUST plug the CmdSN gap 4592 in order to continue to use the session. The gap may be plugged 4593 either by transmitting a command PDU with the same CmdSN, or by 4594 aborting the task (see SCS on how an abort may plug a CmdSN gap). 4596 When a data PDU is rejected and its DataSN can be ascertained, a 4597 target MUST advance ExpDataSN for the current data burst if a 4598 recovery R2T is being generated. The target MAY advance its 4599 ExpDataSN if it does not attempt to recover the lost data PDU. 4601 7.4. Error Recovery Considerations for Discovery Sessions 4603 7.4.1. ErrorRecoveryLevel for Discovery Sessions 4605 The negotiation of the key ErrorRecoveryLevel is not required for 4606 Discovery sessions -- i.e., for sessions that negotiated 4607 "SessionType=Discovery" -- because the default value of 0 is 4608 necessary and sufficient for Discovery sessions. It is however 4609 possible that some legacy iSCSI implementations might attempt to 4610 negotiate the ErrorRecoveryLevel key on Discovery sessions. When 4611 such a negotiation attempt is made by the remote side, a compliant 4612 iSCSI implementation MUST propose a value of 0 (zero) in response. 4613 The operational ErrorRecoveryLevel for Discovery sessions thus 4614 MUST 4615 be 0. This naturally follows from the functionality constraints 4616 that Section 4.3 imposes on Discovery sessions. 4618 7.4.2. Reinstatement Semantics for Discovery Sessions 4620 Discovery sessions are intended to be relatively short-lived. 4621 Initiators are not expected to establish multiple Discovery 4622 sessions to the same iSCSI Network Portal. An initiator may use 4623 the same iSCSI Initiator Name and ISID when establishing different 4624 unique sessions with different targets and/or different portal 4625 groups. This behavior is discussed in Section 10.1.1 and is, in 4626 fact, encouraged as conservative reuse of ISIDs. 4628 The ISID RULE in Section 4.4.3 states that there must not be more 4629 than one session with a matching 4-tuple: . While the spirit of the ISID 4631 RULE applies to Discovery sessions the same as it does for Normal 4632 sessions, note that some Discovery sessions differ from the Normal 4633 sessions in two important aspects: 4635 a) Because Appendix C allows a Discovery session to be 4636 established without specifying a TargetName key in the 4637 Login Request PDU (let us call such a session an "Unnamed" 4638 Discovery session), there is no Target Node context to 4639 enforce the ISID RULE. 4641 b) Portal Groups are defined only in the context of a Target 4642 Node. When the TargetName key is NULL-valued (i.e., not 4643 specified), the TargetPortalGroupTag thus cannot be 4644 ascertained to enforce the ISID RULE. 4646 The following two sections describe each of the two scenarios -- 4647 Named Discovery sessions and Unnamed Discovery sessions. 4649 7.4.2.1. Unnamed Discovery Sessions 4651 For Unnamed Discovery sessions, neither the TargetName nor the 4652 TargetPortalGroupTag is available to the targets in order to 4653 enforce the ISID RULE. So the following rule applies. 4655 UNNAMED ISID RULE: Targets MUST enforce the uniqueness of the 4656 following 4-tuple for Unnamed Discovery sessions: . The following semantics are implied by 4658 this uniqueness requirement. 4660 Targets SHOULD allow concurrent establishment of one Discovery 4661 session with each of its Network Portals by the same initiator 4662 port with a given iSCSI Node Name and an ISID. Each of the 4663 concurrent Discovery sessions, if established by the same 4664 initiator port to other Network Portals, MUST be treated as 4665 independent sessions -- i.e., one session MUST NOT reinstate the 4666 other. 4668 A new Unnamed Discovery session that has a matching 4669 to an existing 4670 Discovery session MUST reinstate the existing Unnamed Discovery 4671 session. Note thus that only an Unnamed Discovery session may 4672 reinstate an Unnamed Discovery session. 4674 7.4.2.2. Named Discovery Session 4676 For a Named Discovery session, the TargetName key is specified by 4677 the initiator and thus the target can unambiguously ascertain the 4678 TargetPortalGroupTag as well. Since all the four elements of the 4679 4-tuple are known, the ISID RULE MUST be enforced by targets with 4680 no changes from Section 4.4.3 semantics. A new session with a 4681 matching 4682 thus will reinstate an existing session. Note in this case that 4683 any new iSCSI session (Discovery or Normal) with the matching 4- 4684 tuple may reinstate an existing Named Discovery iSCSI session. 4686 7.4.3. Target PDUs During Discovery 4688 Targets SHOULD NOT send any responses other than a Text Response 4689 and Logout Response on a Discovery session, once in Full Feature 4690 Phase. 4692 Implementation Note: A target may simply drop the connection in a 4693 Discovery session when it would have requested a Logout via an 4694 Async Message on Normal sessions. 4696 7.5. Connection Timeout Management 4698 iSCSI defines two session-global timeout values (in seconds) - 4699 Time2Wait and Time2Retain - that are applicable when an iSCSI Full 4700 Feature Phase connection is taken out of service either 4701 intentionally or by an exception. Time2Wait is the initial 4702 "respite time" before attempting an explicit/implicit Logout for 4703 the CID in question or task reassignment for the affected tasks 4704 (if any). Time2Retain is the maximum time after the initial 4705 respite interval that the task and/or connection state(s) is/are 4706 guaranteed to be maintained on the target to cater to a possible 4707 recovery attempt. Recovery attempts for the connection and/or 4708 task(s) SHOULD NOT be made before Time2Wait seconds, but MUST be 4709 completed within Time2Retain seconds after that initial Time2Wait 4710 waiting period. 4712 7.5.1. Timeouts on Transport Exception Events 4714 A transport connection shutdown or a transport reset without any 4715 preceding iSCSI protocol interactions informing the end-points of 4716 the fact causes a Full Feature Phase iSCSI connection to be 4717 abruptly terminated. The timeout values to be used in this case 4718 are the negotiated values of DefaultTime2Wait (Section 13.15) and 4719 DefaultTime2Retain (Section 13.16) text keys for the session. 4721 7.5.2. Timeouts on Planned Decommissioning 4723 Any planned decommissioning of a Full Feature Phase iSCSI 4724 connection is preceded by either a Logout Response PDU, or an 4725 Async Message PDU. The Time2Wait and Time2Retain field values 4726 (Section 11.15) in a Logout Response PDU, and the Parameter2 and 4727 Parameter3 fields of an Async Message (AsyncEvent types "drop the 4728 connection" or "drop all the connections"; Section 11.9.1) specify 4729 the timeout values to be used in each of these cases. 4731 These timeout values are only applicable for the affected 4732 connection, and the tasks active on that connection. These 4733 timeout values have no bearing on initiator timers (if any) that 4734 are already running on connections or tasks associated with that 4735 session. 4737 7.6. Implicit Termination of Tasks 4739 A target implicitly terminates the active tasks due to iSCSI 4740 protocol dynamics in the following cases: 4742 a) When a connection is implicitly or explicitly logged out 4743 with the reason code of "Close the connection" and there 4744 are active tasks allegiant to that connection. 4746 b) When a connection fails and eventually the connection 4747 state times out (state transition M1 in Section 8.2.2) 4748 and there are active tasks allegiant to that connection. 4750 c) When a successful Logout with the reason code of "remove 4751 the connection for recovery" is performed while there are 4752 active tasks allegiant to that connection, and those 4753 tasks eventually time out after the Time2Wait and 4754 Time2Retain periods without allegiance reassignment. 4756 d) When a connection is implicitly or explicitly logged out 4757 with the reason code of "Close the session" and there are 4758 active tasks in that session. 4760 If the tasks terminated in the above cases a), b), c) and d)are 4761 SCSI tasks, they must be internally terminated as if with CHECK 4762 CONDITION status. This status is only meaningful for appropriately 4763 handling the internal SCSI state and SCSI side effects with 4764 respect to ordering because this status is never communicated back 4765 as a terminating status to the initiator. However additional 4766 actions may have to be taken at SCSI level depending on the SCSI 4767 context as defined by the SCSI standards (e.g., queued commands 4768 and ACA, UA for the next command on the I_T nexus in cases a), b), 4769 and c) etc. - see [SAM2] and [SPC3]). 4771 7.7. Format Errors 4773 The following two explicit violations of PDU layout rules are 4774 format errors: 4776 a) Illegal contents of any PDU header field except the 4777 Opcode (legal values are specified in Section 11). 4778 b) Inconsistent field contents (consistent field contents 4779 are specified in Section 11). 4781 Format errors indicate a major implementation flaw in one of the 4782 parties. 4784 When a target or an initiator receives an iSCSI PDU with a format 4785 error, it MUST immediately terminate all transport connections in 4786 the session either with a connection close or with a connection 4787 reset and escalate the format error to session recovery (see 4788 Section 7.1.4.4). 4790 All initiator-detected PDU construction errors MUST be considered 4791 as format errors. Some examples of such errors are: 4792 - NOP-In with a valid TTT but an invalid LUN 4794 - NOP-In with a valid ITT (i.e., a NOP-In response) and also a 4795 valid TTT 4797 - SCSI Response PDU with Status=CHECK CONDITION, but 4798 DataSegmentLength = 0 4800 7.8. Digest Errors 4802 The discussion of the legal choices in handling digest errors 4803 below excludes session recovery as an explicit option, but either 4804 party detecting a digest error may choose to escalate the error to 4805 session recovery. 4807 When a target or an initiator receives any iSCSI PDU, with a 4808 header digest error, it MUST either discard the header and all 4809 data up to the beginning of a later PDU or close the connection. 4810 Because the digest error indicates that the length field of the 4811 header may have been corrupted, the location of the beginning of a 4812 later PDU needs to be reliably ascertained by other means such as 4813 the operation of a sync and steering layer. 4815 When a target receives any iSCSI PDU with a payload digest error, 4816 it MUST answer with a Reject PDU with a reason code of Data- 4817 Digest-Error and discard the PDU. 4819 - If the discarded PDU is a solicited or unsolicited iSCSI 4820 data PDU (for immediate data in a command PDU, non-data PDU 4821 rule below applies), the target MUST do one of the 4822 following: 4824 i) Request retransmission with a recovery R2T. 4825 ii) Terminate the task with a response PDU with a CHECK 4826 CONDITION Status and an iSCSI Condition of "protocol 4827 service CRC error" (Section 11.4.7.2). If the target 4828 chooses to implement this option, it MUST wait to 4829 receive all the data (signaled by a Data PDU with the 4830 final bit set for all outstanding R2Ts) before sending 4832 the response PDU. A task management command (such as an 4833 abort task) from the initiator during this wait may 4834 also conclude the task. 4835 - No further action is necessary for targets if the discarded 4836 PDU is a non-data PDU. In case of immediate data being 4837 present on a discarded command, the immediate data is 4838 implicitly recovered when the task is retried (see Section 4839 7.2.1) followed by the entire data transfer for the task. 4841 When an initiator receives any iSCSI PDU with a payload digest 4842 error, it MUST discard the PDU. 4844 - If the discarded PDU is an iSCSI data PDU, the initiator 4845 MUST do one of the following: 4847 a) Request the desired data PDU through SNACK. In 4848 response to the SNACK, the target MUST either resend 4849 the data PDU or reject the SNACK with a Reject PDU 4850 with a reason code of "SNACK reject" in which case: 4851 b) If the status has not already been sent for the 4852 command, the target MUST terminate the command with a 4853 CHECK CONDITION Status and an iSCSI Condition of 4854 "SNACK rejected" (Section 11.4.7.2). 4855 c) If the status was already sent, no further action is 4856 necessary for the target. The initiator in this case 4857 MUST wait for the status to be received and then 4858 discard it, so as to internally signal the completion 4859 with CHECK CONDITION Status and an iSCSI Condition of 4860 "protocol service CRC error" (Section 11.4.7.2). 4861 d) Abort the task and terminate the command with an 4862 error. 4864 - If the discarded PDU is a response PDU or an unsolicited PDU 4865 (e.g. Async, Reject), the initiator MUST do one of the 4866 following: 4868 a) Request PDU retransmission with a status SNACK. 4869 b) Logout the connection for recovery and continue the 4870 tasks on a different connection instance as described 4871 in Section 7.2. 4873 c) Logout to close the connection (abort all the 4874 commands associated with the connection). 4876 Note that an unsolicited PDU carries the next StatSN value on 4877 an iSCSI connection, thereby advancing the StatSN. When an 4878 initiator discards one of these PDUs due to a payload digest 4879 error, the entire PDU including the header MUST be discarded. 4880 Consequently, the initiator MUST treat the exception like a 4881 loss of any other solicited response PDU. 4883 7.9. Sequence Errors 4885 When an initiator receives an iSCSI R2T/data PDU with an out of 4886 order R2TSN/DataSN or a SCSI response PDU with an ExpDataSN that 4887 implies missing data PDU(s), it means that the initiator must have 4888 detected a header or payload digest error on one or more earlier 4889 R2T/data PDUs. The initiator MUST address these implied digest 4890 errors as described in Section 7.8. When a target receives a data 4891 PDU with an out of order DataSN, it means that the target must 4892 have hit a header or payload digest error on at least one of the 4893 earlier data PDUs. The target MUST address these implied digest 4894 errors as described in Section 7.8. 4896 When an initiator receives an iSCSI status PDU with an out of 4897 order StatSN that implies missing responses, it MUST address the 4898 one or more missing status PDUs as described in Section 7.8. As a 4899 side effect of receiving the missing responses, the initiator may 4900 discover missing data PDUs. If the initiator wants to recover the 4901 missing data for a command, it MUST NOT acknowledge the received 4902 responses that start from the StatSN of the relevant command, 4903 until it has completed receiving all the data PDUs of the command. 4905 When an initiator receives duplicate R2TSNs (due to proactive 4906 retransmission of R2Ts by the target) or duplicate DataSNs (due to 4907 proactive SNACKs by the initiator), it MUST discard the 4908 duplicates. 4910 7.10. Message Error Checking 4912 In the iSCSI implementations till date, there has been some 4913 uncertainty on the extent to which incoming messages have to be 4914 checked for protocol errors, beyond what is strictly required for 4915 processing the inbound message. This Section addresses this 4916 question. 4918 Unless this document requires it, an iSCSI implementation is not 4919 required to do an exhaustive protocol conformance check on an 4920 incoming iSCSI PDU. The iSCSI implementation especially is not 4921 required to double-check the remote iSCSI implementation's 4922 conformance to protocol requirements. 4924 7.11. SCSI Timeouts 4926 An iSCSI initiator MAY attempt to plug a command sequence gap on 4927 the target end (in the absence of an acknowledgement of the 4928 command by way of ExpCmdSN) before the ULP timeout by retrying the 4929 unacknowledged command, as described in Section 7.2. 4931 On a ULP timeout for a command (that carried a CmdSN of n), if the 4932 iSCSI initiator intends to continue the session it MUST abort the 4933 command by either using an appropriate Task Management function 4934 request for the specific command, or a "close the connection" 4935 Logout. When using an ABORT TASK, if the ExpCmdSN is still less 4936 than (n+1), the target may see the abort request while missing the 4937 original command itself due to one of the following reasons: 4939 - Original command was dropped due to digest error. 4941 - Connection on which the original command was sent was 4942 successfully logged out. On logout, the unacknowledged 4943 commands issued on the connection being logged out are 4944 discarded. 4946 If the abort request is received and the original command is 4947 missing, targets MUST consider the original command with that 4948 RefCmdSN to be received and issue a Task Management response with 4949 the response code: "Function Complete". This response concludes 4950 the task on both ends. If the abort request is received and the 4951 target can determine (based on the Referenced Task Tag) that the 4952 command was received and executed and also that the response was 4953 sent prior to the abort, then the target MUST respond with the 4954 response code of "Task Does Not Exist". 4956 7.12. Negotiation Failures 4958 Text request and response sequences, when used to set/negotiate 4959 operational parameters, constitute the negotiation/parameter 4960 setting. A negotiation failure is considered to be one or more of 4961 the following: 4963 - None of the choices, or the stated value, is acceptable to 4964 one of the sides in the negotiation. 4966 - The text request timed out and possibly terminated. 4968 - The text request was answered with a Reject PDU. 4970 The following two rules should be used to address negotiation 4971 failures: 4973 a) During Login, any failure in negotiation MUST be 4974 considered a login process failure and the Login Phase 4975 MUST be terminated, and with it, the connection. If the 4976 target detects the failure, it must terminate the login 4977 with the appropriate login response code. 4979 b) A failure in negotiation, while in the Full Feature 4980 Phase, will terminate the entire negotiation sequence 4981 that may consist of a series of text requests that use 4982 the same Initiator Task Tag. The operational parameters 4983 of the session or the connection MUST continue to be the 4984 values agreed upon during an earlier successful 4985 negotiation (i.e., any partial results of this 4986 unsuccessful negotiation MUST NOT take effect and MUST be 4987 discarded). 4989 7.13. Protocol Errors 4991 Mapping framed messages over a "stream" connection, such as TCP, 4992 makes the proposed mechanisms vulnerable to simple software 4993 framing errors. On the other hand, the introduction of framing 4994 mechanisms to limit the effects of these errors may be onerous on 4995 performance for simple implementations. Command Sequence Numbers 4996 and the above mechanisms for connection drop and reestablishment 4997 help handle this type of mapping errors. 4999 All violations of iSCSI PDU exchange sequences specified in this 5000 draft are also protocol errors. This category of errors can only 5001 be 5002 addressed by fixing the implementations; iSCSI defines Reject and 5003 response codes to enable this. 5005 7.14. Connection Failures 5007 iSCSI can keep a session in operation if it is able to 5008 keep/establish at least one TCP connection between the initiator 5009 and the target in a timely fashion. Targets and/or initiators may 5010 recognize a failing connection by either transport level means 5011 (TCP), a gap in the command sequence number, a response stream 5012 that is not filled for a long time, or by a failing iSCSI NOP 5013 (acting as a ping). The latter MAY be used periodically to 5014 increase the speed and likelihood of detecting connection 5015 failures. As an example for transport level means, initiators and 5016 targets MAY also use the keep-alive option, see [RFC1122], on the 5017 TCP connection to enable early link failure detection on otherwise 5018 idle links. 5020 On connection failure, the initiator and target MUST do one of the 5021 following: 5023 a) Attempt connection recovery within the session 5024 (Connection Recovery). 5026 b) Logout the connection with the reason code "closes the 5027 connection" (Section 10.14.5), re-issue missing commands, 5028 and implicitly terminate all active commands. This option 5029 requires support for the within-connection recovery class 5030 (Recovery Within-connection). 5032 c) Perform session recovery (Session Recovery). 5034 Either side may choose to escalate to session recovery (via the 5035 initiator dropping all the connections, or via an Async Message 5036 that announces the similar intent from a target), and the other 5037 side MUST give it precedence. On a connection failure, a target 5038 MUST terminate and/or discard all of the active immediate commands 5039 regardless of which of the above options is used (i.e., immediate 5040 commands are not recoverable across connection failures). 5042 7.15. Session Errors 5044 If all of the connections of a session fail and cannot be 5045 reestablished in a short time, or if initiators detect protocol 5046 errors repeatedly, an initiator may choose to terminate a session 5047 and establish a new session. 5049 In this case, the initiator takes the following actions: 5051 - Resets or closes all the transport connections. 5053 - Terminates all outstanding requests with an appropriate 5054 response before initiating a new session. If the same I_T 5055 nexus is intended to be reestablished, the initiator MUST 5056 employ session reinstatement (see Section 6.3.5). 5058 When the session timeout (the connection state timeout for the 5059 last failed connection) happens on the target, it takes the 5060 following actions: 5062 - Resets or closes the TCP connections (closes the session). 5064 - Terminates all active tasks that were allegiant to the 5065 connection(s) that constituted the session. 5067 A target MUST also be prepared to handle a session reinstatement 5068 request from the initiator that may be addressing session errors. 5070 8. State Transitions 5072 iSCSI connections and iSCSI sessions go through several well- 5073 defined states from the time they are created to the time they are 5074 cleared. 5076 The connection state transitions are described in two separate but 5077 dependent state diagrams for ease in understanding. The first 5078 diagram, "standard connection state diagram", describes the 5079 connection state transitions when the iSCSI connection is not 5080 waiting for, or undergoing, a cleanup by way of an explicit or 5081 implicit Logout. The second diagram, "connection cleanup state 5082 diagram", describes the connection state transitions while 5083 performing the iSCSI connection cleanup. 5085 The "session state diagram" describes the state transitions an 5086 iSCSI session would go through during its lifetime, and it depends 5087 on the states of possibly multiple iSCSI connections that 5088 participate in the session. 5090 States and transitions are described in text, tables and diagrams. 5091 The diagrams are used for illustration. The text and the tables 5092 are the governing specification. 5094 8.1. Standard Connection State Diagrams 5096 8.1.1. State Descriptions for Initiators and Targets 5098 State descriptions for the standard connection state diagram are 5099 as follows: 5100 -S1: FREE 5101 -initiator: State on instantiation, or after successful 5102 connection closure. 5103 -target: State on instantiation, or after successful 5104 connection closure. 5105 -S2: XPT_WAIT 5106 -initiator: Waiting for a response to its transport 5107 connection establishment request. 5108 -target: Illegal 5109 -S3: XPT_UP 5110 -initiator: Illegal 5111 -target: Waiting for the Login process to commence. 5113 -S4: IN_LOGIN 5114 -initiator: Waiting for the Login process to conclude, 5115 possibly involving several PDU exchanges. 5116 -target: Waiting for the Login process to conclude, 5117 possibly involving several PDU exchanges. 5118 -S5: LOGGED_IN 5119 -initiator: In Full Feature Phase, waiting for all 5120 internal, iSCSI, and transport events. 5121 -target: In Full Feature Phase, waiting for all internal, 5122 iSCSI, and transport events. 5123 -S6: IN_LOGOUT 5124 -initiator: Waiting for a Logout response. 5125 -target: Waiting for an internal event signaling completion 5126 of logout processing. 5127 -S7: LOGOUT_REQUESTED 5128 -initiator: Waiting for an internal event signaling 5129 readiness to proceed with Logout. 5130 -target: Waiting for the Logout process to start after 5131 having requested a Logout via an Async Message. 5132 -S8: CLEANUP_WAIT 5133 -initiator: Waiting for the context and/or resources to 5134 initiate the cleanup processing for this CSM. 5135 -target: Waiting for the cleanup process to start for this 5136 CSM. 5137 8.1.2. State Transition Descriptions for Initiators and Targets 5139 -T1: 5140 -initiator: Transport connect request was made (e.g., TCP 5141 SYN sent). 5142 -target: Illegal 5143 -T2: 5144 -initiator: Transport connection request timed out, a 5145 transport reset was received, or an internal event of 5146 receiving a Logout response (success) on another connection 5147 for a "close the session" Logout request was received. 5148 -target:Illegal 5149 -T3: 5150 -initiator: Illegal 5151 -target: Received a valid transport connection request that 5152 establishes the transport connection. 5153 -T4: 5155 -initiator: Transport connection established, thus 5156 prompting the initiator to start the iSCSI Login. 5157 -target: Initial iSCSI Login request was received. 5158 -T5: 5159 -initiator: The final iSCSI Login response with a Status- 5160 Class of zero was received. 5161 -target: The final iSCSI Login request to conclude the 5162 Login Phase was received, thus prompting the target to send 5163 the final iSCSI Login response with a Status-Class of zero. 5164 -T6: 5165 -initiator: Illegal 5166 -target: Timed out waiting for an iSCSI Login, transport 5167 disconnect indication was received, transport reset was 5168 received, or an internal event indicating a transport 5169 timeout was received. In all these cases, the connection is 5170 to be closed. 5171 -T7: 5172 -initiator - one of the following events caused the 5173 transition: 5174 a) The final iSCSI Login response was received with a 5175 non-zero Status-Class. 5176 b) Login timed out. 5177 c) A transport disconnect indication was received. 5178 d) A transport reset was received. 5179 e) An internal event indicating a transport timeout was 5180 received. 5181 f) An internal event of receiving a Logout response 5182 (success) on another connection for a "close the 5183 session" Logout request was received. 5185 In all these cases, the transport connection is closed. 5187 -target - one of the following events caused the 5188 transition: 5189 a) The final iSCSI Login request to conclude the Login 5190 Phase was received, prompting the target to send the 5191 final iSCSI Login response with a non-zero Status- 5192 Class. 5193 b) Login timed out. 5194 c) Transport disconnect indication was received. 5196 d) Transport reset was received. 5197 e) An internal event indicating a transport timeout was 5198 received. 5199 f) On another connection, a "close the session" Logout 5200 request was received. 5202 In all these cases, the connection is to be closed. 5203 -T8: 5204 -initiator: An internal event of receiving a Logout 5205 response (success) on another connection for a "close the 5206 session" Logout request was received, thus closing this 5207 connection requiring no further cleanup. 5208 -target: An internal event of sending a Logout response 5209 (success) on another connection for a "close the session" 5210 Logout request was received, or an internal event of a 5211 successful connection/session reinstatement is received, 5212 thus prompting the target to close this connection cleanly. 5213 -T9, T10: 5214 -initiator: An internal event that indicates the readiness 5215 to start the Logout process was received, thus prompting an 5216 iSCSI Logout to be sent by the initiator. 5217 -target: An iSCSI Logout request was received. 5218 -T11, T12: 5219 -initiator: Async PDU with AsyncEvent "Request Logout" was 5220 received. 5221 -target: An internal event that requires the 5222 decommissioning of the connection is received, thus causing 5223 an Async PDU with an AsyncEvent "Request Logout" to be 5224 sent. 5225 -T13: 5226 -initiator: An iSCSI Logout response (success) was 5227 received, or an internal event of receiving a Logout 5228 response (success) on another connection for a "close the 5229 session" Logout request was received. 5230 -target: An internal event was received that indicates 5231 successful processing of the Logout, which prompts an iSCSI 5232 Logout response (success) to be sent; an internal event of 5233 sending a Logout response (success) on another connection 5234 for a "close the session" Logout request was received; or 5235 an internal event of a successful connection/session 5236 reinstatement is received. In all these cases, the 5237 transport connection is closed. 5239 -T14: 5240 -initiator: Async PDU with AsyncEvent "Request Logout" was 5241 received again. 5242 -target: Illegal 5243 -T15, T16: 5244 -initiator: One or more of the following events caused this 5245 transition: 5246 a) Internal event that indicates a transport connection 5247 timeout was received thus prompting transport RESET 5248 or transport connection closure. 5249 b) A transport RESET. 5250 c) A transport disconnect indication. 5251 d) Async PDU with AsyncEvent "Drop connection" (for 5252 this CID). 5253 e) Async PDU with AsyncEvent "Drop all connections". 5254 -target: One or more of the following events caused this 5255 transition: 5256 a) Internal event that indicates a transport connection 5257 timeout was received, thus prompting transport RESET 5258 or transport connection closure. 5259 b) An internal event of a failed connection/session 5260 reinstatement is received. 5261 c) A transport RESET. 5262 d) A transport disconnect indication. 5263 e) Internal emergency cleanup event was received which 5264 prompts an Async PDU with AsyncEvent "Drop 5265 connection" (for this CID), or event "Drop all 5266 connections". 5268 -T17: 5269 -initiator: One or more of the following events caused this 5270 transition: 5271 a) Logout response, (failure i.e., a non-zero status) 5272 was received, or Logout timed out. 5273 b) Any of the events specified for T15 and T16. 5274 -target: One or more of the following events caused this 5275 transition: 5277 a) Internal event that indicates a failure of the 5278 Logout processing was received, which prompts a 5279 Logout response (failure, i.e., a non-zero status) 5280 to be sent. 5281 b) Any of the events specified for T15 and T16. 5282 -T18: 5283 -initiator: An internal event of receiving a Logout 5284 response (success) on another connection for a "close the 5285 session" Logout request was received. 5287 -target: An internal event of sending a Logout response 5288 (success) on another connection for a "close the session" 5289 Logout request was received, or an internal event of a 5290 successful connection/session reinstatement is received. 5291 In both these cases, the connection is closed. 5293 The CLEANUP_WAIT state (S8) implies that there are possible iSCSI 5294 tasks that have not reached conclusion and are still considered 5295 busy. 5297 8.1.3. Standard Connection State Diagram for an Initiator 5299 Symbolic names for States: 5301 S1: FREE 5303 S2: XPT_WAIT 5305 S4: IN_LOGIN 5307 S5: LOGGED_IN 5309 S6: IN_LOGOUT 5311 S7: LOGOUT_REQUESTED 5313 S8: CLEANUP_WAIT 5315 States S5, S6, and S7 constitute the Full Feature Phase operation 5316 of the connection. 5318 The state diagram is as follows: 5320 -------<-------------+ 5321 +--------->/ S1 \<----+ | 5322 T13| +->\ /<-+ \ | 5323 | / ---+--- \ \ | 5324 | / | T2 \ | | 5325 | T8 | |T1 | | | 5326 | | | / |T7 | 5327 | | | / | | 5328 | | | / | | 5329 | | V / / | 5330 | | ------- / / | 5331 | | / S2 \ / | 5332 | | \ / / | 5333 | | ---+--- / | 5334 | | |T4 / | 5335 | | V / | T18 5336 | | ------- / | 5337 | | / S4 \ | 5338 | | \ / | 5339 | | ---+--- | T15 5340 | | |T5 +--------+---------+ 5341 | | | /T16+-----+------+ | 5342 | | | / -+-----+--+ | | 5343 | | | / / S7 \ |T12| | 5344 | | | / +->\ /<-+ V V 5345 | | | / / -+----- ------- 5346 | | | / /T11 |T10 / S8 \ 5347 | | V / / V +----+ \ / 5348 | | ---+-+- ----+-- | ------- 5349 | | / S5 \T9 / S6 \<+ ^ 5350 | +-----\ /--->\ / T14 | 5351 | ------- --+----+------+T17 5352 +---------------------------+ 5354 The following state transition table represents the above diagram. 5355 Each row represents the starting state for a given transition, 5356 which after taking a transition marked in a table cell would end 5357 in the state represented by the column of the cell. For example, 5358 from state S1, the connection takes the T1 transition to arrive at 5359 state S2. The fields marked "-" correspond to undefined 5360 transitions. 5362 +----+---+---+---+---+----+---+ 5363 |S1 |S2 |S4 |S5 |S6 |S7 |S8 | 5364 ---+----+---+---+---+---+----+---+ 5365 S1| - |T1 | - | - | - | - | - | 5366 ---+----+---+---+---+---+----+---+ 5367 S2|T2 |- |T4 | - | - | - | - | 5368 ---+----+---+---+---+---+----+---+ 5369 S4|T7 |- |- |T5 | - | - | - | 5370 ---+----+---+---+---+---+----+---+ 5371 S5|T8 |- |- | - |T9 |T11 |T15| 5372 ---+----+---+---+---+---+----+---+ 5373 S6|T13 |- |- | - |T14|- |T17| 5374 ---+----+---+---+---+---+----+---+ 5375 S7|T18 |- |- | - |T10|T12 |T16| 5376 ---+----+---+---+---+---+----+---+ 5377 S8| - |- |- | - | - | - | - | 5378 ---+----+---+---+---+---+----+---+ 5380 8.1.4. Standard Connection State Diagram for a Target 5382 Symbolic names for States: 5383 S1: FREE 5385 S3: XPT_UP 5387 S4: IN_LOGIN 5389 S5: LOGGED_IN 5391 S6: IN_LOGOUT 5393 S7: LOGOUT_REQUESTED 5395 S8: CLEANUP_WAIT 5397 States S5, S6, and S7 constitute the Full Feature Phase operation 5398 of the connection. 5400 The state diagram is as follows: 5402 -------<-------------+ 5403 +--------->/ S1 \<----+ | 5404 T13| +->\ /<-+ \ | 5405 | / ---+--- \ \ | 5406 | / | T6 \ | | 5407 | T8 | |T3 | | | 5408 | | | / |T7 | 5409 | | | / | | 5410 | | | / | | 5411 | | V / / | 5412 | | ------- / / | 5413 | | / S3 \ / | 5414 | | \ / / | T18 5415 | | ---+--- / | 5416 | | |T4 / | 5417 | | V / | 5418 | | ------- / | 5419 | | / S4 \ | 5420 | | \ / | 5421 | | ---+--- T15 | 5422 | | |T5 +--------+---------+ 5423 | | | /T16+-----+------+ | 5424 | | | / -+-----+---+ | | 5425 | | | / / S7 \ |T12| | 5426 | | | / +->\ /<-+ V V 5427 | | | / / -+----- ------- 5428 | | | / /T11 |T10 / S8 \ 5429 | | V / / V \ / 5430 | | ---+-+- ------- ------- 5431 | | / S5 \T9 / S6 \ ^ 5432 | +-----\ /--->\ / | 5433 | ------- --+----+--------+T17 5434 +---------------------------+ 5436 The following state transition table represents the above diagram, 5437 and follows the conventions described for the initiator diagram. 5439 +----+---+---+---+---+----+---+ 5440 |S1 |S3 |S4 |S5 |S6 |S7 |S8 | 5441 ---+----+---+---+---+---+----+---+ 5442 S1| - |T3 | - | - | - | - | - | 5443 ---+----+---+---+---+---+----+---+ 5444 S3|T6 |- |T4 | - | - | - | - | 5445 ---+----+---+---+---+---+----+---+ 5446 S4|T7 |- |- |T5 | - | - | - | 5447 ---+----+---+---+---+---+----+---+ 5448 S5|T8 |- |- | - |T9 |T11 |T15| 5449 ---+----+---+---+---+---+----+---+ 5450 S6|T13 |- |- | - |- |- |T17| 5451 ---+----+---+---+---+---+----+---+ 5452 S7|T18 |- |- | - |T10|T12 |T16| 5453 ---+----+---+---+---+---+----+---+ 5454 S8| - |- |- | - | - | - | - | 5455 ---+----+---+---+---+---+----+---+ 5457 8.2. Connection Cleanup State Diagram for Initiators and Targets 5459 Symbolic names for states: 5461 R1: CLEANUP_WAIT (same as S8) 5463 R2: IN_CLEANUP 5465 R3: FREE (same as S1) 5467 Whenever a connection state machine in cleanup (let's call it CSM- 5468 C) enters the CLEANUP_WAIT state (S8), it must go through the 5469 state transitions described in the connection cleanup state 5470 diagram either a) using a separate full-feature phase connection 5471 (let's call it CSM-E, for explicit) in the LOGGED_IN state in the 5472 same session, or b) using a new transport connection (let's call 5473 it CSM-I, for implicit) in the FREE state that is to be added to 5474 the same session. In the CSM-E case, an explicit logout for the 5475 CID that corresponds to CSM-C (either as a connection or session 5476 logout) needs to be performed to complete the cleanup. In the CSM- 5477 I case, an implicit logout for the CID that corresponds to CSM-C 5478 needs to be performed by way of connection reinstatement (Section 5479 6.3.4) for that CID. In either case, the protocol exchanges on 5480 CSM-E or CSM-I determine the state transitions for CSM-C. 5481 Therefore, this cleanup state diagram is only applicable to the 5482 instance of the connection in cleanup (i.e., CSM-C). In the case 5483 of an implicit logout for example, CSM-C reaches FREE (R3) at the 5484 time CSM-I reaches LOGGED_IN. In the case of an explicit logout, 5485 CSM-C reaches FREE (R3) when CSM-E receives a successful logout 5486 response while continuing to be in the LOGGED_IN state. 5488 An initiator must initiate an explicit or implicit connection 5489 logout for a connection in the CLEANUP_WAIT state, if the 5490 initiator intends to continue using the associated iSCSI session. 5492 The following state diagram applies to both initiators and 5493 targets. 5495 ------- 5496 / R1 \ 5497 +--\ /<-+ 5498 / ---+--- \ 5499 / | \ M3 5500 M1 | |M2 | 5501 | | / 5502 | | / 5503 | | / 5504 | V / 5505 | ------- / 5506 | / R2 \ 5507 | \ / 5508 | ------- 5509 | | 5510 | |M4 5511 | | 5512 | | 5513 | | 5514 | V 5515 | ------- 5516 | / R3 \ 5517 +---->\ / 5518 ------- 5520 The following state transition table represents the above diagram, 5521 and follows the same conventions as in earlier sections. 5523 +----+----+----+ 5524 |R1 |R2 |R3 | 5525 -----+----+----+----+ 5526 R1 | - |M2 |M1 | 5527 -----+----+----+----+ 5528 R2 |M3 | - |M4 | 5529 -----+----+----+----+ 5530 R3 | - | - | - | 5531 -----+----+----+----+ 5533 8.2.1. State Descriptions for Initiators and Targets 5535 -R1: CLEANUP_WAIT (Same as S8) 5536 -initiator: Waiting for the internal event to initiate the 5537 cleanup processing for CSM-C. 5538 -target: Waiting for the cleanup process to start for CSM- 5539 C. 5540 -R2: IN_CLEANUP 5541 -initiator: Waiting for the connection cleanup process to 5542 conclude for CSM-C. 5543 -target: Waiting for the connection cleanup process to 5544 conclude for CSM-C. 5545 -R3: FREE (Same as S1) 5546 -initiator: End state for CSM-C. 5547 -target: End state for CSM-C. 5549 8.2.2. State Transition Descriptions for Initiators and Targets 5551 -M1: One or more of the following events was received: 5552 -initiator: 5553 -An internal event that indicates connection state 5554 timeout. 5555 -An internal event of receiving a successful Logout 5556 response on a different connection for a "close the 5557 session" Logout. 5558 -target: 5559 -An internal event that indicates connection state 5560 timeout. 5561 -An internal event of sending a Logout response 5562 (success) on a different connection for a "close the 5563 session" Logout request. 5565 -M2: An implicit/explicit logout process was initiated by the 5566 initiator. 5567 -In CSM-I usage: 5568 -initiator: An internal event requesting the connection 5569 (or session) reinstatement was received, thus prompting 5570 a connection (or session) reinstatement Login to be 5571 sent transitioning CSM-I to state IN_LOGIN. 5572 -target: A connection/session reinstatement Login was 5573 received while in state XPT_UP. 5574 -In CSM-E usage: 5576 -initiator: An internal event that indicates that an 5577 explicit logout was sent for this CID in state 5578 LOGGED_IN. 5579 -target: An explicit logout was received for this CID 5580 in state LOGGED_IN. 5581 -M3: Logout failure detected 5582 -In CSM-I usage: 5583 -initiator: CSM-I failed to reach LOGGED_IN and arrived 5584 into FREE instead. 5585 -target: CSM-I failed to reach LOGGED_IN and arrived 5586 into FREE instead. 5587 -In CSM-E usage: 5588 -initiator: CSM-E either moved out of LOGGED_IN, or 5589 Logout timed out and/or aborted, or Logout response 5590 (failure) was received. 5591 -target: CSM-E either moved out of LOGGED_IN, Logout 5592 timed out and/or aborted, or an internal event that 5593 indicates a failed Logout processing was received. A 5594 Logout response (failure) was sent in the last case. 5596 -M4: Successful implicit/explicit logout was performed. 5597 - In CSM-I usage: 5598 -initiator: CSM-I reached state LOGGED_IN, or an 5599 internal event of receiving a Logout response (success) 5600 on another connection for a "close the session" Logout 5601 request was received. 5602 -target: CSM-I reached state LOGGED_IN, or an internal 5603 event of sending a Logout response (success) on a 5604 different connection for a "close the session" Logout 5605 request was received. 5606 - In CSM-E usage: 5607 -initiator: CSM-E stayed in LOGGED_IN and received a 5608 Logout response (success), or an internal event of 5609 receiving a Logout response (success) on another 5610 connection for a "close the session" Logout request was 5611 received. 5612 -target: CSM-E stayed in LOGGED_IN and an internal 5613 event indicating a successful Logout processing was 5614 received, or an internal event of sending a Logout 5615 response (success) on a different connection for a 5616 "close the session" Logout request was received. 5618 8.3. Session State Diagrams 5620 8.3.1. Session State Diagram for an Initiator 5622 Symbolic Names for States: 5624 Q1: FREE 5626 Q3: LOGGED_IN 5628 Q4: FAILED 5630 State Q3 represents the Full Feature Phase operation of the 5631 session. 5633 The state diagram is as follows: 5635 ------- 5636 / Q1 \ 5637 +------>\ /<-+ 5638 / ---+--- | 5639 / | |N3 5640 N6 | |N1 | 5641 | | | 5642 | N4 | | 5643 | +----------+ | / 5644 | | | | / 5645 | | | | / 5646 | | V V / 5647 -+--+-- -----+- 5648 / Q4 \ N5 / Q3 \ 5649 \ /<------\ / 5650 ------- ------- 5652 The state transition table is as follows: 5654 +---+---+---+ 5655 |Q1 |Q3 |Q4 | 5656 -----+---+---+---+ 5657 Q1 | - |N1 | - | 5658 -----+---+---+---+ 5659 Q3 |N3 | - |N5 | 5660 -----+---+---+---+ 5661 Q4 |N6 |N4 | - | 5662 -----+---+---+---+ 5664 8.3.2. Session State Diagram for a Target 5666 Symbolic Names for States: 5668 Q1: FREE 5670 Q2: ACTIVE 5672 Q3: LOGGED_IN 5674 Q4: FAILED 5676 Q5: IN_CONTINUE 5678 State Q3 represents the Full Feature Phase operation of the 5679 session. 5681 The state diagram is as follows: 5683 ------- 5684 +------------------>/ Q1 \ 5685 / +-------------->\ /<-+ 5686 | | ---+--- | 5687 | | ^ | |N3 5688 N 6 | |N11 N9| V N1 | 5689 | | +------ | 5690 | | / Q2 \ | 5691 | | \ / | 5692 | --+---- +--+--- | 5693 | / Q5 \ | | 5694 | \ / N10 | | 5695 | +-+---+------------+ | N2 / 5696 | ^ | | | / 5697 | N7| |N8 | | / 5698 | | | | V / 5699 -+---+-V V------+- 5700 / Q4 \ N5 / Q3 \ 5701 \ /<-------------\ / 5702 ------- ------- 5704 The state transition table is as follows: 5706 +----+----+----+----+----+ 5707 |Q1 |Q2 |Q3 |Q4 |Q5 | 5708 -----+----+----+----+----+----+ 5709 Q1 | - |N1 | - | - | - | 5710 -----+----+----+----+----+----+ 5711 Q2 |N9 | - |N2 | - | - | 5712 -----+----+----+----+----+----+ 5713 Q3 |N3 | - | - |N5 | - | 5714 -----+----+----+----+----+----+ 5715 Q4 |N6 | - | - | - |N7 | 5716 -----+----+----+----+----+----+ 5717 Q5 |N11 | - |N10 |N8 | - | 5718 -----+----+----+----+----+----+ 5720 8.3.3. State Descriptions for Initiators and Targets 5722 -Q1: FREE 5723 -initiator: State on instantiation or after cleanup. 5725 -target: State on instantiation or after cleanup. 5726 -Q2: ACTIVE 5727 -initiator: Illegal. 5728 -target: The first iSCSI connection in the session 5729 transitioned to IN_LOGIN, waiting for it to complete the 5730 login process. 5731 -Q3: LOGGED_IN 5732 -initiator: Waiting for all session events. 5733 -target: Waiting for all session events. 5734 -Q4: FAILED 5735 -initiator: Waiting for session recovery or session 5736 continuation. 5737 -target: Waiting for session recovery or session 5738 continuation. 5739 -Q5: IN_CONTINUE 5740 -initiator: Illegal. 5741 -target: Waiting for session continuation attempt to reach 5742 a conclusion. 5744 8.3.4. State Transition Descriptions for Initiators and Targets 5746 -N1: 5747 -initiator: At least one transport connection reached the 5748 LOGGED_IN state. 5749 -target: The first iSCSI connection in the session had 5750 reached the IN_LOGIN state. 5751 -N2: 5752 -initiator: Illegal. 5753 -target: At least one iSCSI connection reached the 5754 LOGGED_IN state. 5755 -N3: 5756 -initiator: Graceful closing of the session via session 5757 closure (Section 6.3.6). 5758 -target: Graceful closing of the session via session 5759 closure (Section 6.3.6) or a successful session 5760 reinstatement cleanly closed the session. 5761 -N4: 5762 -initiator: A session continuation attempt succeeded. 5763 -target: Illegal. 5764 -N5: 5766 -initiator: Session failure (Section 6.3.6) occurred. 5767 -target: Session failure (Section 6.3.6) occurred. 5768 -N6: 5769 -initiator: Session state timeout occurred, or a session 5770 reinstatement cleared this session instance. This results 5771 in the freeing of all associated resources and the session 5772 state is discarded. 5773 -target: Session state timeout occurred, or a session 5774 reinstatement cleared this session instance. This results 5775 in the freeing of all associated resources and the session 5776 state is discarded. 5777 -N7: 5778 -initiator: Illegal. 5779 -target: A session continuation attempt is initiated. 5780 -N8: 5781 -initiator: Illegal. 5782 -target: The last session continuation attempt failed. 5783 -N9: 5784 -initiator: Illegal. 5785 -target: Login attempt on the leading connection failed. 5786 -N10: 5787 -initiator: Illegal. 5788 -target: A session continuation attempt succeeded. 5789 -N11: 5790 -initiator: Illegal. 5791 -target: A successful session reinstatement cleanly closed 5792 the session. 5794 9. Security Considerations 5796 Historically, native storage systems have not had to consider 5797 security because their environments offered minimal security 5798 risks. That is, these environments consisted of storage devices 5799 either directly attached to hosts or connected via a Storage Area 5800 Network (SAN) distinctly separate from the communications network. 5801 The use of storage protocols, such as SCSI, over IP-networks 5802 requires that security concerns be addressed. iSCSI 5803 implementations must provide means of protection against active 5804 attacks (e.g., pretending to be another identity, message 5805 insertion, deletion, modification, and replaying) and passive 5806 attacks (e.g.,eavesdropping, gaining advantage by analyzing the 5807 data sent over the line). 5809 Although technically possible, iSCSI SHOULD NOT be configured 5810 without security, specifically in-band authentication, see Section 5811 9.2. iSCSI configured without security should be confined to 5812 closed environments that have very limited and well controlled 5813 security risks. [RFC3723] specifies the mechanisms that must be 5814 used in order to mitigate risks fully described in that document. 5816 The following Section describes the security mechanisms provided 5817 by an iSCSI implementation. 5819 9.1. iSCSI Security Mechanisms 5821 The entities involved in iSCSI security are the initiator, target, 5822 and the IP communication end points. iSCSI scenarios in which 5823 multiple initiators or targets share a single communication end 5824 point are expected. To accommodate such scenarios, iSCSI uses two 5825 separate security mechanisms: In-band authentication between the 5826 initiator and the target at the iSCSI connection level (carried 5827 out by exchange of iSCSI Login PDUs), and packet protection 5828 (integrity, authentication, and confidentiality) by IPsec at the 5829 IP level. The two security mechanisms complement each other. The 5830 in-band authentication provides end-to-end trust (at login time) 5831 between the iSCSI initiator and the target while IPsec provides a 5832 secure channel between the IP communication end points. iSCSI can 5833 be used to access sensitive information for which significant 5834 security protection is appropriate. As further specified in the 5835 rest of this security considerations section, both iSCSI security 5836 mechanisms are mandatory to implement (MUST). Use of in-band 5837 authentication is strongly recommended (SHOULD). In contrast, use 5838 of IPsec is optional (MAY) as the security risks that it addresses 5839 may only be present over a subset of the networks used by an iSCSI 5840 connection or a session; a specific example is that when an iSCSI 5841 session spans data centers, IPsec VPN gateways at the data center 5842 boundaries to protect the WAN connectivity between data centers 5843 may be appropriate in combination with in-band iSCSI 5844 authentication. 5846 Further details on typical iSCSI scenarios and the relation 5847 between the initiators, targets, and the communication end points 5848 can be found in [RFC3723]. 5850 9.2. In-band Initiator-Target Authentication 5852 During login, the target MAY authenticate the initiator and the 5853 initiator MAY authenticate the target. The authentication is 5854 performed on every new iSCSI connection by an exchange of iSCSI 5855 Login PDUs using a negotiated authentication method. 5857 The authentication method cannot assume an underlying IPsec 5858 protection, because IPsec is optional to use. An attacker should 5859 gain as little advantage as possible by inspecting the 5860 authentication phase PDUs. Therefore, a method using clear text 5861 (or equivalent) passwords MUST NOT be used; on the other hand, 5862 identity protection is not strictly required. 5864 The authentication mechanism protects against an unauthorized 5865 login to storage resources by using a false identity (spoofing). 5866 Once the authentication phase is completed, if the underlying 5867 IPsec is not used, all PDUs are sent and received in clear. The 5868 authentication mechanism alone (without underlying IPsec) should 5869 only be used when there is no risk of eavesdropping, message 5870 insertion, deletion, modification, and replaying. 5872 Section 11 defines several authentication methods and the exact 5873 steps that must be followed in each of them, including the iSCSI- 5874 text-keys and their allowed values in each step. Whenever an iSCSI 5875 initiator gets a response whose keys, or their values, are not 5876 according to the step definition, it MUST abort the connection. 5878 Whenever an iSCSI target gets a response whose keys, or their 5879 values, are not according to the step definition, it MUST answer 5880 with a Login reject with the "Initiator Error" or "Missing 5881 Parameter" status. These statuses are not intended for 5882 cryptographically incorrect values such as the CHAP response, for 5883 which "Authentication Failure" status MUST be specified. The 5884 importance of this rule can be illustrated in CHAP with target 5885 authentication (see Section 12.1.3) where the initiator would have 5886 been able to conduct a reflection attack by omitting his response 5887 key (CHAP_R) using the same CHAP challenge as the target and 5888 reflecting the target's response back to the target. In CHAP, this 5889 is prevented because the target must answer the missing CHAP_R key 5890 with a Login reject with the "Missing Parameter" status. 5892 For some of the authentication methods, a key specifies the 5893 identity of the iSCSI initiator or target for authentication 5894 purposes. The value associated with that key MAY be different from 5895 the iSCSI Name and SHOULD be configurable. (CHAP_N, see Section 5896 12.1.3 and SRP_U, see Section 12.1.2). For this reason, iSCSI 5897 implementations SHOULD manage authentication in a way that 5898 impersonation across iSCSI Names via these authentication 5899 identities is not possible. Specifically, implementations SHOULD 5900 allow configuration of an authentication identity for a Name if 5901 different, and authentication credentials for that identity. 5902 During the login time, implementations SHOULD verify the Name-to- 5903 identity relationship in addition to authenticating the identity 5904 through the negotiated authentication method. 5906 When an iSCSI session has multiple TCP connections, either 5907 concurrently or sequentially, the authentication method and 5908 identities should not vary among the connections. Therefore, all 5909 connections in an iSCSI session SHOULD use the same authentication 5910 method, iSCSI Name and authentication identity (for authentication 5911 methods that use an authentication identity). Implementations 5912 SHOULD check this and cause an authentication failure on a new 5913 connection that uses a different authentication method, iSCSI 5914 Name or authentication identity from those already used in the 5915 session. In addition, implementations SHOULD NOT support both 5916 authenticated and unauthenticated TCP connections in the same 5917 iSCSI session, added either concurrently or sequentially to the 5918 session. 5920 9.2.1. CHAP Considerations 5922 Compliant iSCSI initiators and targets MUST implement the CHAP 5923 authentication method [RFC1994] (according to Section 12.1.3 5924 including the target authentication option). 5926 When CHAP is performed over a non-encrypted channel, it is 5927 vulnerable to an off-line dictionary attack. Implementations MUST 5928 support use of up to 128 bit random CHAP secrets, including the 5929 means to generate such secrets and to accept them from an external 5930 generation source. Implementations MUST NOT provide secret 5931 generation (or expansion) means other than random generation. 5933 An administrative entity of an environment in which CHAP is used 5934 with a secret that has less than 96 random bits MUST enforce IPsec 5935 encryption (according to the implementation requirements in 5936 Confidentiality) to protect the connection. Moreover, in this case 5937 IKE authentication with group pre-shared cryptographic keys SHOULD 5938 NOT be used unless it is not essential to protect group members 5939 against off-line dictionary attacks by other members. 5941 CHAP secrets MUST be an integral number of bytes (octets). A 5942 compliant implementation SHOULD NOT continue with the login step 5943 in which it should send a CHAP response (CHAP_R, Section 12.1.3) 5944 unless it can verify that the CHAP secret is at least 96 bits, or 5945 that IPsec encryption is being used to protect the connection. 5947 Any CHAP secret used for initiator authentication MUST NOT be 5948 configured for authentication of any target, and any CHAP secret 5949 used for target authentication MUST NOT be configured for 5950 authentication of any initiator. If the CHAP response received by 5951 one end of an iSCSI connection is the same as the CHAP response 5952 that the receiving endpoint would have generated for the same CHAP 5953 challenge, the response MUST be treated as an authentication 5954 failure and cause the connection to close (this ensures that the 5955 same CHAP secret is not used for authentication in both 5956 directions). Also, if an iSCSI implementation can function as 5957 both initiator and target, different CHAP secrets and identities 5958 MUST be configured for these two roles. The following is an 5959 example of the attacks prevented by the above requirements: 5961 a) Rogue wants to impersonate Storage to Alice, and knows 5962 that a single secret is used for both directions of 5963 Storage-Alice authentication. 5965 b) Rogue convinces Alice to open two connections to Rogue, 5966 and Rogue identifies itself as Storage on both 5967 connections. 5969 c) Rogue issues a CHAP challenge on connection 1, waits for 5970 Alice to respond, and then reflects Alice's challenge as 5971 the initial challenge to Alice on connection 2. 5973 d) If Alice doesn't check for the reflection across 5974 connections, Alice's response on connection 2 enables 5975 Rogue to impersonate Storage on connection 1, even though 5976 Rogue does not know the Alice-Storage CHAP secret. 5978 Originators MUST NOT reuse the CHAP challenge sent by the 5979 Responder for the other direction of a bidirectional 5980 authentication. Responders MUST check for this condition and close 5981 the iSCSI TCP connection if it occurs. 5983 The same CHAP secret SHOULD NOT be configured for authentication 5984 of multiple initiators or multiple targets, as this enables any of 5985 them to impersonate any other one of them, and compromising one of 5986 them enables the attacker to impersonate any of them. It is 5987 recommended that iSCSI implementations check for use of identical 5988 CHAP secrets by different peers when this check is feasible, and 5989 take appropriate measures to warn users and/or administrators when 5990 this is detected. 5992 When an iSCSI initiator or target authenticates itself to 5993 counterparts in multiple administrative domains, it SHOULD use a 5994 different CHAP secret for each administrative domain to avoid 5995 propagating security compromises across domains. 5997 Within a single administrative domain: 5999 - A single CHAP secret MAY be used for authentication of an 6000 initiator to multiple targets. 6002 - A single CHAP secret MAY be used for an authentication of a 6003 target to multiple initiators when the initiators use an 6004 external server (e.g., RADIUS, [RFC2865]) to verify the 6005 target's CHAP responses and do not know the target's CHAP 6006 secret. 6008 If an external response verification server (e.g., RADIUS) is not 6009 used, employing a single CHAP secret for authentication of a 6010 target to multiple initiators requires that all such initiators 6011 know that target secret. Any of these initiators can impersonate 6012 the target to any other such initiator, and compromise of such an 6013 initiator enables an attacker to impersonate the target to all 6014 such initiators. Targets SHOULD use separate CHAP secrets for 6015 authentication to each initiator when such risks are of concern; 6016 in this situation it may be useful to configure a separate logical 6017 iSCSI target with its own iSCSI Node Name for each initiator or 6018 group of initiators among which such separation is desired. 6020 The above requirements strengthen the security properties of CHAP 6021 authentication for iSCSI by comparison to the basic CHAP 6022 authentication mechanism [RFC1994]. It is very important to 6023 adhere to these requirements, especially the requirements for 6024 strong (large randomly generated) CHAP secrets, as iSCSI 6025 implementations and deployments that fail to use strong CHAP 6026 secrets are likely to be highly vulnerable to off-line dictionary 6027 attacks on CHAP secrets. 6029 Replacement of CHAP with a better authentication mechanism is 6030 anticipated in a future version of iSCSI. The FC-SP-2 standard 6031 [FC-SP-2] has specified the EAP-GPSK authentication mechanism 6032 [RFC5433] as an alternative to (and possible future replacement 6033 for) Fibre Channel's similar usage of strengthened CHAP. Another 6034 possible replacement for CHAP is a secure password mechanism, 6035 e.g., an updated version of iSCSI's current SRP authentication 6036 mechanism. 6038 9.2.2. SRP Considerations 6040 The strength of the SRP authentication method (specified in 6041 [RFC2945]) is dependent on the characteristics of the group being 6042 used (i.e., the prime modulus N and generator g). As described in 6043 [RFC2945], N is required to be a Sophie-German prime (of the form 6044 N = 2q + 1, where q is also prime) and the generator g is a 6045 primitive root of GF(n). In iSCSI authentication, the prime 6046 modulus N MUST be at least 768 bits. 6048 The list of allowed SRP groups is provided in [RFC3723]. 6050 9.2.3. Kerberos Considerations 6052 iSCSI uses raw Kerberos V5 [RFC4120] for authenticating a client 6053 (iSCSI initiator) principal to a service (iSCSI target) principal. 6054 Note that iSCSI does not use the Generic Security Services 6055 Application Programming Interface (GSS-API) [RFC2743] nor the 6056 Kerberos V5 GSS-API security mechanism [RFC4121]. This means that 6057 iSCSI implementations supporting the KRB5 AuthMethod (Section 6058 12.1) are directly involved in the Kerberos protocol. When 6059 Kerberos V5 is used for authentication, the following actions MUST 6060 be performed as specified in [RFC4120]: 6062 Target MUST validate the KRB_AP_REQ to ensure that the 6063 initiator can be trusted 6065 When mutual authentication is selected, the initiator MUST 6066 validate KRB_AP_REP to determine the outcome of mutual 6067 authentication 6069 As Kerberos V5 is capable of providing mutual authentication, 6070 implementations SHOULD support mutual authentication by default 6071 for login authentication. 6073 Note however that Kerberos authentication only assures that the 6074 server (iSCSI target) can be trusted by the Kerberos client 6075 (initiator) and vice-versa; an initiator should employ 6076 appropriately secured service discovery techniques (e.g. iSNS, 6077 Section 4.2.7) to ensure that it is talking to the intended target 6078 principal. 6080 iSCSI does not use Kerberos v5 for either integrity or 6081 confidentiality protection of the iSCSI protocol. iSCSI uses IPsec 6082 for those purposes as specified in Section 9.3. 6084 9.3. IPsec 6086 iSCSI uses the IPsec mechanism for packet protection 6087 (cryptographic integrity, authentication, and confidentiality) at 6088 the IP level between the iSCSI communicating end points. The 6089 following sections describe the IPsec protocols that must be 6090 implemented for data integrity and authentication, 6091 confidentiality, and cryptographic key management. 6093 An iSCSI initiator or target may provide the required IPsec 6094 support fully integrated or in conjunction with an IPsec front-end 6095 device. In the latter case, the compliance requirements with 6096 regard to IPsec support apply to the "combined device". Only the 6097 "combined device" is to be considered an iSCSI device. 6099 Detailed considerations and recommendations for using IPsec for 6100 iSCSI are provided in [RFC3723] as updated by [IPSEC-IPS]. The 6101 IPsec requirements are reproduced here for convenience and are 6102 intended to match those in [IPSEC-IPS]; in the event of a 6103 discrepancy, the requirements in [IPSEC-IPS] apply. 6105 9.3.1. Data Integrity and Authentication 6107 Data authentication and integrity is provided by a cryptographic 6108 keyed Message Authentication Code in every sent packet. This code 6109 protects against message insertion, deletion, and modification. 6110 Protection against message replay is realized by using a sequence 6111 counter. 6113 An iSCSI-compliant initiator or target MUST provide data integrity 6114 and authentication by implementing IPsec v2 [RFC2401] with ESPv2 6115 [RFC2406] in tunnel mode, SHOULD provide data integrity and 6116 authentication by implementing IPsec v3 [RFC4301] with ESPv3 6117 [RFC4303] in tunnel mode, and MAY provide data integrity and 6118 authentication by implementing either IPsec v2 or v3 with the 6119 appropriate version of ESP in transport mode. The IPsec 6121 implementation MUST fulfill the following iSCSI-specific 6122 requirements: 6124 - HMAC-SHA1 MUST be implemented in the specific form of HMAC- 6125 SHA-1-96 [RFC2404]. 6127 - AES CBC MAC with XCBC extensions using 128-bit keys SHOULD 6128 be implemented [RFC3566]. 6130 - Implementations that support IKEv2 [RFC5996] SHOULD also 6131 implement AES GMAC [RFC4543] using 128-bit keys. 6133 The ESP anti-replay service MUST also be implemented. 6135 At the high speeds iSCSI is expected to operate, a single IPsec SA 6136 could rapidly cycle through the ESP 32-bit sequence number space. 6137 In view of this, an iSCSI implementation that is capable of 6138 operating at speeds of 1 Gbps and that implements both IKEv2 6139 [RFC5996] and ESPv3 [RFC4303] MUST also implement extended (64- 6140 bit) sequence numbers for ESPv3 and SHOULD use ESPv3 extended 6141 sequence numbers for all security associations that use ESPv3 to 6142 protect iSCSI connections. 6144 9.3.2. Confidentiality 6146 Confidentiality is provided by encrypting the data in every 6147 packet. When confidentiality is used it MUST be accompanied by 6148 data integrity and authentication to provide comprehensive 6149 protection against eavesdropping, message insertion, deletion, 6150 modification, and replaying. 6152 An iSCSI-compliant initiator or target MUST provide 6153 confidentiality by implementing IPsec v2 [RFC2401] with ESPv2 6154 [RFC2406] in tunnel mode, SHOULD provide confidentiality by 6155 implementing IPsec v3 [RFC4301] with ESPv3 [RFC4303] in tunnel 6156 mode and MAY provide confidentiality by implementing either IPsec 6157 v2 or v3 with the appropriate version of ESP in transport mode, 6158 with the following iSCSI specific requirements that apply to IPsec 6159 v2 and IPsec v3: 6160 - 3DES in CBC mode MAY be implemented [RFC2451]. 6162 - AES in CBC mode with 128-bit keys MUST be implemented 6163 [RFC3602]; other key sizes MAY be supported. 6165 - AES in Counter mode MAY be implemented [RFC3686]. 6167 - Implementations that support IKEv2 [RFC5996] SHOULD also 6168 implement AES GCM with 128-bit keys [RFC4106] ]; other key 6169 sizes MAY be supported. 6171 DES in CBC mode MUST NOT be used due to its inherent weakness. 6173 The NULL encryption algorithm MUST also be implemented. 6175 9.3.3. Policy, Security Associations, and Cryptographic Key 6176 Management 6178 A compliant iSCSI implementation MUST meet the cryptographic key 6179 management requirements of the IPsec protocol suite. 6180 Authentication, security association negotiation, and 6181 cryptographic key management MUST be provided by implementing IKE 6182 [RFC2409] using the IPsec DOI [RFC2407], and SHOULD be provided by 6183 implementing IKEv2 [RFC5996], with the following iSCSI-specific 6184 requirements: 6186 a) Peer authentication using a pre-shared cryptographic key MUST 6187 be supported. Certificate-based peer authentication using 6188 digital signatures MAY be supported. For IKEv1 ([RFC2409]), 6189 peer authentication using the public key encryption methods 6190 outlined in IKE sections 5.2 and 5.3 of [RFC2409] SHOULD NOT 6191 be used. 6192 b) When digital signatures are used to achieve authentication, 6193 an IKE negotiator SHOULD use IKE Certificate Request 6194 Payload(s) to specify the certificate authority. IKE 6195 negotiators SHOULD check the pertinent Certificate Revocation 6196 List (CRL) before accepting a PKI certificate for use in IKE 6197 authentication procedures. These checks may not be needed in 6198 environments where a small number of certificates are 6199 statically configured as trust anchors. 6200 c) Conformant iSCSI implementations of IKEv1 MUST support Main 6201 Mode and SHOULD support Aggressive Mode. Main Mode with pre- 6202 shared key authentication method SHOULD NOT be used when 6203 either the initiator or the target uses dynamically assigned 6204 addresses. While in many cases pre-shared keys offer good 6205 security, situations in which dynamically assigned addresses 6206 are used force the use of a group pre-shared key, which 6207 creates vulnerability to a man-in-the-middle attack. 6208 d) In the IKEv1 Phase 2 Quick Mode, exchanges for creating the 6209 Phase 2 SA, the Identification Payload MUST be present. 6210 e) The following identification type requirements apply to 6211 IKEv1. ID_IPV4_ADDR, ID_IPV6_ADDR (if the protocol stack 6212 supports IPv6) and ID_FQDN Identification Types MUST be 6213 supported; ID_USER_FQDN SHOULD be supported. The IP Subnet, 6214 IP Address Range, ID_DER_ASN1_DN, and ID_DER_ASN1_GN 6215 Identification Types SHOULD NOT be used. The ID_KEY_ID 6216 Identification Type MUST NOT be used. 6217 f) If IKEv2 is supported, the following identification 6218 requirements apply. ID_IPV4_ADDR, ID_IPV6_ADDR (if the 6219 protocol stack supports IPv6) and ID_FQDN Identification 6220 Types MUST be supported; ID_RFC822_ADDR SHOULD be supported. 6221 The ID_DER_ASN1_DN, and ID_DER_ASN1_GN Identification Types 6222 SHOULD NOT be used. The ID_KEY_ID Identification Type MUST 6223 NOT be used. 6225 The reasons for the "MUST NOT" and "SHOULD NOT" requirements for 6226 identification type requirements in preceding bullets e) and f) 6227 are: 6229 - IP Subnet and IP Address Range are too broad to usefully 6230 identify an iSCSI endpoint. 6232 - The DN and GN types are X.500 identities; it is usually 6233 better to use an identity from subjectAltName in a PKI 6234 certificate. 6236 - ID_KEY_ID is not interoperable as specified. 6238 Manual cryptographic keying MUST NOT be used because it does not 6239 provide the necessary re-keying support. 6241 When DH groups are used, a DH group of at least 2048 bits SHOULD 6242 be offered as a part of all proposals to create IPsec Security 6243 Associations to protect iSCSI traffic, with both IKEv1 and IKEv2. 6245 When IPsec is used, the receipt of an IKEv1 Phase 2 delete message 6246 or an IKEv2 INFORMATIONAL exchange that deletes the SA SHOULD NOT 6247 be interpreted as a reason for tearing down the iSCSI TCP 6248 connection. If additional traffic is sent on it, a new IKE SA will 6249 be created to protect it. 6251 The method used by the initiator to determine whether the target 6252 should be connected using IPsec is regarded as an issue of IPsec 6253 policy administration, and thus not defined in the iSCSI standard. 6255 The method used by an initiator that supports both IPsec v2 and v3 6256 to determine which versions of IPsec are supported by the target 6257 is also regarded as an issue of IPsec policy administration, and 6258 thus not defined in the iSCSI standard. If both IPsec v2 and v3 6259 are supported by both the initiator and target, use of IPsec v3 is 6260 recommended. 6262 If an iSCSI target is discovered via a SendTargets request in a 6263 discovery session not using IPsec, the initiator should assume 6264 that it does not need IPsec to establish a session to that target. 6265 If an iSCSI target is discovered using a discovery session that 6266 does use IPsec, the initiator SHOULD use IPsec when establishing a 6267 session to that target. 6269 9.4. Security Considerations for the X#NodeArchitecture Key 6271 The security considerations in this Section are specific to the 6272 X#NodeArchitecture discussed in Section 13.26. 6274 This extension key transmits specific implementation details about 6275 the node that sends it; such details may be considered sensitive 6276 in some environments. For example, if a certain software or 6277 firmware version is known to contain security weaknesses, 6278 announcing the presence of that version via this key may not be 6279 desirable. The countermeasures for this security concern are: 6281 a) sending less detailed information in the key values, 6282 b) not sending the extension key, or 6283 c) using IPsec ([RFC4303]) to provide confidentiality for the 6284 iSCSI connection on which the key is sent 6286 To support the first and second countermeasures, all 6287 implementations of this extension key MUST provide an 6288 administrative mechanism to disable sending the key. In addition, 6289 all implementations SHOULD provide an administrative mechanism to 6290 configure a verbosity level of the key value, thereby controlling 6291 the amount of information sent. 6293 For example, a lower verbosity might enable transmission of node 6294 architecture component names only, but no version numbers. The 6295 choice of which countermeasure is most appropriate depends on the 6296 environment. However, sending less detailed information in the key 6297 values may be an acceptable countermeasure in many environments, 6298 since it provides a compromise between sending too much 6299 information and the other more complete countermeasures of not 6300 sending the key at all or using IPsec. 6302 In addition to security considerations involving transmission of 6303 the key contents, any logging method(s) used for the key values 6304 MUST keep the information secure from intruders. For all 6305 implementations, the requirements to address this security concern 6306 are: 6308 a) Display of the log MUST only be possible with administrative 6309 rights to the node. 6310 b) Options to disable logging to disk and to keep logs for a 6311 fixed duration SHOULD be provided. 6313 Finally, it is important to note that different nodes may have 6314 different levels of risk, and these differences may affect the 6315 implementation. The components of risk include assets, threats, 6316 and vulnerabilities. Consider the following example iSCSI nodes, 6317 which demonstrate differences in assets and vulnerabilities of the 6318 nodes, and as a result, differences in implementation: 6320 a) One iSCSI target based on a special-purpose operating 6321 system: Since the iSCSI target controls access to the 6322 data storage containing company assets, the asset level 6323 is seen as very high. Also, because of the special- 6324 purpose operating system, in which vulnerabilities are 6325 less well-known, the vulnerability level is viewed as 6326 low. 6328 b) Multiple iSCSI initiators in a blade farm, each running a 6329 general purpose operating system: The asset level of each 6330 node is viewed as low, since blades are replaceable and 6331 low cost. However, the vulnerability level is viewed as 6332 high, since there may be many well-known vulnerabilities 6333 to that general-purpose operating system. For this 6334 target, an appropriate implementation might be logging of 6335 received key values, but no transmission of the key. For 6336 this initiator, an appropriate implementation might be 6337 transmission of the key, but no logging of received key 6338 values. 6340 9.5. SCSI Access Control Considerations 6342 iSCSI is a SCSI transport protocol and as such does not apply any 6343 access controls on SCSI-level operations such as SCSI task 6344 management functions (e.g. LU Reset, see Section 11.5.1). SCSI- 6345 level access controls (e.g. ACCESS CONTROL OUT, see [SPC3]) have 6346 to be appropriately deployed in practice to address SCSI-level 6347 security considerations, in addition to security at iSCSI 6348 connection and packet protection mechanisms that were already 6349 discussed in preceding Sections. 6351 10. Notes to Implementers 6353 This Section notes some of the performance and reliability 6354 considerations of the iSCSI protocol. This protocol was designed 6355 to allow efficient silicon and software implementations. The iSCSI 6356 task tag mechanism was designed to enable Direct Data Placement 6357 (DDP - a DMA form) at the iSCSI level or lower. 6359 The guiding assumption made throughout the design of this protocol 6360 is that targets are resource constrained relative to initiators. 6362 Implementers are also advised to consider the implementation 6363 consequences of the iSCSI to SCSI mapping model as outlined in 6364 Section 4.4.3. 6366 10.1. Multiple Network Adapters 6368 The iSCSI protocol allows multiple connections, not all of which 6369 need to go over the same network adapter. If multiple network 6370 connections are to be utilized with hardware support, the iSCSI 6371 protocol command-data-status allegiance to one TCP connection 6372 ensures that there is no need to replicate information across 6373 network adapters or otherwise require them to cooperate. 6375 However, some task management commands may require some loose form 6376 of cooperation or replication at least on the target. 6378 10.1.1. Conservative Reuse of ISIDs 6380 Historically, the SCSI model (and implementations and applications 6381 based on that model) has assumed that SCSI ports are static, 6382 physical entities. Recent extensions to the SCSI model have taken 6383 advantage of persistent worldwide unique names for these ports. In 6384 iSCSI however, the SCSI initiator ports are the endpoints of 6385 dynamically created sessions, so the presumptions of "static and 6386 physical" do not apply. In any case, the model clauses 6387 (particularly, Section 4.4.1) provide for persistent, reusable 6388 names for the iSCSI-type SCSI initiator ports even though there 6389 does not need to be any physical entity bound to these names. 6391 To both minimize the disruption of legacy applications and to 6392 better facilitate the SCSI features that rely on persistent names 6393 for SCSI ports, iSCSI implementations SHOULD attempt to provide a 6394 stable presentation of SCSI Initiator Ports (both to the upper OS- 6395 layers and to the targets to which they connect). This can be 6396 achieved in an initiator implementation by conservatively reusing 6397 ISIDs. In other words, the same ISID should be used in the Login 6398 process to multiple target portal groups (of the same iSCSI Target 6399 or different iSCSI Targets). The ISID RULE (Section 4.4.3) only 6400 prohibits reuse to the same target portal group. It does not 6401 "preclude" reuse to other target portal groups. 6402 The principle of conservative reuse "encourages" reuse to other 6403 target portal groups. When a SCSI target device sees the same 6404 (InitiatorName, ISID) pair in different sessions to different 6405 target portal groups, it can identify the underlying SCSI 6406 Initiator Port on each session as the same SCSI port. In effect, 6407 it can recognize multiple paths from the same source. 6409 10.1.2. iSCSI Name, ISID, and TPGT Use 6411 The designers of the iSCSI protocol are aware that legacy SCSI 6412 transports rely on initiator identity to assign access to storage 6413 resources. Although newer techniques are available and simplify 6414 access control, support for configuration and authentication 6415 schemes that are based on initiator identity is deemed important 6416 in order to support legacy systems and administration software. 6417 iSCSI thus supports the notion that it should be possible to 6418 assign access to storage resources based on "initiator device" 6419 identity. 6421 When there are multiple hardware or software components 6422 coordinated as a single iSCSI Node, there must be some (logical) 6423 entity that represents the iSCSI Node that makes the iSCSI Node 6424 Name available to all components involved in session creation and 6425 login. Similarly, this entity that represents the iSCSI Node must 6426 be able to coordinate session identifier resources (ISID for 6427 initiators) to enforce both the ISID and TSIH RULES (see Section 6428 4.4.3). 6430 For targets, because of the closed environment, implementation of 6431 this entity should be straightforward. However, vendors of iSCSI 6432 hardware (e.g., NICs or HBAs) intended for targets, SHOULD provide 6433 mechanisms for configuration of the iSCSI Node Name across the 6434 portal groups instantiated by multiple instances of these 6435 components within a target. 6437 However, complex targets making use of multiple Target Portal 6438 Group Tags may reconfigure them to achieve various quality goals. 6439 The initiators have two mechanisms at their disposal to discover 6440 and/or check reconfiguring targets - the discovery session type 6441 and a key returned by the target during login to confirm the TPGT. 6442 An initiator should attempt to "rediscover" the target 6443 configuration anytime a session is terminated unexpectedly. 6445 For initiators, in the long term, it is expected that operating 6446 system vendors will take on the role of this entity and provide 6447 standard APIs that can inform components of their iSCSI Node Name 6448 and can configure and/or coordinate ISID allocation, use, and 6449 reuse. 6451 Recognizing that such initiator APIs are not available today, 6452 other implementations of the role of this entity are possible. For 6453 example, a human may instantiate the (common) Node name as part of 6454 the installation process of each iSCSI component involved in 6455 session creation and login. This may be done either by pointing 6456 the component to a vendor-specific location for this datum or to a 6457 system-wide location. The structure of the ISID namespace (see 6458 Section 11.12.5 and [RFC3721]) facilitates implementation of the 6459 ISID coordination by allowing each component vendor to 6460 independently (of other vendor's components) coordinate 6461 allocation, use, and reuse of its own partition of the ISID 6462 namespace in a vendor-specific manner. Partitioning of the ISID 6463 namespace within initiator portal groups managed by that vendor 6464 allows each such initiator portal group to act independently of 6465 all other portal groups when selecting an ISID for a login; this 6466 facilitates enforcement of the ISID RULE (see Section 4.4.3) at 6467 the initiator. 6469 A vendor of iSCSI hardware (e.g., NICs or HBAs) intended for use 6470 in initiators MUST implement a mechanism for configuring the iSCSI 6471 Node Name. Vendors, and administrators must ensure that iSCSI Node 6472 Names are unique worldwide. It is therefore important that when 6473 one chooses to reuse the iSCSI Node Name of a disabled unit, not 6474 to re-assign that name to the original unit unless its worldwide 6475 uniqueness can be ascertained again. 6477 In addition, a vendor of iSCSI hardware must implement a mechanism 6478 to configure and/or coordinate ISIDs for all sessions managed by 6479 multiple instances of that hardware within a given iSCSI Node. 6480 Such configuration might be either permanently pre-assigned at the 6481 factory (in a necessarily globally unique way), statically 6482 assigned (e.g., partitioned across all the NICs at initialization 6483 in a locally unique way), or dynamically assigned (e.g., on-line 6484 allocator, also in a locally unique way). In the latter two cases, 6485 the configuration may be via public APIs (perhaps driven by an 6486 independent vendor's software, such as the OS vendor) or via 6487 private APIs driven by the vendor's own software. 6489 The process of name assignment and coordination has to be as 6490 encompassing and automated as possible as years of legacy usage 6491 have shown it to be highly error-prone. It is to be mentioned 6492 that SCSI has today alternative schemes of access control that can 6493 be used by all transports and their security is not dependent on 6494 strict naming coordination. 6496 10.2. Autosense and Auto Contingent Allegiance (ACA) 6498 Autosense refers to the automatic return of sense data to the 6499 initiator in case a command did not complete successfully. iSCSI 6500 initiators and targets MUST support and use autosense. 6502 ACA helps preserve ordered command execution in the presence of 6503 errors. As there can be many commands in-flight between an 6504 initiator and a target, SCSI initiator functionality in some 6505 operating systems depends on ACA to enforce ordered command 6506 execution during error recovery, and hence iSCSI initiator 6507 implementations for those operating systems need to support ACA. 6508 In order to support error recovery for these operating systems and 6509 iSCSI initiators, iSCSI targets SHOULD support ACA. 6511 10.3. iSCSI Timeouts 6513 iSCSI recovery actions are often dependent on iSCSI time-outs 6514 being recognized and acted upon before SCSI time-outs. Determining 6515 the right time-outs to use for various iSCSI actions (command 6516 acknowledgements expected, status acknowledgements, etc.) is very 6517 much dependent on infrastructure (hardware, links, TCP/IP stack, 6518 iSCSI driver). As a guide, the implementer may use an average Nop- 6519 Out/Nop-In turnaround delay multiplied by a "safety factor" (e.g., 6520 4) as a good estimate for the basic delay of the iSCSI stack for a 6521 given connection. The safety factor should account for the network 6522 load variability. For connection teardown the implementer may 6523 want to consider also TCP common practice for the given 6524 infrastructure. 6526 Text negotiations MAY also be subject to either time-limits or 6527 limits in the number of exchanges. Those SHOULD be generous enough 6528 to avoid affecting interoperability (e.g., allowing each key to be 6529 negotiated on a separate exchange). 6531 The relation between iSCSI timeouts and SCSI timeouts should also 6532 be considered. SCSI timeouts should be longer than iSCSI timeouts 6533 plus the time required for iSCSI recovery whenever iSCSI recovery 6534 is planned. Alternatively, an implementer may choose to interlock 6535 iSCSI timeouts and recovery with SCSI timeouts so that SCSI 6536 recovery will become active only where iSCSI is not planned to, or 6537 failed to, recover. 6539 The implementer may also want to consider the interaction between 6540 various iSCSI exception events - such as a digest failure - and 6541 subsequent timeouts. When iSCSI error recovery is active, a digest 6542 failure is likely to result in discovering a missing command or 6543 data PDU. In these cases, an implementer may want to lower the 6544 timeout values to enable faster initiation for recovery 6545 procedures. 6547 10.4. Command Retry and Cleaning Old Command Instances 6549 To avoid having old, retried command instances appear in a valid 6550 command window after a command sequence number wrap around, the 6551 protocol requires (see Section 4.2.2.1) that on every connection 6552 on which a retry has been issued, a non-immediate command be 6553 issued and acknowledged within a 2**31-1 commands interval from 6554 the CmdSN of the retried command. This requirement can be 6555 fulfilled by an implementation in several ways. 6557 The simplest technique to use is to send a (non-retry) non- 6558 immediate SCSI command (or a NOP if no SCSI command is available 6559 for a while) after every command retry on the connection on which 6560 the retry was attempted. As errors are deemed rare events, this 6561 technique is probably the most effective, as it does not involve 6562 additional checks at the initiator when issuing commands. 6564 10.5. Synch and Steering Layer and Performance 6566 While a synch and steering layer is optional, an initiator/target 6567 that does not have it working against a target/initiator that 6568 demands synch and steering may experience performance degradation 6569 caused by packet reordering and loss. Providing a synch and 6570 steering mechanism is recommended for all high-speed 6571 implementations. 6573 10.6. Considerations for State-dependent Devices and Long-lasting 6574 SCSI Operations 6576 Sequential access devices operate on the principle that the 6577 position of the device is based on the last command processed. As 6578 such, command processing order and knowledge of whether or not the 6579 previous command was processed is of the utmost importance to 6580 maintain data integrity. For example, inadvertent retries of SCSI 6581 commands when it is not known if the previous SCSI command was 6582 processed is a potential data integrity risk. 6584 For a sequential access device, consider the scenario in which a 6585 SCSI SPACE command to backspace one filemark is issued and then 6586 re-issued due to no status received for the command. If the first 6587 SPACE command was actually processed, the re-issued SPACE command, 6588 if processed, will cause the position to change. Thus, a 6589 subsequent write operation will write data to the wrong position 6590 and any previous data at that position will be overwritten. 6592 For a medium changer device, consider the scenario in which an 6593 EXCHANGE MEDIUM command (the SOURCE ADDRESS and DESTINATION 6594 ADDRESS are the same thus performing a swap) is issued and then 6595 re-issued due to no status received for the command. If the first 6596 EXCHANGE MEDIUM command was actually processed, the re-issued 6597 EXCHANGE MEDIUM command, if processed, will perform the swap 6598 again. The net effect is no swap was performed thus leaving a data 6599 integrity exposure. 6601 All commands that change the state of the device (as in SPACE 6602 commands for sequential access devices, and EXCHANGE MEDIUM for 6603 medium changer device), MUST be issued as non-immediate commands 6604 for deterministic and in order delivery to iSCSI targets. 6606 For many of those state changing commands, the execution model 6607 also assumes that the command is executed exactly once. Devices 6608 implementing READ POSITION and LOCATE provide a means for SCSI 6609 level command recovery and new tape-class devices should support 6610 those commands. In their absence a retry at SCSI level is 6611 difficult and error recovery at iSCSI level is advisable. 6613 Devices operating on long latency delivery subsystems and 6614 performing long lasting SCSI operations may need mechanisms that 6615 enable connection replacement while commands are running (e.g., 6616 during an extended copy operation). 6618 10.6.1. Determining the Proper ErrorRecoveryLevel 6620 The implementation and use of a specific ErrorRecoveryLevel should 6621 be determined based on the deployment scenarios of a given iSCSI 6622 implementation. Generally, the following factors must be 6623 considered before deciding on the proper level of recovery: 6625 a) Application resilience to I/O failures. 6626 b) Required level of availability in the face of transport 6627 connection failures. 6628 c) Probability of transport layer "checksum escape" (message 6629 error undetected by TCP checksum - see [RFC3385] for 6630 related discussion). This in turn decides the iSCSI 6631 digest failure frequency, and thus the criticality of 6632 iSCSI-level error recovery. The details of estimating 6633 this probability are outside the scope of this document. 6635 A consideration of the above factors for SCSI tape devices as an 6636 example suggests that implementations SHOULD use 6637 ErrorRecoveryLevel=1 when transport connection failure is not a 6638 concern and SCSI level recovery is unavailable, and 6639 ErrorRecoveryLevel=2 when the connection failure is also of high 6640 likelihood during a backup/retrieval. 6642 For extended copy operations, implementations SHOULD use 6643 ErrorRecoveryLevel=2 whenever there is a relatively high 6644 likelihood of connection failure. 6646 10.7. Multi-task Abort Implementation Considerations 6648 Multi-task abort operations are typically issued in emergencies - 6649 such as clearing a device lock-up, HA failover/failback etc. In 6650 these circumstances, it is desirable to rapidly go through the 6651 error handling process as opposed to the target waiting on 6652 multiple third-party initiators who may not even be functional 6653 anymore - especially if this emergency is triggered because of one 6654 such initiator failure. Therefore, both iSCSI target and 6655 initiator implementations SHOULD support FastAbort multi-task 6656 abort semantics (Section 4.2.3.4). 6658 Note that both in standard semantics (Section 4.2.3.3) and 6659 FastAbort semantics (Section 4.2.3.4), there may be outstanding 6660 data transfers even after the TMF completion is reported on the 6661 issuing session. In the case of iSCSI/iSER [iSER], these would be 6662 tagged data transfers for STags not owned by any active tasks. 6663 Whether or not real buffers support these data transfers is 6664 implementation-dependent. However, the data transfers logically 6665 MUST be silently discarded by the target iSCSI layer in all cases. 6666 A target MAY, on an implementation-defined internal timeout, also 6667 choose to drop the connections on which it did not receive the 6668 expected Data-Out sequences (Section 4.2.3.3) or NOP-Out 6669 acknowledgements (Section 4.2.3.4) so as to reclaim the associated 6670 buffer, STag, and TTT resources as appropriate. 6672 11. iSCSI PDU Formats 6674 All multi-byte integers that are specified in formats defined in 6675 this document are to be represented in network byte order (i.e., 6676 big endian). Any field that appears in this document assumes that 6677 the most significant byte is the lowest numbered byte and the most 6678 significant bit (within byte or field) is the lowest numbered bit 6679 unless specified otherwise. 6681 Any compliant sender MUST set all bits not defined and all 6682 reserved fields to zero unless specified otherwise. Any compliant 6683 receiver MUST ignore any bit not defined and all reserved fields 6684 unless specified otherwise. Receipt of reserved code values in 6685 defined fields MUST be reported as a protocol error. 6687 Reserved fields are marked by the word "reserved", some 6688 abbreviation of "reserved", or by "." for individual bits when no 6689 other form of marking is technically feasible. 6691 11.1. iSCSI PDU Length and Padding 6693 iSCSI PDUs are padded to the closest integer number of four byte 6694 words. The padding bytes SHOULD be sent as 0. 6696 11.2. PDU Template, Header, and Opcodes 6698 All iSCSI PDUs have one or more header segments and, optionally, a 6699 data segment. After the entire header segment group a header- 6700 digest MAY follow. The data segment MAY also be followed by a 6701 data-digest. 6703 The Basic Header Segment (BHS) is the first segment in all of the 6704 iSCSI PDUs. The BHS is a fixed-length 48-byte header segment. It 6705 MAY be followed by Additional Header Segments (AHS), a Header- 6706 Digest, a Data Segment, and/or a Data-Digest. 6708 The overall structure of an iSCSI PDU is as follows: 6710 Byte/ 0 | 1 | 2 | 3 | 6711 / | | | | 6712 |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| 6713 +---------------+---------------+---------------+--------------+ 6714 0/ Basic Header Segment (BHS) / 6715 +/ / 6716 +---------------+---------------+---------------+--------------+ 6717 48/ Additional Header Segment 1 (AHS) (optional) / 6718 +/ / 6719 +---------------+---------------+---------------+--------------+ 6720 / Additional Header Segment 2 (AHS) (optional) / 6721 +/ / 6722 +---------------+---------------+---------------+--------------+ 6723 +---------------+---------------+---------------+--------------+ 6724 / Additional Header Segment n (AHS) (optional) / 6725 +/ / 6726 +---------------+---------------+---------------+--------------+ 6727 k/ Header-Digest (optional) / 6728 +/ / 6729 +---------------+---------------+---------------+--------------+ 6730 l/ Data Segment(optional) / 6731 +/ / 6732 +---------------+---------------+---------------+--------------+ 6733 m/ Data-Digest (optional) / 6734 +/ / 6735 +---------------+---------------+---------------+--------------+ 6737 All PDU segments and digests are padded to the closest integer 6738 number of four byte words. For example, all PDU segments and 6739 digests start at a four byte word boundary and the padding ranges 6740 from 0 to 3 bytes. The padding bytes SHOULD be sent as 0. 6742 iSCSI response PDUs do not have AH Segments. 6744 11.2.1. Basic Header Segment (BHS) 6746 The BHS is 48 bytes long. The Opcode and DataSegmentLength fields 6747 appear in all iSCSI PDUs. In addition, when used, the Initiator 6748 Task Tag and Logical Unit Number always appear in the same 6749 location in the header. 6751 The format of the BHS is: 6753 Byte/ 0 | 1 | 2 | 3 | 6754 / | | | | 6755 |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| 6756 +---------------+---------------+---------------+--------------+ 6757 0|.|I| Opcode |F| Opcode-specific fields | 6758 +---------------+---------------+---------------+--------------+ 6759 4|TotalAHSLength | DataSegmentLength | 6760 +---------------+---------------+---------------+--------------+ 6761 8| LUN or Opcode-specific fields | 6762 + + 6763 12| | 6764 +---------------+---------------+---------------+--------------+ 6765 16| Initiator Task Tag | 6766 +---------------+---------------+---------------+--------------+ 6767 20/ Opcode-specific fields / 6768 +/ / 6769 +---------------+---------------+---------------+--------------+ 6770 48 6772 11.2.1.1. I 6774 For request PDUs, the I bit set to 1 is an immediate delivery 6775 marker. 6777 11.2.1.2. Opcode 6779 The Opcode indicates the type of iSCSI PDU the header 6780 encapsulates. 6782 The Opcodes are divided into two categories: initiator opcodes and 6783 target opcodes. Initiator opcodes are in PDUs sent by the 6784 initiator (request PDUs). Target opcodes are in PDUs sent by the 6785 target (response PDUs). 6787 Initiators MUST NOT use target opcodes and targets MUST NOT use 6788 initiator opcodes. 6790 Initiator opcodes defined in this specification are: 6792 0x00 NOP-Out 6794 0x01 SCSI Command (encapsulates a SCSI Command Descriptor 6795 Block) 6797 0x02 SCSI Task Management function request 6799 0x03 Login Request 6801 0x04 Text Request 6803 0x05 SCSI Data-out (for WRITE operations) 6805 0x06 Logout Request 6807 0x10 SNACK Request 6809 0x1c-0x1e Vendor specific codes 6811 Target opcodes are: 6813 0x20 NOP-In 6815 0x21 SCSI Response - contains SCSI status and possibly sense 6816 information or other response information. 6818 0x22 SCSI Task Management function response 6820 0x23 Login Response 6822 0x24 Text Response 6824 0x25 SCSI Data-in - for READ operations. 6826 0x26 Logout Response 6828 0x31 Ready To Transfer (R2T) - sent by target when it is ready 6829 to receive data. 6831 0x32 Asynchronous Message - sent by target to indicate certain 6832 special conditions. 6834 0x3c-0x3e Vendor specific codes 6836 0x3f Reject 6838 All other opcodes are reserved. 6840 11.2.1.3. Final (F) bit 6842 When set to 1 it indicates the final (or only) PDU of a sequence. 6844 11.2.1.4. Opcode-specific Fields 6846 These fields have different meanings for different opcode types. 6848 11.2.1.5. TotalAHSLength 6850 Total length of all AHS header segments in units of four byte 6851 words including padding, if any. 6853 The TotalAHSLength is only used in PDUs that have an AHS and MUST 6854 be 0 in all other PDUs. 6856 11.2.1.6. DataSegmentLength 6858 This is the data segment payload length in bytes (excluding 6859 padding). The DataSegmentLength MUST be 0 whenever the PDU has no 6860 data segment. 6862 11.2.1.7. LUN 6864 Some opcodes operate on a specific Logical Unit. The Logical Unit 6865 Number (LUN) field identifies which Logical Unit. If the opcode 6866 does not relate to a Logical Unit, this field is either ignored or 6867 may be used in an opcode specific way. The LUN field is 64-bits 6868 and should be formatted in accordance with [SAM2]. For example, 6869 LUN[0] from [SAM2] is BHS byte 8 and so on up to LUN[7] from 6870 [SAM2], which is BHS byte 15. 6872 11.2.1.8. Initiator Task Tag 6874 The initiator assigns a Task Tag to each iSCSI task it issues. 6875 While a task exists, this tag MUST uniquely identify the task 6876 session-wide. SCSI may also use the initiator task tag as part of 6877 the SCSI task identifier when the timespan during which an iSCSI 6878 initiator task tag must be unique extends over the timespan during 6879 which a SCSI task tag must be unique. However, the iSCSI Initiator 6880 Task Tag must exist and be unique even for untagged SCSI commands. 6882 An ITT value of 0xffffffff is reserved and MUST NOT be assigned 6883 for a task by the initiator. The only instance in which it may be 6884 seen on the wire is in a target-initiated NOP-In PDU (Section 6885 11.19) and in the initiator response to that PDU, if necessary. 6887 11.2.2. Additional Header Segment (AHS) 6889 The general format of an AHS is: 6891 Byte/ 0 | 1 | 2 | 3 | 6892 / | | | | 6893 |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| 6894 +---------------+---------------+---------------+--------------+ 6895 0| AHSLength | AHSType | AHS-Specific | 6896 +---------------+---------------+---------------+--------------+ 6897 4/ AHS-Specific / 6898 +/ / 6899 +---------------+---------------+---------------+--------------+ 6900 x 6902 11.2.2.1. AHSType 6904 The AHSType field is coded as follows: 6906 bit 0-1 - Reserved 6908 bit 2-7 - AHS code 6910 0 - Reserved 6912 1 - Extended CDB 6913 2 - Expected Bidirectional Read Data Length 6915 3 - 63 Reserved 6917 11.2.2.2. AHSLength 6919 This field contains the effective length in bytes of the AHS 6920 excluding AHSType and AHSLength and padding, if any. The AHS is 6921 padded to the smallest integer number of 4 byte words (i.e., from 6922 0 up to 3 padding bytes). 6924 11.2.2.3. Extended CDB AHS 6926 The format of the Extended CDB AHS is: 6928 Byte/ 0 | 1 | 2 | 3 | 6929 / | | | | 6930 |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| 6931 +---------------+---------------+---------------+--------------+ 6932 0| AHSLength (CDBLength-15) | 0x01 | Reserved | 6933 +---------------+---------------+---------------+--------------+ 6934 4/ ExtendedCDB...+padding / 6935 +/ / 6936 +---------------+---------------+---------------+--------------+ 6937 x 6939 This type of AHS MUST NOT be used if the CDBLength is less than 6940 17. 6941 The length includes the reserved byte 3. 6943 11.2.2.4. Bidirectional Expected Read-Data Length AHS 6945 The format of the Bidirectional Read Expected Data Transfer Length 6946 AHS is: 6948 Byte/ 0 | 1 | 2 | 3 | 6949 / | | | | 6950 |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| 6951 +---------------+---------------+---------------+--------------+ 6952 0| AHSLength (0x0005) | 0x02 | Reserved | 6953 +---------------+---------------+---------------+--------------+ 6954 4| Expected Read-Data Length | 6955 +---------------+---------------+---------------+--------------+ 6956 8 6958 11.2.3. Header Digest and Data Digest 6960 Optional header and data digests protect the integrity of the 6961 header and data, respectively. The digests, if present, are 6962 located, respectively, after the header and PDU-specific data, and 6963 cover respectively the header and the PDU data, each including 6964 the padding bytes, if any. 6966 The existence and type of digests are negotiated during the Login 6967 Phase. 6969 The separation of the header and data digests is useful in iSCSI 6970 routing applications, in which only the header changes when a 6971 message is forwarded. In this case, only the header digest should 6972 be recalculated. 6974 Digests are not included in data or header length fields. 6976 A zero-length Data Segment also implies a zero-length data-digest. 6978 11.2.4. Data Segment 6980 The (optional) Data Segment contains PDU associated data. Its 6981 payload effective length is provided in the BHS field - 6982 DataSegmentLength. The Data Segment is also padded to an integer 6983 number of 4 byte words. 6985 11.3. SCSI Command 6987 The format of the SCSI Command PDU is: 6989 Byte/ 0 | 1 | 2 | 3 | 6990 / | | | | 6991 |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| 6992 +---------------+---------------+---------------+--------------+ 6993 0|.|I| 0x01 |F|R|W|. .|ATTR | Reserved | 6994 +---------------+---------------+---------------+--------------+ 6995 4|TotalAHSLength | DataSegmentLength | 6996 +---------------+---------------+---------------+--------------+ 6997 8| Logical Unit Number (LUN) | 6998 + + 6999 12| | 7000 +---------------+---------------+---------------+--------------+ 7001 16| Initiator Task Tag | 7002 +---------------+---------------+---------------+--------------+ 7003 20| Expected Data Transfer Length | 7004 +---------------+---------------+---------------+--------------+ 7005 24| CmdSN | 7006 +---------------+---------------+---------------+--------------+ 7007 28| ExpStatSN | 7008 +---------------+---------------+---------------+--------------+ 7009 32/ SCSI Command Descriptor Block (CDB) / 7010 +/ / 7011 +---------------+---------------+---------------+--------------+ 7012 48/ AHS (Optional) / 7013 +---------------+---------------+---------------+--------------+ 7014 x/ Header Digest (Optional) / 7015 +---------------+---------------+---------------+--------------+ 7016 y/ (DataSegment, Command Data) (Optional) / 7017 +/ / 7018 +---------------+---------------+---------------+--------------+ 7019 z/ Data Digest (Optional) / 7020 +---------------+---------------+---------------+--------------+ 7022 11.3.1. Flags and Task Attributes (byte 1) 7024 The flags for a SCSI Command are: 7026 bit 0 (F) is set to 1 when no unsolicited SCSI Data-Out PDUs 7027 follow this PDU. When F=1 for a write and if Expected Data 7028 Transfer Length is larger than the DataSegmentLength, the 7029 target may solicit additional data through R2T. 7031 bit 1 (R) is set to 1 when the command is expected to input 7032 data. 7034 bit 2 (W) is set to 1 when the command is expected to output 7035 data. 7037 bit 3-4 Reserved. 7039 bit 5-7 contains Task Attributes. 7041 Task Attributes (ATTR) have one of the following integer values 7042 (see [SAM2] for details): 7044 0 - Untagged 7046 1 - Simple 7048 2 - Ordered 7050 3 - Head of Queue 7052 4 - ACA 7054 5-7 - Reserved 7056 At least one of the W and F bits MUST be set to 1. 7057 Either or both of R and W MAY be 1 when either the Expected Data 7058 Transfer Length and/or Bidirectional Read Expected Data Transfer 7059 Length are 0, but they MUST NOT both be 0 when the Expected Data 7060 Transfer Length and/or Bidirectional Read Expected Data Transfer 7061 Length are not 0 (i.e., when some data transfer is expected the 7062 transfer direction is indicated by the R and/or W bit). 7064 11.3.2. CmdSN - Command Sequence Number 7066 Enables ordered delivery across multiple connections in a single 7067 session. 7069 11.3.3. ExpStatSN 7071 Command responses up to ExpStatSN-1 (mod 2**32) have been received 7072 (acknowledges status) on the connection. 7074 11.3.4. Expected Data Transfer Length 7076 For unidirectional operations, the Expected Data Transfer Length 7077 field contains the number of bytes of data involved in this SCSI 7078 operation. For a unidirectional write operation (W flag set to 1 7079 and R flag set to 0), the initiator uses this field to specify the 7080 number of bytes of data it expects to transfer for this operation. 7081 For a unidirectional read operation (W flag set to 0 and R flag 7082 set to 1), the initiator uses this field to specify the number of 7083 bytes of data it expects the target to transfer to the initiator. 7084 It corresponds to the SAM2 byte count. 7086 For bidirectional operations (both R and W flags are set to 1), 7087 this field contains the number of data bytes involved in the write 7088 transfer. For bidirectional operations, an additional header 7089 segment MUST be present in the header sequence that indicates the 7090 Bidirectional Read Expected Data Transfer Length. The Expected 7091 Data Transfer Length field and the Bidirectional Read Expected 7092 Data Transfer Length field correspond to the SAM2 byte count. 7094 If the Expected Data Transfer Length for a write and the length of 7095 the immediate data part that follows the command (if any) are the 7096 same, then no more data PDUs are expected to follow. In this 7097 case, the F bit MUST be set to 1. 7099 If the Expected Data Transfer Length is higher than the 7100 FirstBurstLength (the negotiated maximum amount of unsolicited 7101 data the target will accept), the initiator MUST send the maximum 7102 amount of unsolicited data OR ONLY the immediate data, if any. 7104 Upon completion of a data transfer, the target informs the 7105 initiator (through residual counts) of how many bytes were 7106 actually processed (sent and/or received) by the target. 7108 11.3.5. CDB - SCSI Command Descriptor Block 7110 There are 16 bytes in the CDB field to accommodate the commonly 7111 used CDBs. Whenever the CDB is larger than 16 bytes, an Extended 7112 CDB AHS MUST be used to contain the CDB spillover. 7114 11.3.6. Data Segment - Command Data 7116 Some SCSI commands require additional parameter data to accompany 7117 the SCSI command. This data may be placed beyond the boundary of 7118 the iSCSI header in a data segment. Alternatively, user data 7119 (e.g., from a WRITE operation) can be placed in the data segment 7120 (both cases are referred to as immediate data). These data are 7121 governed by the rules for solicited vs. unsolicited data outlined 7122 in Section 4.2.5.2. 7124 11.4. SCSI Response 7126 The format of the SCSI Response PDU is: 7128 Byte/ 0 | 1 | 2 | 3 | 7129 / | | | | 7130 |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| 7131 +---------------+---------------+---------------+--------------+ 7132 0|.|.| 0x21 |1|. .|o|u|O|U|.| Response | Status | 7133 +---------------+---------------+---------------+--------------+ 7134 4|TotalAHSLength | DataSegmentLength | 7135 +---------------+---------------+---------------+--------------+ 7136 8| Reserved | 7137 + + 7138 12| | 7139 +---------------+---------------+---------------+--------------+ 7140 16| Initiator Task Tag | 7141 +---------------+---------------+---------------+--------------+ 7142 20| SNACK Tag or Reserved | 7143 +---------------+---------------+---------------+--------------+ 7144 24| StatSN | 7145 +---------------+---------------+---------------+--------------+ 7146 28| ExpCmdSN | 7147 +---------------+---------------+---------------+--------------+ 7148 32| MaxCmdSN | 7149 +---------------+---------------+---------------+--------------+ 7150 36| ExpDataSN or Reserved | 7151 +---------------+---------------+---------------+--------------+ 7152 40| Bidirectional Read Residual Count or Reserved | 7153 +---------------+---------------+---------------+--------------+ 7154 44| Residual Count or Reserved | 7155 +---------------+---------------+---------------+--------------+ 7156 48| Header-Digest (Optional) | 7157 +---------------+---------------+---------------+--------------+ 7158 / Data Segment (Optional) / 7159 +/ / 7160 +---------------+---------------+---------------+--------------+ 7161 | Data-Digest (Optional) | 7162 +---------------+---------------+---------------+--------------+ 7164 11.4.1. Flags (byte 1) 7166 bit 1-2 Reserved. 7168 bit 3 - (o) set for Bidirectional Read Residual Overflow. In 7169 this case, the Bidirectional Read Residual Count indicates 7170 the number of bytes that were not transferred to the 7171 initiator because the initiator's Expected Bidirectional 7172 Read Data Transfer Length was not sufficient. 7174 bit 4 - (u) set for Bidirectional Read Residual Underflow. In 7175 this case, the Bidirectional Read Residual Count indicates 7176 the number of bytes that were not transferred to the 7177 initiator out of the number of bytes expected to be 7178 transferred. 7180 bit 5 - (O) set for Residual Overflow. In this case, the 7181 Residual Count indicates the number of bytes that were not 7182 transferred because the initiator's Expected Data Transfer 7183 Length was not sufficient. For a bidirectional operation, 7184 the Residual Count contains the residual for the write 7185 operation. 7187 bit 6 - (U) set for Residual Underflow. In this case, the 7188 Residual Count indicates the number of bytes that were not 7189 transferred out of the number of bytes that were expected to 7190 be transferred. For a bidirectional operation, the Residual 7191 Count contains the residual for the write operation. 7193 bit 7 - (0) Reserved. 7195 Bits O and U and bits o and u are mutually exclusive (i.e., having 7196 both o and u or O and U set to 1 is a protocol error). 7198 For a response other than "Command Completed at Target", bits 3-6 7199 MUST be 0. 7201 11.4.2. Status 7203 The Status field is used to report the SCSI status of the command 7204 (as specified in [SAM2]) and is only valid if the Response Code is 7205 Command Completed at target. 7207 Some of the status codes defined in [SAM2] are: 7209 0x00 GOOD 7210 0x02 CHECK CONDITION 7212 0x08 BUSY 7214 0x18 RESERVATION CONFLICT 7216 0x28 TASK SET FULL 7218 0x30 ACA ACTIVE 7220 0x40 TASK ABORTED 7222 See [SAM2] for the complete list and definitions. 7224 If a SCSI device error is detected while data from the initiator 7225 is still expected (the command PDU did not contain all the data 7226 and the target has not received a Data PDU with the final bit 7227 Set), the target MUST wait until it receives a Data PDU with the F 7228 bit set in the last expected sequence before sending the Response 7229 PDU. 7231 11.4.3. Response 7233 This field contains the iSCSI service response. 7235 iSCSI service response codes defined in this specification are: 7237 0x00 - Command Completed at Target 7239 0x01 - Target Failure 7241 0x80-0xff - Vendor specific 7243 All other response codes are reserved. 7245 The Response is used to report a Service Response. The mapping of 7246 the response code into a SCSI service response code value, if 7247 needed, is outside the scope of this document. However, in 7248 symbolic terms response value 0x00 maps to the SCSI service 7249 response (see [SAM2] and [SPC3]) of TASK COMPLETE or LINKED 7250 COMMAND COMPLETE. All other Response values map to the SCSI 7251 service response of SERVICE DELIVERY OR TARGET FAILURE. 7253 If a SCSI Response PDU does not arrive before the session is 7254 terminated, the SCSI service response is SERVICE DELIVERY OR 7255 TARGET FAILURE. 7257 A non-zero response field indicates a failure to execute the 7258 command in which case the Status and Flag fields are undefined and 7259 MUST be ignored on reception. 7261 11.4.4. SNACK Tag 7263 This field contains a copy of the SNACK Tag of the last SNACK Tag 7264 accepted by the target on the same connection and for the command 7265 for which the response is issued. Otherwise it is reserved and 7266 should be set to 0. 7268 After issuing a R-Data SNACK the initiator must discard any SCSI 7269 status unless contained in an SCSI Response PDU carrying the same 7270 SNACK Tag as the last issued R-Data SNACK for the SCSI command on 7271 the current connection. 7273 For a detailed discussion on R-Data SNACK see 11.16.3. 7275 11.4.5. Residual Count 7277 11.4.5.1. Field Semantics 7279 The Residual Count field MUST be valid in the case where either 7280 the U bit or the O bit is set. If neither bit is set, the Residual 7281 Count field MUST be ignored on reception and SHOULD be set to 0 7282 when sending. Targets may set the residual count and initiators 7283 may use it when the response code is "completed at target" (even 7284 if the status returned is not GOOD). If the O bit is set, the 7285 Residual Count indicates the number of bytes that were not 7286 transferred because the initiator's Expected Data Transfer Length 7287 was not sufficient. If the U bit is set, the Residual Count 7288 indicates the number of bytes that were not transferred out of the 7289 number of bytes expected to be transferred. 7291 11.4.5.2. Residuals Concepts Overview 7293 SCSI-Presented Data Transfer Length (SPDTL) is the term this 7294 document uses (see Section 2.1 for definition) to represent the 7295 aggregate data length that the target SCSI layer attempts to 7296 transfer using the local iSCSI layer for a task. Expected Data 7297 Transfer Length (EDTL) is the iSCSI term that represents the 7298 length of data that the iSCSI layer expects to transfer for a 7299 task. EDTL is specified in the SCSI Command PDU. 7301 When SPDTL = EDTL for a task, the target iSCSI layer completes the 7302 task with no residuals. Whenever SPDTL differs from EDTL for a 7303 task, that task is said to have a residual. 7305 If SPDTL > EDTL for a task, iSCSI Overflow MUST be signaled in the 7306 SCSI Response PDU as specified in Section 11.4.5.1. The Residual 7307 Count MUST be set to the numerical value of (SPDTL - EDTL). 7309 If SPDTL < EDTL for a task, iSCSI Underflow MUST be signaled in 7310 the SCSI Response PDU as specified in Section 11.4.5.1. The 7311 Residual Count MUST be set to the numerical value of (EDTL - 7312 SPDTL). 7314 Note that the Overflow and Underflow scenarios are independent of 7315 Data-In and Data-Out. Either scenario is logically possible in 7316 either direction of data transfer. 7318 11.4.5.3. SCSI REPORT LUNS and Residual Overflow 7320 This Section discusses the residual overflow issues citing the 7321 example of the SCSI REPORT LUNS command. Note however that there 7322 are several SCSI commands (e.g., INQUIRY) with ALLOCATION LENGTH 7323 fields following the same underlying rules. The semantics in the 7324 rest of the Section apply to all such SCSI commands. 7326 The specification of the SCSI REPORT LUNS command requires that 7327 the SCSI target limit the amount of data transferred to a maximum 7328 size (ALLOCATION LENGTH) provided by the initiator in the REPORT 7329 LUNS CDB. 7331 If the Expected Data Transfer Length (EDTL) in the iSCSI header of 7332 the SCSI Command PDU for a REPORT LUNS command is set to at least 7333 as large as that ALLOCATION LENGTH, the SCSI layer truncation 7334 prevents an iSCSI Residual Overflow from occurring. A SCSI 7335 initiator can detect that such truncation has occurred via other 7336 information at the SCSI layer. The rest of the Section elaborates 7337 this required behavior. 7339 The SCSI REPORT LUNS command requests a target SCSI layer to 7340 return a logical unit inventory (LUN list) to the initiator SCSI 7341 layer (see Section 6.21 of [SPC3]). The size of this LUN list may 7342 not be known to the initiator SCSI layer when it issues the REPORT 7343 LUNS command; to avoid transferring more LUN list data than the 7344 initiator is prepared for, the REPORT LUNS CDB contains an 7345 ALLOCATION LENGTH field to specify the maximum amount of data to 7346 be transferred to the initiator for this command. If the initiator 7347 SCSI layer has underestimated the number of logical units at the 7348 target, it is possible that the complete logical unit inventory 7349 does not fit in the specified ALLOCATION LENGTH. In this 7350 situation, Section 4.3.3.6 in [SPC3] requires that the target SCSI 7351 layer "shall terminate transfers to the Data-In Buffer" when the 7352 number of bytes specified by the ALLOCATION LENGTH field have been 7353 transferred. 7355 Therefore, in response to a REPORT LUNS command, the SCSI layer at 7356 the target presents at most ALLOCATION LENGTH bytes of data 7357 (logical unit inventory) to iSCSI for transfer to the initiator. 7358 For a REPORT LUNS command, if the iSCSI EDTL is at least as large 7359 as the ALLOCATION LENGTH, the SCSI truncation ensures that the 7360 EDTL will accommodate all of the data to be transferred. If all of 7361 the logical unit inventory data presented to the iSCSI layer -- 7362 i.e., the data remaining after any SCSI truncation -- is 7363 transferred to the initiator by the iSCSI layer, an iSCSI Residual 7364 Overflow has not occurred and the iSCSI (O) bit MUST NOT be set in 7365 the SCSI Response or final SCSI Data-Out PDU. Note that this 7366 behavior is implied by the combination of Section 11.4.5.1 along 7367 with the specification of the REPORT LUNS command in [SPC3]. 7368 However, if the iSCSI EDTL is larger than the ALLOCATION LENGTH in 7369 this scenario, note that the iSCSI Underflow MUST be signaled in 7370 the SCSI Response PDU. An iSCSI Underflow MUST also be signaled 7371 when the iSCSI EDTL is equal to the ALLOCATION LENGTH but the 7372 logical unit inventory data presented to the iSCSI layer is 7373 smaller than the ALLOCATION LENGTH. 7375 The LUN LIST LENGTH field in the logical unit inventory (the first 7376 field in the inventory) is not affected by truncation of the 7377 inventory to fit in ALLOCATION LENGTH; this enables a SCSI 7378 initiator to determine that the received inventory is incomplete 7379 by noticing that the LUN LIST LENGTH in the inventory is larger 7380 than the ALLOCATION LENGTH that was sent in the REPORT LUNS CDB. A 7381 common initiator behavior in this situation is to re-issue the 7382 REPORT LUNS command with a larger ALLOCATION LENGTH. 7384 11.4.6. Bidirectional Read Residual Count 7386 The Bidirectional Read Residual Count field MUST be valid in the 7387 case where either the u bit or the o bit is set. If neither bit is 7388 set, the Bidirectional Read Residual Count field is reserved. 7389 Targets may set the Bidirectional Read Residual Count and 7390 initiators may use it when the response code is "completed at 7391 target". If the o bit is set, the Bidirectional Read Residual 7392 Count indicates the number of bytes that were not transferred to 7393 the initiator because the initiator's Expected Bidirectional Read 7394 Transfer Length was not sufficient. If the u bit is set, the 7395 Bidirectional Read Residual Count indicates the number of bytes 7396 that were not transferred to the initiator out of the number of 7397 bytes expected to be transferred. 7399 11.4.7. Data Segment - Sense and Response Data Segment 7401 iSCSI targets MUST support and enable autosense. If Status is 7402 CHECK CONDITION (0x02), then the Data Segment MUST contain sense 7403 data for the failed command. 7405 For some iSCSI responses, the response data segment MAY contain 7406 some response related information, (e.g., for a target failure, it 7407 may contain a vendor specific detailed description of the 7408 failure). 7410 If the DataSegmentLength is not 0, the format of the Data Segment 7411 is as follows: 7413 Byte/ 0 | 1 | 2 | 3 | 7414 / | | | | 7415 |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| 7416 +---------------+---------------+---------------+--------------+ 7417 0|SenseLength | Sense Data | 7418 +---------------+---------------+---------------+--------------+ 7419 x/ Sense Data / 7420 +---------------+---------------+---------------+--------------+ 7421 y/ Response Data / 7422 / / 7423 +---------------+---------------+---------------+--------------+ 7425 11.4.7.1. SenseLength 7427 Length of Sense Data. 7429 11.4.7.2. Sense Data 7431 The Sense Data contains detailed information about a check 7432 condition and [SPC3] specifies the format and content of the Sense 7433 Data. 7435 Certain iSCSI conditions result in the command being terminated at 7436 the target (response Command Completed at Target) with a SCSI 7437 Check Condition Status as outlined in the next table: 7439 +--------------------------+----------+--------------------------+ 7440 | iSCSI Condition |Sense | Additional Sense Code & | 7441 | |Key | Qualifier | 7442 +--------------------------+----------+--------------------------+ 7443 | Unexpected unsolicited |Aborted | ASC = 0x0c ASCQ = 0x0c | 7444 | data |Command-0B| Write Error | 7445 +--------------------------+----------+--------------------------+ 7446 | Incorrect amount of data |Aborted | ASC = 0x0c ASCQ = 0x0d | 7447 | |Command-0B| Write Error | 7448 +--------------------------+----------+--------------------------+ 7449 | Protocol Service CRC |Aborted | ASC = 0x47 ASCQ = 0x05 | 7450 | error |Command-0B| CRC Error Detected | 7451 +--------------------------+----------+--------------------------+ 7452 | SNACK rejected |Aborted | ASC = 0x11 ASCQ = 0x13 | 7453 | |Command-0B| Read Error | 7454 +--------------------------+----------+--------------------------+ 7456 The target reports the "Incorrect amount of data" condition if 7457 during data output the total data length to output is greater than 7458 FirstBurstLength and the initiator sent unsolicited non-immediate 7459 data but the total amount of unsolicited data is different than 7460 FirstBurstLength. The target reports the same error when the 7461 amount of data sent as a reply to an R2T does not match the amount 7462 requested. 7464 11.4.8. ExpDataSN 7466 The number of Data-In (read) PDUs the target has sent for the 7467 command. 7469 This field MUST be 0 if the response code is not Command Completed 7470 at Target or the target sent no Data-In PDUs for the command. 7472 11.4.9. StatSN - Status Sequence Number 7474 StatSN is a Sequence Number that the target iSCSI layer generates 7475 per connection and that in turn, enables the initiator to 7476 acknowledge status reception. StatSN is incremented by 1 for every 7477 response/status sent on a connection except for responses sent as 7478 a result of a retry or SNACK. In the case of responses sent due to 7479 a retransmission request, the StatSN MUST be the same as the first 7480 time the PDU was sent unless the connection has since been 7481 restarted. 7482 11.4.10. ExpCmdSN - Next Expected CmdSN from this Initiator 7484 ExpCmdSN is a Sequence Number that the target iSCSI returns to the 7485 initiator to acknowledge command reception. It is used to update a 7486 local variable with the same name. An ExpCmdSN equal to MaxCmdSN+1 7487 indicates that the target cannot accept new commands. 7489 11.4.11. MaxCmdSN - Maximum CmdSN from this Initiator 7491 MaxCmdSN is a Sequence Number that the target iSCSI returns to the 7492 initiator to indicate the maximum CmdSN the initiator can send. It 7493 is used to update a local variable with the same name. If MaxCmdSN 7494 is equal to ExpCmdSN-1, this indicates to the initiator that the 7495 target cannot receive any additional commands. When MaxCmdSN 7496 changes at the target while the target has no pending PDUs to 7497 convey this information to the initiator, it MUST generate a NOP- 7498 IN to carry the new MaxCmdSN. 7500 11.5. Task Management Function Request 7502 Byte/ 0 | 1 | 2 | 3 | 7503 / | | | | 7504 |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| 7505 +---------------+---------------+---------------+--------------+ 7506 0|.|I| 0x02 |1| Function | Reserved | 7507 +---------------+---------------+---------------+--------------+ 7508 4|TotalAHSLength | DataSegmentLength | 7509 +---------------+---------------+---------------+--------------+ 7510 8| Logical Unit Number (LUN) or Reserved | 7511 + + 7512 12| | 7513 +---------------+---------------+---------------+--------------+ 7514 16| Initiator Task Tag | 7515 +---------------+---------------+---------------+--------------+ 7516 20| Referenced Task Tag or 0xffffffff | 7517 +---------------+---------------+---------------+--------------+ 7518 24| CmdSN | 7519 +---------------+---------------+---------------+--------------+ 7520 28| ExpStatSN | 7521 +---------------+---------------+---------------+--------------+ 7522 32| RefCmdSN or Reserved | 7523 +---------------+---------------+---------------+--------------+ 7524 36| ExpDataSN or Reserved | 7525 +---------------+---------------+---------------+--------------+ 7526 40/ Reserved / 7527 +/ / 7528 +---------------+---------------+---------------+--------------+ 7529 48| Header-Digest (Optional) | 7530 +---------------+---------------+---------------+--------------+ 7532 11.5.1. Function 7534 The Task Management functions provide an initiator with a way to 7535 explicitly control the execution of one or more Tasks (SCSI and 7536 iSCSI tasks). The Task Management function codes are listed below. 7537 For a more detailed description of SCSI task management, see 7538 [SAM2]. 7540 1 - ABORT TASK - aborts the task identified by the 7541 Referenced Task Tag field. 7543 2 - ABORT TASK SET - aborts all Tasks issued via this 7544 session on the logical unit. 7546 3 - CLEAR ACA - clears the Auto Contingent Allegiance 7547 condition. 7549 4 - CLEAR TASK SET - aborts all Tasks in the appropriate 7550 task set as defined by the TST field in the Control mode 7551 page (see [SPC3]). 7553 5 - LOGICAL UNIT RESET 7555 6 - TARGET WARM RESET 7557 7 - TARGET COLD RESET 7559 8 - TASK REASSIGN - reassigns connection allegiance for the 7560 task identified by the Initiator Task Tag field to this 7561 connection, thus resuming the iSCSI exchanges for the task. 7563 All other possible values for Function field are reserved. 7565 For all these functions, the Task Management function response 7566 MUST be returned as detailed in Section 11.6. All these functions 7567 apply to the referenced tasks regardless of whether they are 7568 proper SCSI tasks or tagged iSCSI operations. Task management 7569 requests must act on all the commands from the same session having 7570 a CmdSN lower than the task management CmdSN. LOGICAL UNIT RESET, 7571 TARGET WARM RESET and TARGET COLD RESET may affect commands from 7572 other sessions or commands from the same session regardless of 7573 their CmdSN value. 7575 If the task management request is marked for immediate delivery, 7576 it must be considered immediately for execution, but the 7577 operations involved (all or part of them) may be postponed to 7578 allow the target to receive all relevant tasks. According to 7579 [SAM2], for all the tasks covered by the Task Management response 7580 (i.e., with CmdSN lower than the task management command CmdSN) 7581 but except the Task Management response to a TASK REASSIGN, 7582 additional responses MUST NOT be delivered to the SCSI layer after 7583 the Task Management response. The iSCSI initiator MAY deliver to 7584 the SCSI layer all responses received before the Task Management 7585 response (i.e., it is a matter of implementation if the SCSI 7586 responses, received before the Task Management response but after 7587 the task management request was issued, are delivered to the SCSI 7588 layer by the iSCSI layer in the initiator). The iSCSI target MUST 7589 ensure that no responses for the tasks covered by a task 7590 management function are delivered to the iSCSI initiator after the 7591 Task Management response except for a task covered by a TASK 7592 REASSIGN. 7594 For ABORT TASK SET and CLEAR TASK SET, the issuing initiator MUST 7595 continue to respond to all valid target transfer tags (received 7596 via R2T, Text Response, NOP-In, or SCSI Data-in PDUs) related to 7597 the affected task set, even after issuing the task management 7598 request. The issuing initiator SHOULD however terminate (i.e., by 7599 setting the F-bit to 1) these response sequences as quickly as 7600 possible. The target on its part MUST wait for responses on all 7601 affected target transfer tags before acting on either of these two 7602 task management requests. In case all or part of the response 7603 sequence is not received (due to digest errors) for a valid TTT, 7604 the target MAY treat it as a case of within-command error recovery 7605 class (see Section 7.1.4.1) if it is supporting ErrorRecoveryLevel 7606 >= 1, or alternatively may drop the connection to complete the 7607 requested task set function. 7609 If an ABORT TASK is issued for a task created by an immediate 7610 command then RefCmdSN MUST be that of the Task Management request 7611 itself (i.e. CmdSN and RefCmdSN are equal); otherwise RefCmdSN 7612 MUST be set to the CmdSN of the task to be aborted (lower than 7613 CmdSN). 7615 If the connection is still active (it is not undergoing an 7616 implicit or explicit logout), ABORT TASK MUST be issued on the 7617 same connection to which the task to be aborted is allegiant at 7618 the time the Task Management Request is issued. If the connection 7619 is implicitly or explicitly logged out (i.e., no other request 7620 will be issued on the failing connection and no other response 7621 will be received on the failing connection), then an ABORT TASK 7622 function request may be issued on another connection. This Task 7623 Management request will then establish a new allegiance for the 7624 command to be aborted as well as abort it (i.e., the task to be 7625 aborted will not have to be retried or reassigned, and its status, 7626 if sent but not acknowledged, will be resent followed by the Task 7627 Management response). 7629 At the target an ABORT TASK function MUST NOT be executed on a 7630 Task Management request; such a request MUST result in Task 7631 Management response of "Function rejected". 7633 For the LOGICAL UNIT RESET function, the target MUST behave as 7634 dictated by the Logical Unit Reset function in [SAM2]. 7636 The implementation of the TARGET WARM RESET function and the 7637 TARGET COLD RESET function is OPTIONAL and when implemented, 7638 should act as described below. The TARGET WARM RESET is also 7639 subject to SCSI access controls on the requesting initiator as 7640 defined in [SPC3]. When authorization fails at the target, the 7641 appropriate response as described in Section 11.6.1 MUST be 7642 returned by the target. The TARGET COLD RESET function is not 7643 subject to SCSI access controls, but its execution privileges may 7644 be managed by iSCSI mechanisms such as login authentication. 7646 When executing the TARGET WARM RESET and TARGET COLD RESET 7647 functions, the target cancels all pending operations on all 7648 Logical Units known by the issuing initiator. Both functions are 7649 equivalent to the Target Reset function specified by [SAM2]. They 7650 can affect many other initiators logged in with the servicing SCSI 7651 target port. 7653 The target MUST treat the TARGET COLD RESET function additionally 7654 as a power on event, thus terminating all of its TCP connections 7655 to all initiators (all sessions are terminated). For this reason, 7656 the Service Response (defined by [SAM2]) for this SCSI task 7657 management function may not be reliably delivered to the issuing 7658 initiator port. 7660 For the TASK REASSIGN function, the target should reassign the 7661 connection allegiance to this new connection (and thus resume 7662 iSCSI exchanges for the task). TASK REASSIGN MUST ONLY be received 7663 by the target after the connection on which the command was 7664 previously executing has been successfully logged-out. The Task 7665 Management response MUST be issued before the reassignment becomes 7666 effective. 7668 For additional usage semantics see Section 7.2. 7670 At the target a TASK REASSIGN function request MUST NOT be 7671 executed to reassign the connection allegiance of a Task 7672 Management function request, an active text negotiation task, or a 7673 Logout task; such a request MUST result in Task Management 7674 response of "Function rejected". 7676 TASK REASSIGN MUST be issued as an immediate command. 7678 11.5.2. TotalAHSLength and DataSegmentLength 7680 For this PDU, TotalAHSLength and DataSegmentLength MUST be 0. 7682 11.5.3. LUN 7684 This field is required for functions that address a specific LU 7685 (ABORT TASK, CLEAR TASK SET, ABORT TASK SET, CLEAR ACA, LOGICAL 7686 UNIT RESET) and is reserved in all others. 7688 11.5.4. Referenced Task Tag 7690 The Initiator Task Tag of the task to be aborted for the ABORT 7691 TASK function or reassigned for the TASK REASSIGN function. For 7692 all the other functions this field MUST be set to the reserved 7693 value 0xffffffff. 7695 11.5.5. RefCmdSN 7697 If an ABORT TASK is issued for a task created by an immediate 7698 command then RefCmdSN MUST be that of the Task Management request 7699 itself (i.e. CmdSN and RefCmdSN are equal). 7701 For an ABORT TASK of a task created by non-immediate command 7702 RefCmdSN MUST be set to the CmdSN of the task identified by the 7703 Referenced Task Tag field. Targets must use this field as 7704 described in Section 11.6.1 when the task identified by the 7705 Referenced Task Tag field is not with the target. 7707 Otherwise, this field is reserved. 7709 11.5.6. ExpDataSN 7711 For recovery purposes, the iSCSI target and initiator maintain a 7712 data acknowledgement reference number - the first input DataSN 7713 number unacknowledged by the initiator. When issuing a new 7714 command, this number is set to 0. If the function is TASK 7715 REASSIGN, which establishes a new connection allegiance for a 7716 previously issued Read or Bidirectional command, ExpDataSN will 7717 contain an updated data acknowledgement reference number or the 7718 value 0; the latter indicating that the data acknowledgement 7719 reference number is unchanged. The initiator MUST discard any data 7720 PDUs from the previous execution that it did not acknowledge and 7721 the target MUST transmit all Data-in PDUs (if any) starting with 7722 the data acknowledgement reference number. The number of 7723 retransmitted PDUs may or may not be the same as the original 7724 transmission depending on if there was a change in 7725 MaxRecvDataSegmentLength in the reassignment. The target MAY also 7726 send no more Data-In PDUs if all data has been acknowledged. 7728 The value of ExpDataSN MUST be 0 or higher than the DataSN of the 7729 last acknowledged Data-In PDU, but not larger than DataSN+1 of the 7730 last Data-IN PDU sent by the target. Any other value MUST be 7731 ignored by the target. 7733 For other functions this field is reserved. 7735 11.6. Task Management Function Response 7736 Byte/ 0 | 1 | 2 | 3 | 7737 / | | | | 7738 |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| 7739 +---------------+---------------+---------------+--------------+ 7740 0|.|.| 0x22 |1| Reserved | Response | Reserved | 7741 +---------------+---------------+---------------+--------------+ 7742 4|TotalAHSLength | DataSegmentLength | 7743 +--------------------------------------------------------------+ 7744 8/ Reserved / 7745 / / 7746 +---------------+---------------+---------------+--------------+ 7747 16| Initiator Task Tag | 7748 +---------------+---------------+---------------+--------------+ 7749 20| Reserved | 7750 +---------------+---------------+---------------+--------------+ 7751 24| StatSN | 7752 +---------------+---------------+---------------+--------------+ 7753 28| ExpCmdSN | 7754 +---------------+---------------+---------------+--------------+ 7755 32| MaxCmdSN | 7756 +---------------+---------------+---------------+--------------+ 7757 36/ Reserved / 7758 +/ / 7759 +---------------+---------------+---------------+--------------+ 7760 48| Header-Digest (Optional) | 7761 +---------------+---------------+---------------+--------------+ 7763 For the functions ABORT TASK, ABORT TASK SET, CLEAR ACA, CLEAR 7764 TASK SET, LOGICAL UNIT RESET, TARGET COLD RESET, TARGET WARM RESET 7765 and TASK REASSIGN, the target performs the requested Task 7766 Management function and sends a Task Management response back to 7767 the initiator. For TASK REASSIGN, the new connection allegiance 7768 MUST ONLY become effective at the target after the target issues 7769 the Task Management Response. 7771 11.6.1. Response 7773 The target provides a Response, which may take on the following 7774 values: 7776 0 - Function complete. 7777 1 - Task does not exist. 7779 2 - LUN does not exist. 7780 3 - Task still allegiant. 7781 4 - Task allegiance reassignment not supported. 7782 5 - Task management function not supported. 7783 6 - Function authorization failed. 7784 255 - Function rejected. 7786 All other values are reserved. 7788 For a discussion on usage of response codes 3 and 4, see Section 7789 7.2.2. 7791 For the TARGET COLD RESET and TARGET WARM RESET functions, the 7792 target cancels all pending operations across all Logical Units 7793 known to the issuing initiator. For the TARGET COLD RESET 7794 function, the target MUST then close all of its TCP connections to 7795 all initiators (terminates all sessions). 7797 The mapping of the response code into a SCSI service response code 7798 value, if needed, is outside the scope of this document. However, 7799 in symbolic terms, Response values 0 and 1 map to the SCSI service 7800 response of FUNCTION COMPLETE. Response value 2 maps to SCSI 7801 service response of INCORRECT LOGICAL UNIT NUMBER. All other 7802 Response values map to the SCSI service response of FUNCTION 7803 REJECTED. If a Task Management function response PDU does not 7804 arrive before the session is terminated, the SCSI service response 7805 is SERVICE DELIVERY OR TARGET FAILURE. 7807 The response to ABORT TASK SET and CLEAR TASK SET MUST only be 7808 issued by the target after all of the commands affected have been 7809 received by the target, the corresponding task management 7810 functions have been executed by the SCSI target, and the delivery 7811 of all responses delivered until the task management function 7812 completion have been confirmed (acknowledged through ExpStatSN) by 7813 the initiator on all connections of this session. For the exact 7814 timeline of events, refer to Section 4.2.3.3 and Section 4.2.3.4. 7816 For the ABORT TASK function, 7817 a) If the Referenced Task Tag identifies a valid task leading 7818 to a successful termination, then targets must return the 7819 "Function complete" response. 7820 b) If the Referenced Task Tag does not identify an existing 7821 task, but if the CmdSN indicated by the RefCmdSN field in 7822 the Task Management function request is within the valid 7823 CmdSN window and less than the CmdSN of the Task Management 7824 function request itself, then targets must consider the 7825 CmdSN received and return the "Function complete" response. 7826 c) If the Referenced Task Tag does not identify an existing 7827 task and if the CmdSN indicated by the RefCmdSN field in 7828 the Task Management function request is outside the valid 7829 CmdSN window, then targets must return the "Task does not 7830 exist" response. 7832 For response semantics on function types that can potentially 7833 impact multiple active tasks on the target, see Section 4.2.3. 7835 11.6.2. TotalAHSLength and DataSegmentLength 7837 For this PDU TotalAHSLength and DataSegmentLength MUST be 0. 7839 11.7. SCSI Data-out & SCSI Data-in 7841 The SCSI Data-out PDU for WRITE operations has the following 7842 format: 7844 Byte/ 0 | 1 | 2 | 3 | 7845 / | | | | 7846 |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| 7847 +---------------+---------------+---------------+--------------+ 7848 0|.|.| 0x05 |F| Reserved | 7849 +---------------+---------------+---------------+--------------+ 7850 4|TotalAHSLength | DataSegmentLength | 7851 +---------------+---------------+---------------+--------------+ 7852 8| LUN or Reserved | 7853 + + 7854 12| | 7855 +---------------+---------------+---------------+--------------+ 7856 16| Initiator Task Tag | 7857 +---------------+---------------+---------------+--------------+ 7858 20| Target Transfer Tag or 0xffffffff | 7859 +---------------+---------------+---------------+--------------+ 7860 24| Reserved | 7861 +---------------+---------------+---------------+--------------+ 7862 28| ExpStatSN | 7863 +---------------+---------------+---------------+--------------+ 7864 32| Reserved | 7865 +---------------+---------------+---------------+--------------+ 7866 36| DataSN | 7867 +---------------+---------------+---------------+--------------+ 7868 40| Buffer Offset | 7869 +---------------+---------------+---------------+--------------+ 7870 44| Reserved | 7871 +---------------+---------------+---------------+--------------+ 7872 48| Header-Digest (Optional) | 7873 +---------------+---------------+---------------+--------------+ 7874 / DataSegment / 7875 +/ / 7876 +---------------+---------------+---------------+--------------+ 7877 | Data-Digest (Optional) | 7878 +---------------+---------------+---------------+--------------+ 7880 The SCSI Data-in PDU for READ operations has the following format: 7882 Byte/ 0 | 1 | 2 | 3 | 7883 / | | | | 7884 |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| 7885 +---------------+---------------+---------------+--------------+ 7886 0|.|.| 0x25 |F|A|0 0 0|O|U|S| Reserved |Status or Rsvd| 7887 +---------------+---------------+---------------+--------------+ 7888 4|TotalAHSLength | DataSegmentLength | 7889 +---------------+---------------+---------------+--------------+ 7890 8| LUN or Reserved | 7891 + + 7892 12| | 7893 +---------------+---------------+---------------+--------------+ 7894 16| Initiator Task Tag | 7895 +---------------+---------------+---------------+--------------+ 7896 20| Target Transfer Tag or 0xffffffff | 7897 +---------------+---------------+---------------+--------------+ 7898 24| StatSN or Reserved | 7899 +---------------+---------------+---------------+--------------+ 7900 28| ExpCmdSN | 7901 +---------------+---------------+---------------+--------------+ 7902 32| MaxCmdSN | 7903 +---------------+---------------+---------------+--------------+ 7904 36| DataSN | 7905 +---------------+---------------+---------------+--------------+ 7906 40| Buffer Offset | 7907 +---------------+---------------+---------------+--------------+ 7908 44| Residual Count | 7909 +---------------+---------------+---------------+--------------+ 7910 48| Header-Digest (Optional) | 7911 +---------------+---------------+---------------+--------------+ 7912 / DataSegment / 7913 +/ / 7914 +---------------+---------------+---------------+--------------+ 7915 | Data-Digest (Optional) | 7916 +---------------+---------------+---------------+--------------+ 7918 Status can accompany the last Data-in PDU if the command did not 7919 end with an exception (i.e., the status is "good status" - GOOD, 7920 CONDITION MET or INTERMEDIATE CONDITION MET). The presence of 7921 status (and of a residual count) is signaled though the S flag 7922 bit. Although targets MAY choose to send even non-exception 7923 status in separate responses, initiators MUST support non- 7924 exception status in Data-In PDUs. 7926 11.7.1. F (Final) Bit 7928 For outgoing data, this bit is 1 for the last PDU of unsolicited 7929 data or the last PDU of a sequence that answers an R2T. 7931 For incoming data, this bit is 1 for the last input (read) data 7932 PDU of a sequence. Input can be split into several sequences, 7933 each having its own F bit. Splitting the data stream into 7934 sequences does not affect DataSN counting on Data-In PDUs. It MAY 7935 be used as a "change direction" indication for Bidirectional 7936 operations that need such a change. 7938 DataSegmentLength MUST NOT exceed MaxRecvDataSegmentLength for the 7939 direction it is sent and the total of all the DataSegmentLength of 7940 all PDUs in a sequence MUST NOT exceed MaxBurstLength (or 7941 FirstBurstLength for unsolicited data). However the number of 7942 individual PDUs in a sequence (or in total) may be higher than the 7943 MaxBurstLength (or FirstBurstLength) to MaxRecvDataSegmentLength 7944 ratio (as PDUs may be limited in length by the sender 7945 capabilities). Using DataSegmentLength of 0 may increase beyond 7946 what is reasonable for the number of PDUs and should therefore be 7947 avoided. 7949 For Bidirectional operations, the F bit is 1 for both the end of 7950 the input sequences and the end of the output sequences. 7952 11.7.2. A (Acknowledge) bit 7954 For sessions with ErrorRecoveryLevel 1 or higher, the target sets 7955 this bit to 1 to indicate that it requests a positive 7956 acknowledgement from the initiator for the data received. The 7957 target should use the A bit moderately; it MAY only set the A bit 7958 to 1 once every MaxBurstLength bytes, or on the last Data-In PDU 7959 that concludes the entire requested read data transfer for the 7960 task from the target's perspective, and it MUST NOT do so more 7961 frequently. The target MUST NOT set to 1 the A bit for sessions 7962 with ErrorRecoveryLevel=0. The initiator MUST ignore the A bit set 7963 to 1 for sessions with ErrorRecoveryLevel=0. 7965 On receiving a Data-In PDU with the A bit set to 1 on a session 7966 with ErrorRecoveryLevel greater than 0, if there are no holes in 7967 the read data until that Data-In PDU, the initiator MUST issue a 7968 SNACK of type DataACK except when it is able to acknowledge the 7969 status for the task immediately via ExpStatSN on other outbound 7970 PDUs if the status for the task is also received. In the latter 7971 case (acknowledgement through ExpStatSN), sending a SNACK of type 7972 DataACK in response to the A bit is OPTIONAL, but if it is done, 7973 it must not be sent after the status acknowledgement through 7974 ExpStatSN. If the initiator has detected holes in the read data 7975 prior to that Data-In PDU, it MUST postpone issuing the SNACK of 7976 type DataACK until the holes are filled. An initiator also MUST 7977 NOT acknowledge the status for the task before those holes are 7978 filled. A status acknowledgement for a task that generated the 7979 Data-In PDUs is considered by the target as an implicit 7980 acknowledgement of the Data-In PDUs if such an acknowledgement was 7981 requested by the target. 7983 11.7.3. Flags (byte 1) 7985 The last SCSI Data packet sent from a target to an initiator for a 7986 SCSI command that completed successfully (with a status of GOOD, 7987 CONDITION MET, INTERMEDIATE or INTERMEDIATE CONDITION MET) may 7988 also optionally contain the Status for the data transfer. In this 7989 case, Sense Data cannot be sent together with the Command Status. 7990 If the command is completed with an error, then the response and 7991 sense data MUST be sent in a SCSI Response PDU (i.e., MUST NOT be 7992 sent in a SCSI Data packet). For Bidirectional commands, the 7993 status MUST be sent in a SCSI Response PDU. 7995 bit 2-4 - Reserved. 7997 bit 5-6 - used the same as in a SCSI Response. These bits are 7998 only valid when S is set to 1. For details see SNACK . 8000 bit 7 S (status)- set to indicate that the Command Status 8001 field contains status. If this bit is set to 1, the F bit 8002 MUST also be set to 1. 8004 The fields StatSN, Status, and Residual Count only have meaningful 8005 content if the S bit is set to 1 and their values are defined in 8006 SNACK . 8008 11.7.4. Target Transfer Tag and LUN 8010 On outgoing data, the Target Transfer Tag is provided to the 8011 target if the transfer is honoring an R2T. In this case, the 8012 Target Transfer Tag field is a replica of the Target Transfer Tag 8013 provided with the R2T. 8015 On incoming data, the Target Transfer Tag and LUN MUST be provided 8016 by the target if the A bit is set to 1; otherwise they are 8017 reserved. The Target Transfer Tag and LUN are copied by the 8018 initiator into the SNACK of type DataACK that it issues as a 8019 result of receiving a SCSI Data-in PDU with the A bit set to 1. 8021 The Target Transfer Tag values are not specified by this protocol 8022 except that the value 0xffffffff is reserved and means that the 8023 Target Transfer Tag is not supplied. If the Target Transfer Tag 8024 is provided, then the LUN field MUST hold a valid value and be 8025 consistent with whatever was specified with the command; 8026 otherwise, the LUN field is reserved. 8028 11.7.5. DataSN 8030 For input (read) or bidirectional Data-In PDUs, the DataSN is the 8031 input PDU number within the data transfer for the command 8032 identified by the Initiator Task Tag. 8034 R2T and Data-In PDUs, in the context of bidirectional commands, 8035 share the numbering sequence (see Section 4.2.2.4). 8037 For output (write) data PDUs, the DataSN is the Data-Out PDU 8038 number within the current output sequence. The current output 8039 sequence is either identified by the Initiator Task Tag (for 8040 unsolicited data) or is a data sequence generated for one R2T (for 8041 data solicited through R2T). 8043 11.7.6. Buffer Offset 8045 The Buffer Offset field contains the offset of this PDU payload 8046 data within the complete data transfer. The sum of the buffer 8047 offset and length should not exceed the expected transfer length 8048 for the command. 8050 The order of data PDUs within a sequence is determined by 8051 DataPDUInOrder. When set to Yes, it means that PDUs have to be in 8052 increasing Buffer Offset order and overlays are forbidden. 8054 The ordering between sequences is determined by 8055 DataSequenceInOrder. When set to Yes, it means that sequences have 8056 to be in increasing Buffer Offset order and overlays are 8057 forbidden. 8059 11.7.7. DataSegmentLength 8061 This is the data payload length of a SCSI Data-In or SCSI Data-Out 8062 PDU. The sending of 0 length data segments should be avoided, but 8063 initiators and targets MUST be able to properly receive 0 length 8064 data segments. 8066 The Data Segments of Data-in and Data-out PDUs SHOULD be filled to 8067 the integer number of 4 byte words (real payload) unless the F bit 8068 is set to 1. 8070 11.8. Ready To Transfer (R2T) 8072 Byte/ 0 | 1 | 2 | 3 | 8073 / | | | | 8074 |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| 8075 +---------------+---------------+---------------+--------------+ 8076 0|.|.| 0x31 |1| Reserved | 8077 +---------------+---------------+---------------+--------------+ 8078 4|TotalAHSLength | DataSegmentLength | 8079 +---------------+---------------+---------------+--------------+ 8080 8| LUN | 8081 + + 8082 12| | 8083 +---------------+---------------+---------------+--------------+ 8084 16| Initiator Task Tag | 8085 +---------------+---------------+---------------+--------------+ 8086 20| Target Transfer Tag | 8087 +---------------+---------------+---------------+--------------+ 8088 24| StatSN | 8089 +---------------+---------------+---------------+--------------+ 8090 28| ExpCmdSN | 8091 +---------------+---------------+---------------+--------------+ 8092 32| MaxCmdSN | 8093 +---------------+---------------+---------------+--------------+ 8094 36| R2TSN | 8095 +---------------+---------------+---------------+--------------+ 8096 40| Buffer Offset | 8097 +---------------+---------------+---------------+--------------+ 8098 44| Desired Data Transfer Length | 8099 +--------------------------------------------------------------+ 8100 48| Header-Digest (Optional) | 8101 +---------------+---------------+---------------+--------------+ 8103 When an initiator has submitted a SCSI Command with data that 8104 passes from the initiator to the target (WRITE), the target may 8105 specify which blocks of data it is ready to receive. The target 8106 may request that the data blocks be delivered in whichever order 8107 is convenient for the target at that particular instant. This 8108 information is passed from the target to the initiator in the 8109 Ready To Transfer (R2T) PDU. 8111 In order to allow write operations without an explicit initial 8112 R2T, the initiator and target MUST have negotiated the key 8113 InitialR2T to No during Login. 8115 An R2T MAY be answered with one or more SCSI Data-out PDUs with a 8116 matching Target Transfer Tag. If an R2T is answered with a single 8117 Data-out PDU, the Buffer Offset in the Data PDU MUST be the same 8118 as the one specified by the R2T, and the data length of the Data 8119 PDU MUST be the same as the Desired Data Transfer Length specified 8120 in the R2T. If the R2T is answered with a sequence of Data PDUs, 8121 the Buffer Offset and Length MUST be within the range of those 8122 specified by R2T, and the last PDU MUST have the F bit set to 1. 8123 If the last PDU (marked with the F bit) is received before the 8124 Desired Data Transfer Length is transferred, a target MAY choose 8125 to Reject that PDU with "Protocol error" reason code. 8126 DataPDUInOrder governs the Data-Out PDU ordering. If 8127 DataPDUInOrder is set to Yes, the Buffer Offsets and Lengths for 8128 consecutive PDUs MUST form a continuous non-overlapping range and 8129 the PDUs MUST be sent in increasing offset order. 8131 The target may send several R2T PDUs. It, therefore, can have a 8132 number of pending data transfers. The number of outstanding R2T 8133 PDUs are limited by the value of the negotiated key 8134 MaxOutstandingR2T. Within a task, outstanding R2Ts MUST be 8135 fulfilled by the initiator in the order in which they were 8136 received. 8138 R2T PDUs MAY also be used to recover Data Out PDUs. Such an R2T 8139 (Recovery-R2T) is generated by a target upon detecting the loss of 8140 one or more Data-Out PDUs due to: 8142 - Digest error 8144 - Sequence error 8146 - Sequence reception timeout 8148 A Recovery-R2T carries the next unused R2TSN, but requests part of 8149 or the entire data burst that an earlier R2T (with a lower R2TSN) 8150 had already requested. 8152 DataSequenceInOrder governs the buffer offset ordering in 8153 consecutive R2Ts. If DataSequenceInOrder is Yes, then consecutive 8154 R2Ts MUST refer to continuous non-overlapping ranges except for 8155 Recovery-R2Ts. 8157 11.8.1. TotalAHSLength and DataSegmentLength 8159 For this PDU TotalAHSLength and DataSegmentLength MUST be 0. 8161 11.8.2. R2TSN 8163 R2TSN is the R2T PDU input PDU number within the command 8164 identified by the Initiator Task Tag. 8166 For bidirectional commands R2T and Data-In PDUs share the input 8167 PDU numbering sequence (see Section 4.2.2.4). 8169 11.8.3. StatSN 8171 The StatSN field will contain the next StatSN. The StatSN for this 8172 connection is not advanced after this PDU is sent. 8174 11.8.4. Desired Data Transfer Length and Buffer Offset 8176 The target specifies how many bytes it wants the initiator to send 8177 because of this R2T PDU. The target may request the data from the 8178 initiator in several chunks, not necessarily in the original order 8179 of the data. The target, therefore, also specifies a Buffer Offset 8180 that indicates the point at which the data transfer should begin, 8181 relative to the beginning of the total data transfer. The Desired 8182 Data Transfer Length MUST NOT be 0 and MUST NOT exceed 8183 MaxBurstLength. 8185 11.8.5. Target Transfer Tag 8187 The target assigns its own tag to each R2T request that it sends 8188 to the initiator. This tag can be used by the target to easily 8189 identify the data it receives. The Target Transfer Tag and LUN are 8190 copied in the outgoing data PDUs and are only used by the target. 8191 There is no protocol rule about the Target Transfer Tag except 8192 that the value 0xffffffff is reserved and MUST NOT be sent by a 8193 target in an R2T. 8195 11.9. Asynchronous Message 8197 An Asynchronous Message may be sent from the target to the 8198 initiator without correspondence to a particular command. The 8199 target specifies the reason for the event and sense data. 8201 Byte/ 0 | 1 | 2 | 3 | 8202 / | | | | 8203 |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| 8204 +---------------+---------------+---------------+--------------+ 8205 0|.|.| 0x32 |1| Reserved | 8206 +---------------+---------------+---------------+--------------+ 8207 4|TotalAHSLength | DataSegmentLength | 8208 +---------------+---------------+---------------+--------------+ 8209 8| LUN or Reserved | 8210 + + 8211 12| | 8212 +---------------+---------------+---------------+--------------+ 8213 16| 0xffffffff | 8214 +---------------+---------------+---------------+--------------+ 8215 20| Reserved | 8216 +---------------+---------------+---------------+--------------+ 8217 24| StatSN | 8218 +---------------+---------------+---------------+--------------+ 8219 28| ExpCmdSN | 8220 +---------------+---------------+---------------+--------------+ 8221 32| MaxCmdSN | 8222 +---------------+---------------+---------------+--------------+ 8223 36| AsyncEvent | AsyncVCode | Parameter1 or Reserved | 8224 +---------------+---------------+---------------+--------------+ 8225 40| Parameter2 or Reserved | Parameter3 or Reserved | 8226 +---------------+---------------+---------------+--------------+ 8227 44| Reserved | 8228 +---------------+---------------+---------------+--------------+ 8229 48| Header-Digest (Optional) | 8230 +---------------+---------------+---------------+--------------+ 8231 / DataSegment - Sense Data and iSCSI Event Data / 8232 +/ / 8233 +---------------+---------------+---------------+--------------+ 8234 | Data-Digest (Optional) | 8235 +---------------+---------------+---------------+--------------+ 8237 Some Asynchronous Messages are strictly related to iSCSI while 8238 others are related to SCSI [SAM2]. 8240 StatSN counts this PDU as an acknowledgeable event (StatSN is 8241 advanced), which allows for initiator and target state 8242 synchronization. 8244 11.9.1. AsyncEvent 8246 The codes used for iSCSI Asynchronous Messages (events) are: 8248 0 (SCSI_ASYNC) - a SCSI Asynchronous Event is reported in the 8249 sense data. Sense Data that accompanies the report, in the 8250 data segment, identifies the condition. The sending of a 8251 SCSI Event (Asynchronous Event Reporting in SCSI 8252 terminology) is dependent on the target support for SCSI 8253 asynchronous event reporting (see [SAM2]) as indicated in 8254 the standard INQUIRY data (see [SPC3]). Its use may be 8255 enabled by parameters in the SCSI Control mode page (see 8256 [SPC3]). 8258 1 (REQUEST_LOGOUT) - target requests Logout. This Async 8259 Message MUST be sent on the same connection as the one 8260 requesting to be logged out. The initiator MUST honor this 8261 request by issuing a Logout as early as possible, but no 8262 later than Parameter3 seconds. Initiator MUST send a 8263 Logout with a reason code of "Close the connection" OR 8264 "Close the session" to close all the connections. Once this 8265 message is received, the initiator SHOULD NOT issue new 8266 iSCSI commands on the connection to be logged out. The 8267 target MAY reject any new I/O requests that it receives 8268 after this Message with the reason code "Waiting for 8269 Logout". If the initiator does not Logout in Parameter3 8270 seconds, the target should send an Async PDU with iSCSI 8271 event code "Dropped the connection" if possible, or simply 8272 terminate the transport connection. Parameter1 and 8273 Parameter2 are reserved. 8275 2 (CONNECTION_DROP) - target indicates it will drop the 8276 connection. 8278 The Parameter1 field indicates the CID of the connection 8279 going to be dropped. 8281 The Parameter2 field (Time2Wait) indicates, in seconds, the 8282 minimum time to wait before attempting to reconnect or 8283 reassign. 8285 The Parameter3 field (Time2Retain) indicates the maximum 8286 time allowed to reassign commands after the initial wait (in 8287 Parameter2). 8289 If the initiator does not attempt to reconnect and/or 8290 reassign the outstanding commands within the time specified 8291 by Parameter3, or if Parameter3 is 0, the target will 8292 terminate all outstanding commands on this connection. In 8293 this case, no other responses should be expected from the 8294 target for the outstanding commands on this connection. 8296 A value of 0 for Parameter2 indicates that reconnect can be 8297 attempted immediately. 8299 3 (SESSION_DROP) - target indicates it will drop all the 8300 connections of this session. 8302 Parameter1 field is reserved. 8304 The Parameter2 field (Time2Wait) indicates, in seconds, the 8305 minimum time to wait before attempting to reconnect. 8306 The Parameter3 field (Time2Retain) indicates the maximum 8307 time allowed to reassign commands after the initial wait (in 8308 Parameter2). 8310 If the initiator does not attempt to reconnect and/or 8311 reassign the outstanding commands within the time specified 8312 by Parameter3, or if Parameter3 is 0, the session is 8313 terminated. In this case, the target will terminate all 8314 outstanding commands in this session; no other responses 8315 should be expected from the target for the outstanding 8316 commands in this session. A value of 0 for Parameter2 8317 indicates that reconnect can be attempted immediately. 8319 4 (RENEGOTIATE) - target requests parameter negotiation on 8320 this connection. The initiator MUST honor this request by 8321 issuing a Text Request (that can be empty) on the same 8322 connection as early as possible, but no later than 8323 Parameter3 seconds, unless a Text Request is already pending 8324 on the connection, or by issuing a Logout Request. If the 8325 initiator does not issue a Text Request the target may 8326 reissue the Asynchronous Message requesting parameter 8327 negotiation. 8329 5 (FAST_ABORT) - all active tasks for LU with a matching LUN 8330 field in the Async Message PDU are being terminated. The 8331 receiving initiator iSCSI layer MUST respond to this Message 8332 by taking the following steps in order. 8334 - Stop Data-Out transfers on that connection for all active 8335 TTTs for the affected LUN quoted in the Async Message 8336 PDU. 8337 - Acknowledge the StatSN of the Async Message PDU via a NOP- 8338 Out PDU with ITT=0xffffffff (i.e., non-ping flavor), 8339 while copying the LUN field from the Async Message to 8340 NOP-Out. 8342 This value of AsyncEvent however MUST NOT be used on an 8343 iSCSI session unless the new TaskReporting text key defined 8344 in Section 13.23 was negotiated to FastAbort on the session. 8346 255 - vendor-specific iSCSI Event. The AsyncVCode details the 8347 vendor code, and data MAY accompany the report. 8349 All other event codes are reserved. 8351 11.9.2. AsyncVCode 8353 AsyncVCode is a vendor specific detail code that is only valid if 8354 the AsyncEvent field indicates a vendor specific event. Otherwise, 8355 it is reserved. 8357 11.9.3. LUN 8359 The LUN field MUST be valid if AsyncEvent is 0. Otherwise, this 8360 field is reserved. 8362 11.9.4. Sense Data and iSCSI Event Data 8364 For a SCSI event, this data accompanies the report in the data 8365 segment and identifies the condition. 8367 For an iSCSI event, additional vendor-unique data MAY accompany 8368 the Async event. Initiators MAY ignore the data when not 8369 understood while processing the rest of the PDU. 8371 If the DataSegmentLength is not 0, the format of the DataSegment 8372 is as follows: 8374 Byte/ 0 | 1 | 2 | 3 | 8375 / | | | | 8376 |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| 8377 +---------------+---------------+---------------+--------------+ 8378 0|SenseLength | Sense Data | 8379 +---------------+---------------+---------------+--------------+ 8380 x/ Sense Data / 8381 +---------------+---------------+---------------+--------------+ 8382 y/ iSCSI Event Data / 8383 / / 8384 +---------------+---------------+---------------+--------------+ 8385 z| 8387 11.9.4.1. SenseLength 8389 This is the length of Sense Data. When the Sense Data field is 8390 empty (e.g., the event is not a SCSI event) SenseLength is 0. 8392 11.10. Text Request 8394 The Text Request is provided to allow for the exchange of 8395 information and for future extensions. It permits the initiator to 8396 inform a target of its capabilities or to request some special 8397 operations. 8399 Byte/ 0 | 1 | 2 | 3 | 8400 / | | | | 8401 |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| 8402 +---------------+---------------+---------------+--------------+ 8403 0|.|I| 0x04 |F|C| Reserved | 8404 +---------------+---------------+---------------+--------------+ 8405 4|TotalAHSLength | DataSegmentLength | 8406 +---------------+---------------+---------------+--------------+ 8407 8| LUN or Reserved | 8408 + + 8409 12| | 8410 +---------------+---------------+---------------+--------------+ 8411 16| Initiator Task Tag | 8412 +---------------+---------------+---------------+--------------+ 8413 20| Target Transfer Tag or 0xffffffff | 8414 +---------------+---------------+---------------+--------------+ 8415 24| CmdSN | 8416 +---------------+---------------+---------------+--------------+ 8417 28| ExpStatSN | 8418 +---------------+---------------+---------------+--------------+ 8419 32/ Reserved / 8420 +/ / 8421 +---------------+---------------+---------------+--------------+ 8422 48| Header-Digest (Optional) | 8423 +---------------+---------------+---------------+--------------+ 8424 / DataSegment (Text) / 8425 +/ / 8426 +---------------+---------------+---------------+--------------+ 8427 | Data-Digest (Optional) | 8428 +---------------+---------------+---------------+--------------+ 8430 An initiator MUST NOT have more than one outstanding Text Request 8431 on a connection at any given time. 8433 On a connection failure, an initiator must either explicitly abort 8434 any active allegiant text negotiation task or must cause such a 8435 task to be implicitly terminated by the target. 8437 11.10.1. F (Final) Bit 8439 When set to 1, indicates that this is the last or only text 8440 request in a sequence of Text Requests; otherwise, it indicates 8441 that more Text Requests will follow. 8443 11.10.2. C (Continue) Bit 8445 When set to 1, indicates that the text (set of key=value pairs) in 8446 this Text Request is not complete (it will be continued on 8447 subsequent Text Requests); otherwise, it indicates that this Text 8448 Request ends a set of key=value pairs. A Text Request with the C 8449 bit set to 1 MUST have the F bit set to 0. 8451 11.10.3. Initiator Task Tag 8453 The initiator assigned identifier for this Text Request. If the 8454 command is sent as part of a sequence of text requests and 8455 responses, the Initiator Task Tag MUST be the same for all the 8456 requests within the sequence (similar to linked SCSI commands). 8457 The I bit for all requests in a sequence also MUST be the same. 8459 11.10.4. Target Transfer Tag 8461 When the Target Transfer Tag is set to the reserved value 8462 0xffffffff, it tells the target that this is a new request and the 8463 target resets any internal state associated with the Initiator 8464 Task Tag (resets the current negotiation state). 8466 The target sets the Target Transfer Tag in a text response to a 8467 value other than the reserved value 0xffffffff whenever it 8468 indicates that it has more data to send or more operations to 8469 perform that are associated with the specified Initiator Task Tag. 8470 It MUST do so whenever it sets the F bit to 0 in the response. By 8471 copying the Target Transfer Tag from the response to the next Text 8472 Request, the initiator tells the target to continue the operation 8473 for the specific Initiator Task Tag. The initiator MUST ignore the 8474 Target Transfer Tag in the Text Response when the F bit is set to 8475 1. 8477 This mechanism allows the initiator and target to transfer a large 8478 amount of textual data over a sequence of text-command/text- 8479 response exchanges, or to perform extended negotiation sequences. 8481 If the Target Transfer Tag is not 0xffffffff, the LUN field MUST 8482 be sent by the target in the Text Response. 8484 A target MAY reset its internal negotiation state if an exchange 8485 is stalled by the initiator for a long time or if it is running 8486 out of resources. 8488 Long text responses are handled as in the following example: 8490 I->T Text SendTargets=All (F=1,TTT=0xffffffff) 8492 T->I Text (F=0,TTT=0x12345678) 8494 I->T Text (F=1, TTT=0x12345678) 8496 T->I Text (F=0, TTT=0x12345678) 8498 I->T Text (F=1, TTT=0x12345678) 8500 ... 8502 T->I Text (F=1, TTT=0xffffffff) 8504 11.10.5. Text 8506 The data lengths of a text request MUST NOT exceed the iSCSI 8507 target MaxRecvDataSegmentLength (a per connection and per 8508 direction negotiated parameter). The text format is specified in 8509 Section 6.2. 8511 Section 12 and Section 13 list some basic Text key=value pairs, 8512 some of which can be used in Login Request/Response and some in 8513 Text Request/Response. 8515 A key=value pair can span Text request or response boundaries. A 8516 key=value pair can start in one PDU and continue on the next. In 8518 other words the end of a PDU does not necessarily signal the end 8519 of a key=value pair. 8521 The target responds by sending its response back to the initiator. 8522 The response text format is similar to the request text format. 8523 The text response MAY refer to key=value pairs presented in an 8524 earlier text request and the text in the request may refer to 8525 earlier responses. 8527 Section 6.2 details the rules for the Text Requests and Responses. 8529 Text operations are usually meant for parameter 8530 setting/negotiations, but can also be used to perform some long 8531 lasting operations. 8533 Text operations that take a long time should be placed in their 8534 own Text request. 8536 11.11. Text Response 8538 The Text Response PDU contains the target's responses to the 8539 initiator's Text request. The format of the Text field matches 8540 that of the Text request. 8542 Byte/ 0 | 1 | 2 | 3 | 8543 / | | | | 8544 |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| 8545 +---------------+---------------+---------------+--------------+ 8546 0|.|.| 0x24 |F|C| Reserved | 8547 +---------------+---------------+---------------+--------------+ 8548 4|TotalAHSLength | DataSegmentLength | 8549 +---------------+---------------+---------------+--------------+ 8550 8| LUN or Reserved | 8551 + + 8552 12| | 8553 +---------------+---------------+---------------+--------------+ 8554 16| Initiator Task Tag | 8555 +---------------+---------------+---------------+--------------+ 8556 20| Target Transfer Tag or 0xffffffff | 8557 +---------------+---------------+---------------+--------------+ 8558 24| StatSN | 8559 +---------------+---------------+---------------+--------------+ 8560 28| ExpCmdSN | 8561 +---------------+---------------+---------------+--------------+ 8562 32| MaxCmdSN | 8563 +---------------+---------------+---------------+--------------+ 8564 36/ Reserved / 8565 +/ / 8566 +---------------+---------------+---------------+--------------+ 8567 48| Header-Digest (Optional) | 8568 +---------------+---------------+---------------+--------------+ 8569 / DataSegment (Text) / 8570 +/ / 8571 +---------------+---------------+---------------+--------------+ 8572 | Data-Digest (Optional) | 8573 +---------------+---------------+---------------+--------------+ 8575 11.11.1. F (Final) Bit 8577 When set to 1, in response to a Text Request with the Final bit 8578 set to 1, the F bit indicates that the target has finished the 8579 whole operation. Otherwise, if set to 0 in response to a Text 8580 Request with the Final Bit set to 1, it indicates that the target 8581 has more work to do (invites a follow-on text request). A Text 8582 Response with the F bit set to 1 in response to a Text Request 8583 with the F bit set to 0 is a protocol error. 8585 A Text Response with the F bit set to 1 MUST NOT contain key=value 8586 pairs that may require additional answers from the initiator. 8588 A Text Response with the F bit set to 1 MUST have a Target 8589 Transfer Tag field set to the reserved value of 0xffffffff. 8591 A Text Response with the F bit set to 0 MUST have a Target 8592 Transfer Tag field set to a value other than the reserved 8593 0xffffffff. 8595 11.11.2. C (Continue) Bit 8597 When set to 1, indicates that the text (set of key=value pairs) in 8598 this Text Response is not complete (it will be continued on 8599 subsequent Text Responses); otherwise, it indicates that this Text 8600 Response ends a set of key=value pairs. A Text Response with the C 8601 bit set to 1 MUST have the F bit set to 0. 8603 11.11.3. Initiator Task Tag 8605 The Initiator Task Tag matches the tag used in the initial Text 8606 Request. 8608 11.11.4. Target Transfer Tag 8610 When a target has more work to do (e.g., cannot transfer all the 8611 remaining text data in a single Text Response or has to continue 8612 the negotiation) and has enough resources to proceed, it MUST set 8613 the Target Transfer Tag to a value other than the reserved value 8614 of 0xffffffff. Otherwise, the Target Transfer Tag MUST be set to 8615 0xffffffff. 8617 When the Target Transfer Tag is not 0xffffffff, the LUN field may 8618 be significant. 8620 The initiator MUST copy the Target Transfer Tag and LUN in its 8621 next request to indicate that it wants the rest of the data. 8623 When the target receives a Text Request with the Target Transfer 8624 Tag set to the reserved value of 0xffffffff, it resets its 8625 internal information (resets state) associated with the given 8626 Initiator Task Tag (restarts the negotiation). 8628 When a target cannot finish the operation in a single Text 8629 Response, and does not have enough resources to continue, it 8630 rejects the Text Request with the appropriate Reject code. 8632 A target may reset its internal state associated with an Initiator 8633 Task Tag (the current negotiation state), state expressed through 8634 the Target Transfer Tag if the initiator fails to continue the 8635 exchange for some time. The target may reject subsequent Text 8636 Requests with the Target Transfer Tag set to the "stale" value. 8638 11.11.5. StatSN 8640 The target StatSN variable is advanced by each Text Response sent. 8642 11.11.6. Text Response Data 8644 The data lengths of a text response MUST NOT exceed the iSCSI 8645 initiator MaxRecvDataSegmentLength (a per connection and per 8646 direction negotiated parameter). 8648 The text in the Text Response Data is governed by the same rules 8649 as the text in the Text Request Data (see Section 11.11.2). 8651 Although the initiator is the requesting party and controls the 8652 request-response initiation and termination, the target can offer 8653 key=value pairs of its own as part of a sequence and not only in 8654 response to the initiator. 8656 11.12. Login Request 8658 After establishing a TCP connection between an initiator and a 8659 target, the initiator MUST start a Login Phase to gain further 8660 access to the target's resources. 8662 The Login Phase (see Section 6.3) consists of a sequence of Login 8663 requests and responses that carry the same Initiator Task Tag. 8665 Login requests are always considered as immediate. 8667 Byte/ 0 | 1 | 2 | 3 | 8668 / | | | | 8669 |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| 8670 +---------------+---------------+---------------+--------------+ 8671 0|.|1| 0x03 |T|C|.|.|CSG|NSG| Version-max | Version-min | 8672 +---------------+---------------+---------------+--------------+ 8673 4|TotalAHSLength | DataSegmentLength | 8674 +---------------+---------------+---------------+--------------+ 8675 8| ISID | 8676 + +---------------+--------------+ 8677 12| | TSIH | 8678 +---------------+---------------+---------------+--------------+ 8679 16| Initiator Task Tag | 8680 +---------------+---------------+---------------+--------------+ 8681 20| CID | Reserved | 8682 +---------------+---------------+---------------+--------------+ 8683 24| CmdSN | 8684 +---------------+---------------+---------------+--------------+ 8685 28| ExpStatSN or Reserved | 8686 +---------------+---------------+---------------+--------------+ 8687 32| Reserved | 8688 +---------------+---------------+---------------+--------------+ 8689 36| Reserved | 8690 +---------------+---------------+---------------+--------------+ 8691 40/ Reserved / 8692 +/ / 8693 +---------------+---------------+---------------+--------------+ 8694 48/ DataSegment - Login Parameters in Text request Format / 8695 +/ / 8696 +---------------+---------------+---------------+--------------+ 8698 11.12.1. T (Transit) Bit 8700 If set to 1, indicates that the initiator is ready to transit to 8701 the next stage. 8703 If the T bit is set to 1 and NSG is FullFeaturePhase, then this 8704 also indicates that the initiator is ready for the Final Login 8705 Response (see Section 6.3). 8707 11.12.2. C (Continue) Bit 8709 When set to 1, this bit indicates that the text (set of key=value 8710 pairs) in this Login Request is not complete (it will be continued 8711 on subsequent Login Requests); otherwise, it indicates that this 8712 Login Request ends a set of key=value pairs. A Login Request with 8713 the C bit set to 1 MUST have the T bit set to 0. 8715 11.12.3. CSG and NSG 8717 Through these fields, Current Stage (CSG) and Next Stage (NSG), 8718 the Login negotiation requests and responses are associated with a 8719 specific stage in the session (SecurityNegotiation, 8720 LoginOperationalNegotiation, FullFeaturePhase) and may indicate 8721 the next stage to which they want to move (see Section 6.3). The 8722 next stage value is only valid when the T bit is 1; otherwise, it 8723 is reserved. 8725 The stage codes are: 8727 - 0 - SecurityNegotiation 8729 - 1 - LoginOperationalNegotiation 8731 - 3 - FullFeaturePhase 8733 All other codes are reserved. 8735 11.12.4. Version 8737 The version number of the current draft is 0x00. As such, all 8738 devices MUST carry version 0x00 for both Version-min and Version- 8739 max. 8741 11.12.4.1. Version-max 8743 Maximum Version number supported. 8745 All Login requests within the Login Phase MUST carry the same 8746 Version-max. 8748 The target MUST use the value presented with the first login 8749 request. 8751 11.12.4.2. Version-min 8753 All Login requests within the Login Phase MUST carry the same 8754 Version-min. The target MUST use the value presented with the 8755 first login request. 8757 11.12.5. ISID 8759 This is an initiator-defined component of the session identifier 8760 and is structured as follows (see Section 10.1.1 for details): 8762 Byte/ 0 | 1 | 2 | 3 | 8763 / | | | | 8764 |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| 8765 +---------------+---------------+---------------+--------------+ 8766 8| T | A | B | C | 8767 +---------------+---------------+---------------+--------------+ 8768 12| D | 8769 +---------------+---------------+ 8771 The T field identifies the format and usage of A, B, C, and D as 8772 indicated below: 8774 T 8776 00b OUI-Format 8778 A&B are a 22 bit OUI 8780 (the I/G & U/L bits are omitted) 8782 C&D 24 bit qualifier 8784 01b EN - Format (IANA Enterprise Number) 8786 A - Reserved 8788 B&C EN (IANA Enterprise Number) 8790 D - Qualifier 8792 10b "Random" 8794 A - Reserved 8796 B&C Random 8798 D - Qualifier 8800 11b A,B,C&D Reserved 8802 For the T field values 00b and 01b, a combination of A and B (for 8803 00b) or B and C (for 01b) identifies the vendor or organization 8804 whose component (software or hardware) generates this ISID. A 8805 vendor or organization with one or more OUIs, or one or more 8806 Enterprise Numbers, MUST use at least one of these numbers and 8807 select the appropriate value for the T field when its components 8808 generate ISIDs. An OUI or EN MUST be set in the corresponding 8809 fields in network byte order (byte big-endian). 8811 If the T field is 10b, B and C are set to a random 24-bit unsigned 8812 integer value in network byte order (byte big-endian). See 8813 [RFC3721] for how this affects the principle of "conservative 8814 reuse". 8816 The Qualifier field is a 16 or 24-bit unsigned integer value that 8817 provides a range of possible values for the ISID within the 8818 selected namespace. It may be set to any value within the 8819 constraints specified in the iSCSI protocol (see Section 4.4.3 and 8820 Section 10.1.1). 8822 The T field value of 11b is reserved. 8824 If the ISID is derived from something assigned to a hardware 8825 adapter or interface by a vendor, as a preset default value, it 8826 MUST be configurable to a value assigned according to the SCSI 8827 port behavior desired by the system in which it is installed (see 8828 Section 10.1.1 and Section 10.1.2). The resultant ISID MUST also 8829 be persistent over power cycles, reboot, card swap, etc. 8831 11.12.6. TSIH 8833 TSIH must be set in the first Login Request. The reserved value 0 8834 MUST be used on the first connection for a new session. Otherwise, 8835 the TSIH sent by the target at the conclusion of the successful 8836 login of the first connection for this session MUST be used. The 8837 TSIH identifies to the target the associated existing session for 8838 this new connection. 8840 All Login requests within a Login Phase MUST carry the same TSIH. 8842 The target MUST check the value presented with the first login 8843 request and act as specified in Section 5.3.1. 8845 11.12.7. Connection ID - CID 8847 A unique ID for this connection within the session. 8849 All Login requests within the Login Phase MUST carry the same CID. 8851 The target MUST use the value presented with the first login 8852 request. 8854 A Login request with a non-zero TSIH and a CID equal to that of an 8855 existing connection implies a logout of the connection followed by 8856 a Login (see Section 6.3.4). For the details of the implicit 8857 Logout Request, see Section 11.14. 8859 11.12.8. CmdSN 8861 CmdSN is either the initial command sequence number of a session 8862 (for the first Login request of a session - the "leading" login), 8863 or the command sequence number in the command stream if the login 8864 is for a new connection in an existing session. 8866 Examples: 8868 - Login on a leading connection - if the leading login carries 8869 the CmdSN 123, all other login requests in the same login 8870 phase carry the CmdSN 123 and the first non-immediate 8871 command in FullFeaturePhase also carries the CmdSN 123. 8873 - Login on other than a leading connection - if the current 8874 CmdSN at the time the first login on the connection is 8875 issued is 500, then that PDU carries CmdSN=500. Subsequent 8876 login requests that are needed to complete this login phase 8877 may carry a CmdSN higher than 500 if non-immediate requests 8878 that were issued on other connections in the same session 8879 advance CmdSN. 8881 If the login request is a leading login request, the target MUST 8882 use the value presented in CmdSN as the target value for ExpCmdSN. 8884 11.12.9. ExpStatSN 8886 For the first Login Request on a connection this is ExpStatSN for 8887 the old connection and this field is only valid if the Login 8888 request restarts a connection (see Section 6.3.4). 8890 For subsequent Login Requests it is used to acknowledge the Login 8891 Responses with their increasing StatSN values. 8893 11.12.10. Login Parameters 8895 The initiator MUST provide some basic parameters in order to 8896 enable the target to determine if the initiator may use the 8897 target's resources and the initial text parameters for the 8898 security exchange. 8900 All the rules specified in Section 11.10.5 for text requests also 8901 hold for login requests. Keys and their explanations are listed 8902 in Section 12 (security negotiation keys) and Section 13 8903 (operational parameter negotiation keys). All keys in Section 13, 8904 except for the X extension formats, MUST be supported by iSCSI 8905 initiators and targets. Keys in Section 12 only need to be 8906 supported when the function to which they refer is mandatory to 8907 implement. 8909 11.13. Login Response 8911 The Login Response indicates the progress and/or end of the Login 8912 Phase. 8914 Byte/ 0 | 1 | 2 | 3 | 8915 / | | | | 8916 |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| 8917 +---------------+---------------+---------------+--------------+ 8918 0|.|.| 0x23 |T|C|.|.|CSG|NSG| Version-max |Version-active| 8919 +---------------+---------------+---------------+--------------+ 8920 4|TotalAHSLength | DataSegmentLength | 8921 +---------------+---------------+---------------+--------------+ 8922 8| ISID | 8923 + +---------------+--------------+ 8924 12| | TSIH | 8925 +---------------+---------------+---------------+--------------+ 8926 16| Initiator Task Tag | 8927 +---------------+---------------+---------------+--------------+ 8928 20| Reserved | 8929 +---------------+---------------+---------------+--------------+ 8930 24| StatSN | 8931 +---------------+---------------+---------------+--------------+ 8932 28| ExpCmdSN | 8933 +---------------+---------------+---------------+--------------+ 8934 32| MaxCmdSN | 8935 +---------------+---------------+---------------+--------------+ 8936 36| Status-Class | Status-Detail | Reserved | 8937 +---------------+---------------+---------------+--------------+ 8938 40/ Reserved / 8939 +/ / 8940 +---------------+---------------+---------------+--------------+ 8941 48/ DataSegment - Login Parameters in Text request Format / 8942 +/ / 8943 +---------------+---------------+---------------+--------------+ 8945 11.13.1. Version-max 8947 This is the highest version number supported by the target. 8949 All Login responses within the Login Phase MUST carry the same 8950 Version-max. 8952 The initiator MUST use the value presented as a response to the 8953 first login request. 8955 11.13.2. Version-active 8957 Indicates the highest version supported by the target and 8958 initiator. If the target does not support a version within the 8959 range specified by the initiator, the target rejects the login and 8960 this field indicates the lowest version supported by the target. 8962 All Login responses within the Login Phase MUST carry the same 8963 Version-active. 8965 The initiator MUST use the value presented as a response to the 8966 first login request. 8968 11.13.3. TSIH 8970 The TSIH is the target assigned session identifying handle. Its 8971 internal format and content are not defined by this protocol 8972 except for the value 0 that is reserved. With the exception of the 8973 Login Final-Response in a new session, this field should be set to 8974 the TSIH provided by the initiator in the Login Request. For a 8975 new session, the target MUST generate a non-zero TSIH and ONLY 8976 return it in the Login Final-Response (see Section 6.3). 8978 11.13.4. StatSN 8980 For the first Login Response (the response to the first Login 8981 Request), this is the starting status Sequence Number for the 8982 connection. The next response of any kind, including the next 8983 login response, if any, in the same Login Phase, will carry this 8984 number + 1. This field is only valid if the Status-Class is 0. 8986 11.13.5. Status-Class and Status-Detail 8988 The Status returned in a Login Response indicates the execution 8989 status of the Login Phase. The status includes: 8991 Status-Class 8993 Status-Detail 8995 0 Status-Class indicates success. 8997 A non-zero Status-Class indicates an exception. In this case, 8998 Status-Class is sufficient for a simple initiator to use when 8999 handling exceptions, without having to look at the Status-Detail. 9000 The Status-Detail allows finer-grained exception handling for more 9001 sophisticated initiators and for better information for logging. 9003 The status classes are as follows: 9005 0 - Success - indicates that the iSCSI target successfully 9006 received, understood, and accepted the request. The 9007 numbering fields (StatSN, ExpCmdSN, MaxCmdSN) are only valid 9008 if Status-Class is 0. 9010 1 - Redirection - indicates that the initiator must take 9011 further action to complete the request. This is usually due 9012 to the target moving to a different address. All of the 9013 redirection status class responses MUST return one or more 9014 text key parameters of the type "TargetAddress", which 9015 indicates the target's new address. A redirection response 9016 MAY be issued by a target prior or after completing a 9017 security negotiation if a security negotiation is required. 9018 A redirection SHOULD be accepted by an initiator even 9019 without having the target complete a security negotiation if 9020 any security negotiation is required, and MUST be accepted 9021 by the initiator after the completion of the security 9022 negotiation if any security negotiation is required. 9024 2 - Initiator Error (not a format error) - indicates that the 9025 initiator most likely caused the error. This MAY be due to a 9026 request for a resource for which the initiator does not have 9027 permission. The request should not be tried again. 9029 3 - Target Error - indicates that the target sees no errors in 9030 the initiator's login request, but is currently incapable of 9031 fulfilling the request. The initiator may re-try the same 9032 login request later. 9034 The table below shows all of the currently allocated status codes. 9035 The codes are in hexadecimal; the first byte is the status class 9036 and the second byte is the status detail. 9038 ----------------------------------------------------------------- 9039 Status | Code | Description 9040 |(hex) | 9041 ----------------------------------------------------------------- 9042 Success | 0000 | Login is proceeding OK (*1). 9043 ----------------------------------------------------------------- 9044 Target moved | 0101 | The requested iSCSI Target Name (ITN) 9045 temporarily | | has temporarily moved 9046 | | to the address provided. 9047 ----------------------------------------------------------------- 9048 Target moved | 0102 | The requested ITN has permanently moved 9049 permanently | | to the address provided. 9050 ----------------------------------------------------------------- 9051 Initiator | 0200 | Miscellaneous iSCSI initiator 9052 error | | errors. 9053 ---------------------------------------------------------------- 9054 Authentication| 0201 | The initiator could not be 9055 failure | | successfully authenticated or target 9056 | | authentication is not supported. 9057 ----------------------------------------------------------------- 9058 Authorization | 0202 | The initiator is not allowed access 9059 failure | | to the given target. 9060 ----------------------------------------------------------------- 9061 Not found | 0203 | The requested ITN does not 9062 | | exist at this address. 9063 ----------------------------------------------------------------- 9064 Target removed| 0204 | The requested ITN has been removed and 9065 | | no forwarding address is provided. 9066 ----------------------------------------------------------------- 9067 Unsupported | 0205 | The requested iSCSI version range is 9068 version | | not supported by the target. 9069 ----------------------------------------------------------------- 9070 Too many | 0206 | Too many connections on this SSID. 9071 connections | | 9072 ----------------------------------------------------------------- 9073 Missing | 0207 | Missing parameters (e.g., iSCSI 9074 parameter | | Initiator and/or Target Name). 9075 ----------------------------------------------------------------- 9076 Can't include | 0208 | Target does not support session 9077 in session | | spanning to this connection (address). 9078 ----------------------------------------------------------------- 9079 Session type | 0209 | Target does not support this type of 9080 not supported | | of session or not from this Initiator. 9081 ----------------------------------------------------------------- 9082 Session does | 020a | Attempt to add a connection 9083 not exist | | to a non-existent session. 9084 ----------------------------------------------------------------- 9085 Invalid during| 020b | Invalid Request type during Login. 9086 login | | 9087 ----------------------------------------------------------------- 9088 Target error | 0300 | Target hardware or software error. 9089 ----------------------------------------------------------------- 9090 Service | 0301 | The iSCSI service or target is not 9091 unavailable | | currently operational. 9092 ----------------------------------------------------------------- 9093 Out of | 0302 | The target has insufficient session, 9094 resources | | connection, or other resources. 9095 ----------------------------------------------------------------- 9097 (*1)If the response T bit is 1 in both the request and the 9098 matching response, and the NSG is FullFeaturePhase in both the 9099 request and the matching response, the Login Phase is finished and 9100 the initiator may proceed to issue SCSI commands. 9102 If the Status Class is not 0, the initiator and target MUST close 9103 the TCP connection. 9105 If the target wishes to reject the login request for more than one 9106 reason, it should return the primary reason for the rejection. 9108 11.13.6. T (Transit) bit 9110 The T bit is set to 1 as an indicator of the end of the stage. If 9111 the T bit is set to 1 and NSG is FullFeaturePhase, then this is 9112 also the Final Login Response (see Section 6.3). A T bit of 0 9113 indicates a "partial" response, which means "more negotiation 9114 needed". 9116 A login response with a T bit set to 1 MUST NOT contain key=value 9117 pairs that may require additional answers from the initiator 9118 within the same stage. 9120 If the status class is 0, the T bit MUST NOT be set to 1 if the T 9121 bit in the request was set to 0. 9123 11.13.7. C (Continue) Bit 9125 When set to 1, indicates that the text (set of key=value pairs) in 9126 this Login Response is not complete (it will be continued on 9127 subsequent Login Responses); otherwise, it indicates that this 9128 Login Response ends a set of key=value pairs. A Login Response 9129 with the C bit set to 1 MUST have the T bit set to 0. 9131 11.13.8. Login Parameters 9133 The target MUST provide some basic parameters in order to enable 9134 the initiator to determine if it is connected to the correct port 9135 and the initial text parameters for the security exchange. 9137 All the rules specified in Section 11.11.6 for text responses also 9138 hold for login responses. Keys and their explanations are listed 9139 in Section 12(security negotiation keys) and Section 13 9140 (operational parameter negotiation keys). All keys in Section 13, 9141 except for the X extension formats, MUST be supported by iSCSI 9142 initiators and targets. Keys in Section 12, only need to be 9143 supported when the function to which they refer is mandatory to 9144 implement. 9146 11.14. Logout Request 9148 The Logout request is used to perform a controlled closing of a 9149 connection. 9151 An initiator MAY use a logout request to remove a connection from 9152 a session or to close an entire session. 9154 After sending the Logout request PDU, an initiator MUST NOT send 9155 any new iSCSI requests on the closing connection. If the Logout 9156 request is intended to close the session, new iSCSI requests MUST 9157 NOT be sent on any of the connections participating in the 9158 session. 9160 When receiving a Logout request with the reason code of "close the 9161 connection" or "close the session", the target MUST terminate all 9162 pending commands, whether acknowledged via ExpCmdSN or not, on 9163 that connection or session respectively. 9165 When receiving a Logout request with the reason code "remove 9166 connection for recovery", the target MUST discard all requests not 9167 yet acknowledged via ExpCmdSN that were issued on the specified 9168 connection, and suspend all data/status/R2T transfers on behalf of 9169 pending commands on the specified connection. 9171 The target then issues the Logout response and half-closes the TCP 9172 connection (sends FIN). After receiving the Logout response and 9173 attempting to receive the FIN (if still possible), the initiator 9174 MUST completely close the logging-out connection. For the 9175 terminated commands, no additional responses should be expected. 9177 A Logout for a CID may be performed on a different transport 9178 connection when the TCP connection for the CID has already been 9179 terminated. In such a case, only a logical "closing" of the iSCSI 9180 connection for the CID is implied with a Logout. 9182 All commands that were not terminated or not completed (with 9183 status) and acknowledged when the connection is closed completely 9184 can be reassigned to a new connection if the target supports 9185 connection recovery. 9187 If an initiator intends to start recovery for a failing 9188 connection, it MUST use the Logout request to "clean-up" the 9189 target end of a failing connection and enable recovery to start, 9190 or the Login request with a non-zero TSIH and the same CID on a 9191 new connection for the same effect. In sessions with a single 9192 connection, the connection can be closed and then a new connection 9193 reopened. A connection reinstatement login can be used for 9194 recovery (see Section 6.3.4). 9196 A successful completion of a logout request with the reason code 9197 of "close the connection" or "remove the connection for recovery" 9198 results at the target in the discarding of unacknowledged commands 9199 received on the connection being logged out. These are commands 9200 that have arrived on the connection being logged out, but have not 9201 been delivered to SCSI because one or more commands with a smaller 9202 CmdSN has not been received by iSCSI. See Section 4.2.2.1. The 9203 resulting holes in the command sequence numbers will have to be 9204 handled by appropriate recovery (see Section 7) unless the session 9205 is also closed. 9207 The entire logout discussion in this Section is also applicable 9208 for an implicit Logout realized by way of a connection 9209 reinstatement or session reinstatement. When a Login Request 9210 performs an implicit Logout, the implicit Logout is performed as 9211 if having the reason codes specified below: 9213 Reason code Type of implicit Logout 9215 ------------------------------------------- 9217 0 session reinstatement 9219 1 connection reinstatement when the operational 9220 ErrorRecoveryLevel < 2 9222 2 connection reinstatement when the operational 9223 ErrorRecoveryLevel = 2 9225 Byte/ 0 | 1 | 2 | 3 | 9226 / | | | | 9227 |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| 9228 +---------------+---------------+---------------+--------------+ 9229 0|.|I| 0x06 |1| Reason Code | Reserved | 9230 +---------------+---------------+---------------+--------------+ 9231 4|TotalAHSLength | DataSegmentLength | 9232 +--------------------------------------------------------------+ 9233 8/ Reserved / 9234 +/ / 9235 +---------------+---------------+---------------+--------------+ 9236 16| Initiator Task Tag | 9237 +---------------+---------------+---------------+--------------+ 9238 20| CID or Reserved | Reserved | 9239 +---------------+---------------+---------------+--------------+ 9240 24| CmdSN | 9241 +---------------+---------------+---------------+--------------+ 9242 28| ExpStatSN | 9243 +---------------+---------------+---------------+--------------+ 9244 32/ Reserved / 9245 +/ / 9246 +---------------+---------------+---------------+--------------+ 9247 48| Header-Digest (Optional) | 9248 +---------------+---------------+---------------+--------------+ 9250 11.14.1. Reason Code 9252 Reason Code indicates the reason for Logout as follows: 9254 0 - close the session. All commands associated with the 9255 session (if any) are terminated. 9257 1 - close the connection. All commands associated with 9258 connection (if any) are terminated. 9260 2 - remove the connection for recovery. Connection is closed 9261 and all commands associated with it, if any, are to be 9262 prepared for a new allegiance. 9264 All other values are reserved. 9266 11.14.2. TotalAHSLength and DataSegmentLength 9268 For this PDU TotalAHSLength and DataSegmentLength MUST be 0. 9270 11.14.3. CID 9272 This is the connection ID of the connection to be closed 9273 (including closing the TCP stream). This field is only valid if 9274 the reason code is not "close the session". 9276 11.14.4. ExpStatSN 9278 This is the last ExpStatSN value for the connection to be closed. 9280 11.14.5. Implicit termination of tasks 9282 A target implicitly terminates the active tasks due to the iSCSI 9283 protocol in the following cases: 9285 a) When a connection is implicitly or explicitly logged out 9286 with the reason code of "Close the connection" and there 9287 are active tasks allegiant to that connection. 9289 b) When a connection fails and eventually the connection state 9290 times out (state transition M1 in Section 8.2.2) and there 9291 are active tasks allegiant to that connection. 9293 c) When a successful recovery Logout is performed while there 9294 are active tasks allegiant to that connection, and those 9295 tasks eventually time out after the Time2Wait and 9296 Time2Retain periods without allegiance reassignment. 9298 d) When a connection is implicitly or explicitly logged out 9299 with the reason code of "Close the session" and there are 9300 active tasks in that session. 9302 If the tasks terminated in any of the above cases are SCSI tasks, 9303 they must be internally terminated as if with CHECK CONDITION 9304 status. This status is only meaningful for appropriately handling 9306 the internal SCSI state and SCSI side effects with respect to 9307 ordering because this status is never communicated back as a 9308 terminating status to the initiator. However additional actions 9309 may have to be taken at SCSI level depending on the SCSI context 9310 as defined by the SCSI standards (e.g., queued commands and ACA, 9311 UA for the next command on the I_T nexus in cases a), b), and c), 9312 after the tasks are terminated, the target MUST report a Unit 9313 Attention condition on the next command processed on any 9314 connection for each affected I_T_L nexus with the status of CHECK 9315 CONDITION, and the ASC/ASCQ value of 47h/7Fh - "SOME COMMANDS 9316 CLEARED BY ISCSI PROTOCOL EVENT" - etc. - see [SPC3]). 9318 11.15. Logout Response 9320 The logout response is used by the target to indicate if the 9321 cleanup operation for the connection(s) has completed. 9323 After Logout, the TCP connection referred by the CID MUST be 9324 closed at both ends (or all connections must be closed if the 9325 logout reason was session close). 9327 Byte/ 0 | 1 | 2 | 3 | 9328 / | | | | 9329 |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| 9330 +---------------+---------------+---------------+--------------+ 9331 0|.|.| 0x26 |1| Reserved | Response | Reserved | 9332 +---------------+---------------+---------------+--------------+ 9333 4|TotalAHSLength | DataSegmentLength | 9334 +--------------------------------------------------------------+ 9335 8/ Reserved / 9336 +/ / 9337 +---------------+---------------+---------------+--------------+ 9338 16| Initiator Task Tag | 9339 +---------------+---------------+---------------+--------------+ 9340 20| Reserved | 9341 +---------------+---------------+---------------+--------------+ 9342 24| StatSN | 9343 +---------------+---------------+---------------+--------------+ 9344 28| ExpCmdSN | 9345 +---------------+---------------+---------------+--------------+ 9346 32| MaxCmdSN | 9347 +---------------+---------------+---------------+--------------+ 9348 36| Reserved | 9349 +--------------------------------------------------------------+ 9350 40| Time2Wait | Time2Retain | 9351 +---------------+---------------+---------------+--------------+ 9352 44| Reserved | 9353 +---------------+---------------+---------------+--------------+ 9354 48| Header-Digest (Optional) | 9355 +---------------+---------------+---------------+--------------+ 9357 11.15.1. Response 9359 Logout response: 9361 0 - connection or session closed successfully. 9363 1 - CID not found. 9365 2 - connection recovery is not supported. If Logout reason 9366 code was recovery and target does not support it as 9367 indicated by the ErrorRecoveryLevel. 9368 3 - cleanup failed for various reasons. 9370 11.15.2. TotalAHSLength and DataSegmentLength 9372 For this PDU TotalAHSLength and DataSegmentLength MUST be 0. 9374 11.15.3. Time2Wait 9376 If the Logout response code is 0 and if the operational 9377 ErrorRecoveryLevel is 2, this is the minimum amount of time, in 9378 seconds, to wait before attempting task reassignment. If the 9379 Logout response code is 0 and if the operational 9380 ErrorRecoveryLevel is less than 2, this field is to be ignored. 9382 This field is invalid if the Logout response code is 1. 9384 If the Logout response code is 2 or 3, this field specifies the 9385 minimum time to wait before attempting a new implicit or explicit 9386 logout. 9388 If Time2Wait is 0, the reassignment or a new Logout may be 9389 attempted immediately. 9391 11.15.4. Time2Retain 9393 If the Logout response code is 0 and if the operational 9394 ErrorRecoveryLevel is 2, this is the maximum amount of time, in 9395 seconds, after the initial wait (Time2Wait), the target waits for 9396 the allegiance reassignment for any active task after which the 9397 task state is discarded. If the Logout response code is 0 and if 9398 the operational ErrorRecoveryLevel is less than 2, this field is 9399 to be ignored. 9401 This field is invalid if the Logout response code is 1. 9403 If the Logout response code is 2 or 3, this field specifies the 9404 maximum amount of time, in seconds, after the initial wait 9405 (Time2Wait), the target waits for a new implicit or explicit 9406 logout. 9408 If it is the last connection of a session, the whole session state 9409 is discarded after Time2Retain. 9411 If Time2Retain is 0, the target has already discarded the 9412 connection (and possibly the session) state along with the task 9413 states. No reassignment or Logout is required in this case. 9415 11.16. SNACK Request 9417 Byte/ 0 | 1 | 2 | 3 | 9418 / | | | | 9419 |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| 9420 +---------------+---------------+---------------+--------------+ 9421 0|.|.| 0x10 |1|.|.|.| Type | Reserved | 9422 +---------------+---------------+---------------+--------------+ 9423 4|TotalAHSLength | DataSegmentLength | 9424 +---------------+---------------+---------------+--------------+ 9425 8| LUN or Reserved | 9426 + + 9427 12| | 9428 +---------------+---------------+---------------+--------------+ 9429 16| Initiator Task Tag or 0xffffffff | 9430 +---------------+---------------+---------------+--------------+ 9431 20| Target Transfer Tag or SNACK Tag or 0xffffffff | 9432 +---------------+---------------+---------------+--------------+ 9433 24| Reserved | 9434 +---------------+---------------+---------------+--------------+ 9435 28| ExpStatSN | 9436 +---------------+---------------+---------------+--------------+ 9437 32/ Reserved / 9438 +/ / 9439 +---------------+---------------+---------------+--------------+ 9440 40| BegRun | 9441 +--------------------------------------------------------------+ 9442 44| RunLength | 9443 +--------------------------------------------------------------+ 9444 48| Header-Digest (Optional) | 9445 +---------------+---------------+---------------+--------------+ 9447 If the implementation supports ErrorRecoveryLevel greater than 9448 zero, it MUST support all SNACK types. 9450 The SNACK is used by the initiator to request the retransmission 9451 of numbered-responses, data, or R2T PDUs from the target. The 9452 SNACK request indicates the numbered-responses or data "runs" 9453 whose retransmission is requested by the target, where the run 9454 starts with the first StatSN, DataSN, or R2TSN whose 9455 retransmission is requested and indicates the number of Status, 9456 Data, or R2T PDUs requested including the first. 0 has special 9457 meaning when used as a starting number and length: 9459 - When used in RunLength, it means all PDUs starting with the 9460 initial. 9462 - When used in both BegRun and RunLength, it means all 9463 unacknowledged PDUs. 9465 The numbered-response(s) or R2T(s), requested by a SNACK, MUST be 9466 delivered as exact replicas of the ones that the target 9467 transmitted originally except for the fields ExpCmdSN, MaxCmdSN, 9468 and ExpDataSN, which MUST carry the current values. 9469 R2T(s)requested by SNACK MUST also carry the current value of 9470 StatSN. 9472 The numbered Data-In PDUs, requested by a Data SNACK MUST be 9473 delivered as exact replicas of the ones that the target 9474 transmitted originally except for the fields ExpCmdSN and 9475 MaxCmdSN, which MUST carry the current values and except for 9476 resegmentation (see Section 11.16.3). 9478 Any SNACK that requests a numbered-response, Data, or R2T that was 9479 not sent by the target or was already acknowledged by the 9480 initiator, MUST be rejected with a reason code of "Protocol 9481 error". 9483 11.16.1. Type 9485 This field encodes the SNACK function as follows: 9487 0-Data/R2T SNACK - requesting retransmission of one or more 9488 Data-In or R2T PDUs. 9490 1-Status SNACK - requesting retransmission of one or more 9491 numbered responses. 9493 2-DataACK - positively acknowledges Data-In PDUs. 9495 3-R-Data SNACK - requesting retransmission of Data-In PDUs 9496 with possible resegmentation and status tagging. 9498 All other values are reserved. 9500 Data/R2T SNACK, Status SNACK, or R-Data SNACK for a command MUST 9501 precede status acknowledgement for the given command. 9503 11.16.2. Data Acknowledgement 9505 If an initiator operates at ErrorRecoveryLevel 1 or higher, it 9506 MUST issue a SNACK of type DataACK after receiving a Data-In PDU 9507 with the A bit set to 1. However, if the initiator has detected 9508 holes in the input sequence, it MUST postpone issuing the SNACK of 9509 type DataACK until the holes are filled. An initiator MAY ignore 9510 the A bit if it deems that the bit is being set aggressively by 9511 the target (i.e., before the MaxBurstLength limit is 9512 reached). 9514 The DataACK is used to free resources at the target and not to 9515 request or imply data retransmission. 9517 An initiator MUST NOT request retransmission for any data it had 9518 already acknowledged. 9520 11.16.3. Resegmentation 9522 If the initiator MaxRecvDataSegmentLength changed between the 9523 original transmission and the time the initiator requests 9524 retransmission, the initiator MUST issue a R-Data SNACK (see 9525 Section 11.16.1). With R-Data SNACK, the initiator indicates that 9526 it discards all the unacknowledged data and expects the target to 9527 resend it. It also expects resegmentation. In this case, the 9528 retransmitted Data-In PDUs MAY be different from the ones 9529 originally sent in order to reflect changes in 9530 MaxRecvDataSegmentLength. Their DataSN starts with the BegRun of 9531 the last DataACK received by the target if any was received; 9532 otherwise it starts with 0 and is increased by 1 for each resent 9533 Data-In PDU. 9535 A target that has received a R-Data SNACK MUST return a SCSI 9536 Response that contains a copy of the SNACK Tag field from the R- 9537 Data SNACK in the SCSI Response SNACK Tag field as its last or 9538 only Response. For example, if it has already sent a response 9539 containing another value in the SNACK Tag field or had the status 9540 included in the last Data-In PDU, it must send a new SCSI Response 9541 PDU. If a target sends more than one SCSI Response PDU due to this 9542 rule, all SCSI responses must carry the same StatSN (see Section 9543 11.4.4). If an initiator attempts to recover a lost SCSI Response 9544 (with a Status-SNACK, see Section 11.16.1) when more than one 9545 response has been sent, the target will send the SCSI Response 9546 with the latest content known to the target, including the last 9547 SNACK Tag for the command. 9549 For considerations in allegiance reassignment of a task to a 9550 connection with a different MaxRecvDataSegmentLength, refer to 9551 Section 7.2.2. 9553 11.16.4. Initiator Task Tag 9555 For Status SNACK and DataACK, the Initiator Task Tag MUST be set 9556 to the reserved value 0xffffffff. In all other cases, the 9557 Initiator Task Tag field MUST be set to the Initiator Task Tag of 9558 the referenced command. 9560 11.16.5. Target Transfer Tag or SNACK Tag 9562 For an R-Data SNACK, this field MUST contain a value that is 9563 different from 0 or 0xffffffff and is unique for the task 9564 (identified by the Initiator Task Tag). This value MUST be copied 9565 by the iSCSI target in the last or only SCSI Response PDU it 9566 issues for the command. 9568 For DataACK, the Target Transfer Tag MUST contain a copy of the 9569 Target Transfer Tag and LUN provided with the SCSI Data-In PDU 9570 with the A bit set to 1. 9572 In all other cases, the Target Transfer Tag field MUST be set to 9573 the reserved value of 0xffffffff. 9575 11.16.6. BegRun 9577 The DataSN, R2TSN, or StatSN of the first PDU whose retransmission 9578 is requested (Data/R2T and Status SNACK), or the next expected 9579 DataSN (DataACK SNACK). 9581 BegRun 0 when used in conjunction with RunLength 0 means resend 9582 all unacknowledged Data-In, R2T or Response PDUs. 9584 BegRun MUST be 0 for a R-Data SNACK. 9586 11.16.7. RunLength 9588 The number of PDUs whose retransmission is requested. 9590 RunLength 0 signals that all Data-In, R2T, or Response PDUs 9591 carrying the numbers equal to or greater than BegRun have to be 9592 resent. 9594 The RunLength MUST also be 0 for a DataACK SNACK in addition to R- 9595 Data SNACK. 9597 11.17. Reject 9599 Byte/ 0 | 1 | 2 | 3 | 9600 / | | | | 9601 |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| 9602 +---------------+---------------+---------------+--------------+ 9603 0|.|.| 0x3f |1| Reserved | Reason | Reserved | 9604 +---------------+---------------+---------------+--------------+ 9605 4|TotalAHSLength | DataSegmentLength | 9606 +---------------+---------------+---------------+--------------+ 9607 8/ Reserved / 9608 +/ / 9609 +---------------+---------------+---------------+--------------+ 9610 16| 0xffffffff | 9611 +---------------+---------------+---------------+--------------+ 9612 20| Reserved | 9613 +---------------+---------------+---------------+--------------+ 9614 24| StatSN | 9615 +---------------+---------------+---------------+--------------+ 9616 28| ExpCmdSN | 9617 +---------------+---------------+---------------+--------------+ 9618 32| MaxCmdSN | 9619 +---------------+---------------+---------------+--------------+ 9620 36| DataSN/R2TSN or Reserved | 9621 +---------------+---------------+---------------+--------------+ 9622 40| Reserved | 9623 +---------------+---------------+---------------+--------------+ 9624 44| Reserved | 9625 +---------------+---------------+---------------+--------------+ 9626 48| Header-Digest (Optional) | 9627 +---------------+---------------+---------------+--------------+ 9628 xx/ Complete Header of Bad PDU / 9629 +/ / 9630 +---------------+---------------+---------------+--------------+ 9631 yy/Vendor specific data (if any) / 9632 / / 9633 +---------------+---------------+---------------+--------------+ 9634 zz| Data-Digest (Optional) | 9635 +---------------+---------------+---------------+--------------+ 9637 Reject is used to indicate an iSCSI error condition (protocol, 9638 unsupported option, etc.). 9640 11.17.1. Reason 9642 The reject Reason is coded as follows: 9644 +------+----------------------------------------+----------------+ 9645 | Code | Explanation |Can the original| 9646 | (hex)| |PDU be re-sent? | 9647 +------+----------------------------------------+----------------+ 9648 | 0x01 | Reserved | no | 9649 | | | | 9650 | 0x02 | Data (payload) Digest Error | yes (Note 1) | 9651 | | | | 9652 | 0x03 | SNACK Reject | yes | 9653 | | | | 9654 | 0x04 | Protocol Error (e.g., SNACK request for| no | 9655 | | a status that was already acknowledged)| | 9656 | | | | 9657 | 0x05 | Command not supported | no | 9658 | | | | 9659 | 0x06 | Immediate Command Reject - too many | yes | 9660 | | immediate commands | | 9661 | | | | 9662 | 0x07 | Task in progress | no | 9663 | | | | 9664 | 0x08 | Invalid Data ACK | no | 9665 | | | | 9666 | 0x09 | Invalid PDU field | no (Note 2) | 9667 | | | | 9668 | 0x0a | Long Operation Reject - Can't generate | yes | 9669 | | Target Transfer Tag - out of resources | | 9670 | | | | 9671 | 0x0c | Waiting for Logout | no | 9672 +------+----------------------------------------+----------------+ 9674 Note 1: For iSCSI, Data-Out PDU retransmission is only done if the 9675 target requests retransmission with a recovery R2T. However, if 9676 this is the data digest error on immediate data, the initiator may 9677 choose to retransmit the whole PDU including the immediate data. 9679 Note 2: A target should use this reason code for all invalid 9680 values of PDU fields that are meant to describe a task, a 9681 response, or a data transfer. Some examples are invalid TTT/ITT, 9682 buffer offset, LUN qualifying a TTT, and an invalid sequence 9683 number in a SNACK. 9685 Note 3: Reason code 0x0b ("Negotiation reset") defined in 9686 [RFC3720] is deprecated and MUST NOT be used by implementations. 9687 An implementation receiving reason code 0x0b MUST treat it as a 9688 negotiation failure that terminates the Login Phase and the TCP 9689 connection, as specified in Section 7.12. 9691 All other values for Reason are reserved. 9693 In all the cases in which a pre-instantiated SCSI task is 9694 terminated because of the reject, the target MUST issue a proper 9695 SCSI command response with CHECK CONDITION as described in Section 9696 11.4.3. In these cases in which a status for the SCSI task was 9697 already sent before the reject, no additional status is required. 9698 If the error is detected while data from the initiator is still 9699 expected (i.e., the command PDU did not contain all the data and 9700 the target has not received a Data-out PDU with the Final bit set 9701 to 1 for the unsolicited data, if any, and all outstanding R2Ts, 9702 if any), the target MUST wait until it receives the last expected 9703 Data-out PDUs with the F bit set to 1 before sending the Response 9704 PDU. 9706 For additional usage semantics of Reject PDU, see Section 7.3. 9708 11.17.2. DataSN/R2TSN 9710 This field is only valid if the rejected PDU is a Data/R2T SNACK 9711 and the Reject reason code is "Protocol error" (see Section 9712 11.16). The DataSN/R2TSN is the next Data/R2T sequence number 9713 that the target would send for the task, if any. 9715 11.17.3. StatSN, ExpCmdSN and MaxCmdSN 9717 These fields carry their usual values and are not related to the 9718 rejected command. StatSN is advanced after a Reject. 9720 11.17.4. Complete Header of Bad PDU 9722 The target returns the header (not including digest) of the PDU in 9723 error as the data of the response. 9725 11.18. NOP-Out 9727 Byte/ 0 | 1 | 2 | 3 | 9728 / | | | | 9729 |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| 9730 +---------------+---------------+---------------+--------------+ 9731 0|.|I| 0x00 |1| Reserved | 9732 +---------------+---------------+---------------+--------------+ 9733 4|TotalAHSLength | DataSegmentLength | 9734 +---------------+---------------+---------------+--------------+ 9735 8| LUN or Reserved | 9736 + + 9737 12| | 9738 +---------------+---------------+---------------+--------------+ 9739 16| Initiator Task Tag or 0xffffffff | 9740 +---------------+---------------+---------------+--------------+ 9741 20| Target Transfer Tag or 0xffffffff | 9742 +---------------+---------------+---------------+--------------+ 9743 24| CmdSN | 9744 +---------------+---------------+---------------+--------------+ 9745 28| ExpStatSN | 9746 +---------------+---------------+---------------+--------------+ 9747 32/ Reserved / 9748 +/ / 9749 +---------------+---------------+---------------+--------------+ 9750 48| Header-Digest (Optional) | 9751 +---------------+---------------+---------------+--------------+ 9752 / DataSegment - Ping Data (optional) / 9753 +/ / 9754 +---------------+---------------+---------------+--------------+ 9755 | Data-Digest (Optional) | 9756 +---------------+---------------+---------------+--------------+ 9758 A NOP-Out may be used by an initiator as a "ping request" to 9759 verify that a connection/session is still active and all its 9760 components are operational. The NOP-In response is the "ping 9761 echo". 9763 A NOP-Out is also sent by an initiator in response to a NOP-In. 9765 A NOP-Out may also be used to confirm a changed ExpStatSN if 9766 another PDU will not be available for a long time. 9768 Upon receipt of a NOP-In with the Target Transfer Tag set to a 9769 valid value (not the reserved 0xffffffff), the initiator MUST 9770 respond with a NOP-Out. In this case, the NOP-Out Target Transfer 9771 Tag MUST contain a copy of the NOP-In Target Transfer Tag. The 9772 initiator SHOULD NOT send a NOP-Out in response to any other 9773 received NOP-In in order to avoid lengthy sequences of NOP-In and 9774 NOP-Out PDUs sent in response to each other. 9776 11.18.1. Initiator Task Tag 9778 The NOP-Out MUST have the Initiator Task Tag set to a valid value 9779 only if a response in the form of NOP-In is requested (i.e., the 9780 NOP-Out is used as a ping request). Otherwise, the Initiator Task 9781 Tag MUST be set to 0xffffffff. 9783 When a target receives the NOP-Out with a valid Initiator Task 9784 Tag, it MUST respond with a Nop-In Response (see Section 6). 9786 If the Initiator Task Tag contains 0xffffffff, the I bit MUST be 9787 set to 1 and the CmdSN is not advanced after this PDU is sent. 9789 11.18.2. Target Transfer Tag 9791 A target assigned identifier for the operation. 9793 The NOP-Out MUST only have the Target Transfer Tag set if it is 9794 issued in response to a NOP-In with a valid Target Transfer Tag. 9795 In this case, it copies the Target Transfer Tag from the NOP-In 9796 PDU. Otherwise, the Target Transfer Tag MUST be set to 0xffffffff. 9798 When the Target Transfer Tag is set to a value other than 9799 0xffffffff, the LUN field MUST also be copied from the NOP-In. 9801 11.18.3. Ping Data 9803 Ping data is reflected in the NOP-In Response. The length of the 9804 reflected data is limited to MaxRecvDataSegmentLength. The length 9805 of ping data is indicated by the DataSegmentLength. 0 is a valid 9806 value for the DataSegmentLength and indicates the absence of ping 9807 data. 9809 11.19. NOP-In 9811 Byte/ 0 | 1 | 2 | 3 | 9812 / | | | | 9813 |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| 9814 +---------------+---------------+---------------+--------------+ 9815 0|.|.| 0x20 |1| Reserved | 9816 +---------------+---------------+---------------+--------------+ 9817 4|TotalAHSLength | DataSegmentLength | 9818 +---------------+---------------+---------------+--------------+ 9819 8| LUN or Reserved | 9820 + + 9821 12| | 9822 +---------------+---------------+---------------+--------------+ 9823 16| Initiator Task Tag or 0xffffffff | 9824 +---------------+---------------+---------------+--------------+ 9825 20| Target Transfer Tag or 0xffffffff | 9826 +---------------+---------------+---------------+--------------+ 9827 24| StatSN | 9828 +---------------+---------------+---------------+--------------+ 9829 28| ExpCmdSN | 9830 +---------------+---------------+---------------+--------------+ 9831 32| MaxCmdSN | 9832 +---------------+---------------+---------------+--------------+ 9833 36/ Reserved / 9834 +/ / 9835 +---------------+---------------+---------------+--------------+ 9836 48| Header-Digest (Optional) | 9837 +---------------+---------------+---------------+--------------+ 9838 / DataSegment - Return Ping Data / 9839 +/ / 9840 +---------------+---------------+---------------+--------------+ 9841 | Data-Digest (Optional) | 9842 +---------------+---------------+---------------+--------------+ 9844 NOP-In is either sent by a target as a response to a NOP-Out, as a 9845 "ping" to an initiator, or as a means to carry a changed ExpCmdSN 9846 and/or MaxCmdSN if another PDU will not be available for a long 9847 time (as determined by the target). 9849 When a target receives the NOP-Out with a valid Initiator Task Tag 9850 (not the reserved value 0xffffffff), it MUST respond with a NOP-In 9851 with the same Initiator Task Tag that was provided in the NOP-Out 9852 request. It MUST also duplicate up to the first 9853 MaxRecvDataSegmentLength bytes of the initiator provided Ping 9854 Data. For such a response, the Target Transfer Tag MUST be 9855 0xffffffff. The target SHOULD NOT send a NOP-In in response to any 9856 other received NOP-Out in order to avoid lengthy sequences of NOP- 9857 In and NOP-Out PDUs sent in response to each other. 9859 Otherwise, when a target sends a NOP-In that is not a response to 9860 a Nop-Out received from the initiator, the Initiator Task Tag MUST 9861 be set to 0xffffffff and the Data Segment MUST NOT contain any 9862 data (DataSegmentLength MUST be 0). 9864 11.19.1. Target Transfer Tag 9866 If the target is responding to a NOP-Out, this is set to the 9867 reserved value 0xffffffff. 9869 If the target is sending a NOP-In as a Ping (intending to receive 9870 a corresponding NOP-Out), this field is set to a valid value (not 9871 the reserved 0xffffffff). 9873 If the target is initiating a NOP-In without wanting to receive a 9874 corresponding NOP-Out, this field MUST hold the reserved value of 9875 0xffffffff. 9877 11.19.2. StatSN 9879 The StatSN field will always contain the next StatSN. However, 9880 when the Initiator Task Tag is set to 0xffffffff StatSN for the 9881 connection is not advanced after this PDU is sent. 9883 11.19.3. LUN 9885 A LUN MUST be set to a correct value when the Target Transfer Tag 9886 is valid (not the reserved value 0xffffffff). 9888 12. iSCSI Security Text Keys and Authentication Methods 9890 Only the following keys are used during the SecurityNegotiation 9891 stage of the Login Phase: 9893 SessionType 9895 InitiatorName 9897 TargetName 9899 TargetAddress 9901 InitiatorAlias 9903 TargetAlias 9905 TargetPortalGroupTag 9907 AuthMethod and the keys used by the authentication methods 9908 specified under Section 12.1 along with all of their 9909 associated keys as well as Vendor-Specific Authentication 9910 Methods. 9912 Other keys MUST NOT be used. 9914 SessionType, InitiatorName, TargetName, InitiatorAlias, 9915 TargetAlias, and TargetPortalGroupTag are described in Section 13 9916 as they can be used also in the OperationalNegotiation stage. 9918 All security keys have connection-wide applicability. 9920 12.1. AuthMethod 9922 Use: During Login - Security Negotiation 9923 Senders: Initiator and Target 9924 Scope: connection 9926 AuthMethod = 9928 The main item of security negotiation is the authentication method 9929 (AuthMethod). 9931 The authentication methods that can be used (appear in the list- 9932 of-values) are either those listed in the following table or are 9933 vendor-unique methods: 9935 +------------------------------------------------------------+ 9936 | Name | Description | 9937 +------------------------------------------------------------+ 9938 | KRB5 | Kerberos V5 - defined in [RFC4120] | 9939 +------------------------------------------------------------+ 9940 | SRP | Secure Remote Password | 9941 | | defined in [RFC2945] | 9942 +------------------------------------------------------------+ 9943 | CHAP | Challenge Handshake Authentication Protocol| 9944 | | defined in [RFC1994] | 9945 +------------------------------------------------------------+ 9946 | None | No authentication | 9947 +------------------------------------------------------------+ 9949 The AuthMethod selection is followed by an "authentication 9950 exchange" specific to the authentication method selected. 9952 The authentication method proposal may be made by either the 9953 initiator or the target. However the initiator MUST make the first 9954 step specific to the selected authentication method as soon as it 9955 is selected. It follows that if the target makes the 9956 authentication method proposal the initiator sends the first 9957 key(s) of the exchange together with its authentication method 9958 selection. 9960 The authentication exchange authenticates the initiator to the 9961 target, and optionally, the target to the initiator. 9962 Authentication is OPTIONAL to use but MUST be supported by the 9963 target and initiator. 9965 The initiator and target MUST implement CHAP. All other 9966 authentication methods are OPTIONAL. 9968 Private or public extension algorithms MAY also be negotiated for 9969 authentication methods. Whenever a private or public extension 9970 algorithm is part of the default offer (the offer made in absence 9971 of explicit administrative action) the implementer MUST ensure 9972 that CHAP is listed as an alternative in the default offer and 9973 "None" is not part of the default offer. 9975 Extension authentication methods MUST be named using one of the 9976 following two formats: 9978 i) Z-reversed.vendor.dns_name.do_something= 9979 ii) New public key with no name prefix constraints 9981 Authentication methods named using the Z- format are used as 9982 private extensions. New public keys must be registered with IANA 9983 using IETF Review process ([RFC5226]). New public extensions for 9984 authentication methods MUST NOT use the Z# name prefix. 9986 For all of the public or private extension authentication methods, 9987 the method specific keys MUST conform to the format specified in 9988 Section 6.1 for standard-label. 9990 To identify the vendor for private extension authentication 9991 methods, we suggest you use the reversed DNS-name as a prefix to 9992 the proper digest names. 9994 The part of digest-name following Z- MUST conform to the format 9995 for standard-label specified in Section 6.1. 9997 Support for public or private extension authentication methods is 9998 OPTIONAL. 10000 The following subsections define the specific exchanges for each 10001 of the standardized authentication methods. As mentioned earlier 10002 the first step is always done by the initiator. 10004 12.1.1. Kerberos 10006 For KRB5 (Kerberos V5) [RFC4120] and [RFC1964], the initiator MUST 10007 use: 10009 KRB_AP_REQ= 10011 where KRB_AP_REQ is the client message as defined in [RFC4120]. 10013 The default principal name assumed by an iSCSI initiator or target 10014 (prior to any administrative configuration action) MUST be the 10015 iSCSI Initiator Name or iSCSI Target Name respectively, prefixed 10016 by the string "iscsi/". 10018 If the initiator authentication fails, the target MUST respond 10019 with a Login reject with "Authentication Failure" status. 10020 Otherwise, if the initiator has selected the mutual authentication 10021 option (by setting MUTUAL-REQUIRED in the ap-options field of the 10022 KRB_AP_REQ), the target MUST reply with: 10024 KRB_AP_REP= 10026 where KRB_AP_REP is the server's response message as defined in 10027 [RFC4120]. 10029 If mutual authentication was selected and target authentication 10030 fails, the initiator MUST close the connection. 10032 KRB_AP_REQ and KRB_AP_REP are binary-values and their binary 10033 length (not the length of the character string that represents 10034 them in encoded form) MUST NOT exceed 65536 bytes. Hex or Base64 10035 encoding may be used for KRB_AP_REQ and KRB_AP_REP, see Section 10036 6.1. 10038 12.1.2. Secure Remote Password (SRP) 10040 For SRP [RFC2945], the initiator MUST use: 10042 SRP_U= TargetAuth=Yes /* or TargetAuth=No */ 10044 The target MUST answer with a Login reject with the "Authorization 10045 Failure" status or reply with: 10047 SRP_GROUP= SRP_s= 10049 Where G1,G2... are proposed groups, in order of preference. 10051 The initiator MUST either close the connection or continue with: 10053 SRP_A= SRP_GROUP= 10055 Where G is one of G1,G2... that were proposed by the target. 10057 The target MUST answer with a Login reject with the 10058 "Authentication Failure" status or reply with: 10060 SRP_B= 10062 The initiator MUST close the connection or continue with: 10064 SRP_M= 10066 If the initiator authentication fails, the target MUST answer with 10067 a Login reject with "Authentication Failure" status. Otherwise, if 10068 the initiator sent TargetAuth=Yes in the first message (requiring 10069 target authentication), the target MUST reply with: 10071 SRP_HM= 10073 If the target authentication fails, the initiator MUST close the 10074 connection. 10076 Where U, s, A, B, M, and H(A | M | K) are defined in [RFC2945] 10077 (using the SHA1 hash function, such as SRP-SHA1) and G,Gn (Gn 10078 stands for G1,G2...) are identifiers of SRP groups specified in 10079 [RFC3723]. G, Gn, and U are text strings, s,A,B,M, and H(A | M | 10080 K) are binary-values. The length of s,A,B,M and H(A | M | K) in 10081 binary form (not the length of the character string that 10082 represents them in encoded form) MUST NOT exceed 1024 bytes. Hex 10083 or Base64 encoding may be used for s,A,B,M and H(A | M | K), see 10084 Section 6.1. 10086 See Appendix B for the related login example. 10088 For the SRP_GROUP, all the groups specified in [RFC3723] up to 10089 1536 bits (i.e., SRP-768, SRP-1024, SRP-1280, SRP-1536) must be 10090 supported by initiators and targets. To guarantee 10091 interoperability, targets MUST always offer "SRP-1536" as one of 10092 the proposed groups. 10094 12.1.3. Challenge Handshake Authentication Protocol (CHAP) 10096 For CHAP [RFC1994], the initiator MUST use: 10098 CHAP_A= 10100 Where A1,A2... are proposed algorithms, in order of preference. 10102 The target MUST answer with a Login reject with the 10103 "Authentication Failure" status or reply with: 10105 CHAP_A= CHAP_I= CHAP_C= 10107 Where A is one of A1,A2... that were proposed by the initiator. 10109 The initiator MUST continue with: 10111 CHAP_N= CHAP_R= 10113 or, if it requires target authentication, with: 10115 CHAP_N= CHAP_R= CHAP_I= CHAP_C= 10117 If the initiator authentication fails, the target MUST answer with 10118 a Login reject with "Authentication Failure" status. Otherwise, if 10119 the initiator required target authentication, the target MUST 10120 either answer with a Login reject with "Authentication Failure" or 10121 reply with: 10123 CHAP_N= CHAP_R= 10125 If target authentication fails, the initiator MUST close the 10126 connection. 10128 Where N, (A,A1,A2), I, C, and R are (correspondingly) the Name, 10129 Algorithm, Identifier, Challenge, and Response as defined in 10130 [RFC1994], N is a text string, A,A1,A2, and I are numbers, and C 10131 and R are binary-values and their binary length (not the length of 10132 the character string that represents them in encoded form) MUST 10133 NOT exceed 1024 bytes. Hex or Base64 encoding may be used for C 10134 and R, see Section 6.1. 10136 See Appendix B for the related login example. 10138 For the Algorithm, as stated in [RFC1994], one value is required 10139 to be implemented: 10141 5 (CHAP with MD5) 10143 To guarantee interoperability, initiators MUST always offer it as 10144 one of the proposed algorithms. 10146 13. Login/Text Operational Text Keys 10148 Some session specific parameters MUST only be carried on the 10149 leading connection and cannot be changed after the leading 10150 connection login (e.g., MaxConnections, the maximum number of 10151 connections). This holds for a single connection session with 10152 regard to connection restart. The keys that fall into this 10153 category have the use: LO (Leading Only). 10155 Keys that can only be used during login have the use: IO 10156 (initialize only), while those that can be used in both the Login 10157 Phase and Full Feature Phase have the use: ALL. 10159 Keys that can only be used during Full Feature Phase use FFPO 10160 (Full Feature Phase only). 10162 Keys marked as Any-Stage may also appear in the 10163 SecurityNegotiation stage while all other keys described in this 10164 Section are operational keys. 10166 Keys that do not require an answer are marked as Declarative. 10168 Key scope is indicated as session-wide (SW) or connection-only 10169 (CO). 10171 Result function, wherever mentioned, states the function that can 10172 be applied to check the validity of the responder selection. 10173 Minimum means that the selected value cannot exceed the offered 10174 value. Maximum means that the selected value cannot be lower than 10175 the offered value. AND means that the selected value must be a 10176 possible result of a Boolean "and" function with an arbitrary 10177 Boolean value (e.g., if the offered value is No the selected value 10178 must be No). OR means that the selected value must be a possible 10179 result of a Boolean "or" function with an arbitrary Boolean value 10180 (e.g., if the offered value is Yes the selected value must be 10181 Yes). 10183 13.1. HeaderDigest and DataDigest 10185 Use: IO 10186 Senders: Initiator and Target 10187 Scope: CO 10188 HeaderDigest = 10189 DataDigest = 10191 Default is None for both HeaderDigest and DataDigest. 10193 Digests enable the checking of end-to-end, non-cryptographic data 10194 integrity beyond the integrity checks provided by the link layers 10195 and the covering of the whole communication path including all 10196 elements that may change the network level PDUs such as routers, 10197 switches, and proxies. 10199 The following table lists cyclic integrity checksums that can be 10200 negotiated for the digests and that MUST be implemented by every 10201 iSCSI initiator and target. These digest options only have error 10202 detection significance. 10204 +---------------------------------------------+ 10205 | Name | Description | Generator | 10206 +---------------------------------------------+ 10207 | CRC32C | 32 bit CRC |0x11edc6f41| 10208 +---------------------------------------------+ 10209 | None | no digest | 10210 +---------------------------------------------+ 10212 The generator polynomial for this digest is given in hex-notation 10213 (e.g., 0x3b stands for 0011 1011 and the polynomial is 10214 x**5+X**4+x**3+x+1). 10216 When the Initiator and Target agree on a digest, this digest MUST 10217 be used for every PDU in Full Feature Phase. 10219 Padding bytes, when present in a segment covered by a CRC, SHOULD 10220 be set to 0 and are included in the CRC. 10222 The CRC MUST be calculated by a method that produces the same 10223 results as the following process: 10225 - The PDU bits are considered as the coefficients of a 10226 polynomial M(x) of degree n-1; bit 7 of the lowest numbered 10227 byte is considered the most significant bit (x^n-1), 10228 followed by bit 6 of the lowest numbered byte through bit 0 10229 of the highest numbered byte (x^0). 10231 - The most significant 32 bits are complemented. 10233 - The polynomial is multiplied by x^32 then divided by G(x). 10234 The generator polynomial produces a remainder R(x) of degree 10235 <= 31. 10237 - The coefficients of R(x) are considered a 32 bit sequence. 10239 - The bit sequence is complemented and the result is the CRC. 10241 - The CRC bits are mapped into the digest word. The x^31 10242 coefficient in bit 7 of the lowest numbered byte of the 10243 digest continuing through to the byte up to the x^24 10244 coefficient in bit 0 of the lowest numbered byte, continuing 10245 with the x^23 coefficient in bit 7 of next byte through x^0 10246 in bit 0 of the highest numbered byte. 10248 - Computing the CRC over any segment (data or header) extended 10249 to include the CRC built using the generator 0x11edc6f41 10250 will always get the value 0x1c2d19ed as its final remainder 10251 (R(x)). This value is given here in its polynomial form 10252 (i.e., not mapped as the digest word). 10254 For a discussion about selection criteria for the CRC, see 10255 [RFC3385]. For a detailed analysis of the iSCSI polynomial, see 10256 [Castagnoli93]. 10258 Private or public extension algorithms MAY also be negotiated for 10259 digests. Whenever a private or public digest extension algorithm 10260 is part of the default offer (the offer made in absence of 10261 explicit administrative action) the implementer MUST ensure that 10262 CRC32C is listed as an alternative in the default offer and "None" 10263 is not part of the default offer. 10265 Extension digest algorithms MUST be named using one of the 10266 following two formats: 10268 i) Y-reversed.vendor.dns_name.do_something= 10269 ii) New public key with no name prefix constraints 10271 Digests named using the Y- format are used for private purposes 10272 (unregistered). New public keys must be registered with IANA using 10273 IETF Review process ([RFC5226]). New public extensions for digests 10274 MUST NOT use the Y# name prefix. 10276 For private extension digests, to identify the vendor, we suggest 10277 you use the reversed DNS-name as a prefix to the proper digest 10278 names. 10280 The part of digest-name following Y- MUST conform to the format 10281 for standard-label specified in Section 6.1. 10283 Support for public or private extension digests is OPTIONAL. 10285 13.2. MaxConnections 10287 Use: LO 10288 Senders: Initiator and Target 10289 Scope: SW 10290 Irrelevant when: SessionType=Discovery 10292 MaxConnections= 10294 Default is 1. 10295 Result function is Minimum. 10297 Initiator and target negotiate the maximum number of connections 10298 requested/acceptable. 10300 13.3. SendTargets 10302 Use: FFPO 10303 Senders: Initiator 10304 Scope: SW 10306 For a complete description, see Appendix C. 10308 13.4. TargetName 10310 Use: IO by initiator, FFPO by target - only as response to a 10311 SendTargets, Declarative, Any-Stage 10312 Senders: Initiator and Target 10313 Scope: SW 10315 TargetName= 10317 Examples: 10319 TargetName=iqn.1993-11.com.disk-vendor:diskarrays.sn.45678 10321 TargetName=eui.020000023B040506 10323 TargetName=naa.62004567BA64678D0123456789ABCDEF 10325 The initiator of the TCP connection MUST provide this key to the 10326 remote endpoint in the first login request if the initiator is not 10327 establishing a discovery session. The iSCSI Target Name specifies 10328 the worldwide unique name of the target. 10330 The TargetName key may also be returned by the "SendTargets" text 10331 request (which is its only use when issued by a target). 10333 TargetName MUST NOT be redeclared within the login phase. 10335 13.5. InitiatorName 10337 Use: IO, Declarative, Any-Stage 10338 Senders: Initiator 10339 Scope: SW 10341 InitiatorName= 10343 Examples: 10345 InitiatorName=iqn.1992-04.com.os-vendor.plan9:cdrom.12345 10347 InitiatorName=iqn.2001-02.com.ssp.users:customer235.host90 10349 InitiatorName=naa.52004567BA64678D 10351 The initiator of the TCP connection MUST provide this key to the 10352 remote endpoint at the first Login of the Login Phase for every 10353 connection. The InitiatorName key enables the initiator to 10354 identify itself to the remote endpoint. 10356 InitiatorName MUST NOT be redeclared within the login phase. 10358 13.6. TargetAlias 10360 Use: ALL, Declarative, Any-Stage 10361 Senders: Target 10362 Scope: SW 10364 TargetAlias= 10366 Examples: 10368 TargetAlias=Bob-s Disk 10370 TargetAlias=Database Server 1 Log Disk 10372 TargetAlias=Web Server 3 Disk 20 10374 If a target has been configured with a human-readable name or 10375 description, this name SHOULD be communicated to the initiator 10376 during a Login Response PDU if SessionType=Normal (see 13.21). 10377 This string is not used as an identifier, nor is it meant to be 10378 used for authentication or authorization decisions. It can be 10379 displayed by the initiator's user interface in a list of targets 10380 to which it is connected. 10382 13.7. InitiatorAlias 10384 Use: ALL, Declarative, Any-Stage 10385 Senders: Initiator 10386 Scope: SW 10388 InitiatorAlias= 10390 Examples: 10392 InitiatorAlias=Web Server 4 10394 InitiatorAlias=spyalley.nsa.gov 10396 InitiatorAlias=Exchange Server 10398 If an initiator has been configured with a human-readable name or 10399 description, it SHOULD be communicated to the target during a 10400 Login Request PDU. If not, the host name can be used instead. This 10401 string is not used as an identifier, nor is meant to be used for 10402 authentication or authorization decisions. It can be displayed by 10403 the target's user interface in a list of initiators to which it is 10404 connected. 10406 13.8. TargetAddress 10408 Use: ALL, Declarative, Any-Stage 10409 Senders: Target 10410 Scope: SW 10412 TargetAddress=domainname[:port][,portal-group-tag] 10414 The domainname can be specified as either a DNS host name, a 10415 dotted-decimal IPv4 address, or a bracketed IPv6 address as 10416 specified in [RFC3986]. 10418 If the TCP port is not specified, it is assumed to be the IANA- 10419 assigned default port for iSCSI (see Section 14). 10421 If the TargetAddress is returned as the result of a redirect 10422 status in a login response, the comma and portal group tag MUST be 10423 omitted. 10425 If the TargetAddress is returned within a SendTargets response, 10426 the portal group tag MUST be included. 10428 Examples: 10430 TargetAddress=10.0.0.1:5003,1 10432 TargetAddress=[1080:0:0:0:8:800:200C:417A],65 10433 TargetAddress=[1080::8:800:200C:417A]:5003,1 10435 TargetAddress=computingcenter.example.com,23 10437 Use of the portal-group-tag is described in Appendix C. The 10438 formats for the port and portal-group-tag are the same as the one 10439 specified in TargetPortalGroupTag. 10441 13.9. TargetPortalGroupTag 10443 Use: IO by target, Declarative, Any-Stage 10444 Senders: Target 10445 Scope: SW 10447 TargetPortalGroupTag=<16-bit-binary-value> 10449 Examples: 10450 TargetPortalGroupTag=1 10452 The target portal group tag is a 16-bit binary-value that uniquely 10453 identifies a portal group within an iSCSI target node. This key 10454 carries the value of the tag of the portal group that is servicing 10455 the Login request. The iSCSI target returns this key to the 10456 initiator in the Login Response PDU to the first Login Request PDU 10457 that has the C bit set to 0 when TargetName is given by the 10458 initiator. 10460 [SAM2] notes in its informative text that TPGT value should be 10461 non-zero, note that it is incorrect. A zero value is allowed as a 10462 legal value for TPGT. This discrepancy currently stands corrected 10463 in [SAM4]. 10465 For the complete usage expectations of this key see Section 6.3. 10467 13.10. InitialR2T 10469 Use: LO 10470 Senders: Initiator and Target 10471 Scope: SW 10472 Irrelevant when: SessionType=Discovery 10474 InitialR2T= 10476 Examples: 10478 I->InitialR2T=No 10480 T->InitialR2T=No 10482 Default is Yes. 10483 Result function is OR. 10485 The InitialR2T key is used to turn off the default use of R2T for 10486 unidirectional and the output part of bidirectional commands, thus 10487 allowing an initiator to start sending data to a target as if it 10488 has received an initial R2T with Buffer Offset=Immediate Data 10489 Length and Desired Data Transfer Length=(min(FirstBurstLength, 10490 Expected Data Transfer Length) - Received Immediate Data Length). 10492 The default action is that R2T is required, unless both the 10493 initiator and the target send this key-pair attribute specifying 10494 InitialR2T=No. Only the first outgoing data burst (immediate data 10495 and/or separate PDUs) can be sent unsolicited (i.e., not requiring 10496 an explicit R2T). 10498 13.11. ImmediateData 10500 Use: LO 10501 Senders: Initiator and Target 10502 Scope: SW 10503 Irrelevant when: SessionType=Discovery 10505 ImmediateData= 10507 Default is Yes. 10508 Result function is AND. 10510 The initiator and target negotiate support for immediate data. To 10511 turn immediate data off, the initiator or target must state its 10512 desire to do so. ImmediateData can be turned on if both the 10513 initiator and target have ImmediateData=Yes. 10515 If ImmediateData is set to Yes and InitialR2T is set to Yes 10516 (default), then only immediate data are accepted in the first 10517 burst. 10519 If ImmediateData is set to No and InitialR2T is set to Yes, then 10520 the initiator MUST NOT send unsolicited data and the target MUST 10521 reject unsolicited data with the corresponding response code. 10523 If ImmediateData is set to No and InitialR2T is set to No, then 10524 the initiator MUST NOT send unsolicited immediate data, but MAY 10525 send one unsolicited burst of Data-OUT PDUs. 10527 If ImmediateData is set to Yes and InitialR2T is set to No, then 10528 the initiator MAY send unsolicited immediate data and/or one 10529 unsolicited burst of Data-OUT PDUs. 10531 The following table is a summary of unsolicited data options: 10533 +----------+-------------+------------------+--------------+ 10534 |InitialR2T|ImmediateData| Unsolicited |Immediate Data| 10535 | | | Data Out PDUs | | 10536 +----------+-------------+------------------+--------------+ 10537 | No | No | Yes | No | 10538 +----------+-------------+------------------+--------------+ 10539 | No | Yes | Yes | Yes | 10540 +----------+-------------+------------------+--------------+ 10541 | Yes | No | No | No | 10542 +----------+-------------+------------------+--------------+ 10543 | Yes | Yes | No | Yes | 10544 +----------+-------------+------------------+--------------+ 10546 13.12. MaxRecvDataSegmentLength 10548 Use: ALL, Declarative 10549 Senders: Initiator and Target 10550 Scope: CO 10552 MaxRecvDataSegmentLength= 10554 Default is 8192 bytes. 10556 The initiator or target declares the maximum data segment length 10557 in bytes it can receive in an iSCSI PDU. 10559 The transmitter (initiator or target) is required to send PDUs 10560 with a data segment that does not exceed MaxRecvDataSegmentLength 10561 of the receiver. 10563 A target receiver is additionally limited by MaxBurstLength for 10564 solicited data and FirstBurstLength for unsolicited data. An 10565 initiator MUST NOT send solicited PDUs exceeding MaxBurstLength 10566 nor unsolicited PDUs exceeding FirstBurstLength (or 10567 FirstBurstLength-Immediate Data Length if immediate data were 10568 sent). 10570 13.13. MaxBurstLength 10572 Use: LO 10573 Senders: Initiator and Target 10574 Scope: SW 10575 Irrelevant when: SessionType=Discovery 10577 MaxBurstLength= 10579 Default is 262144 (256 Kbytes). 10580 Result function is Minimum. 10582 The initiator and target negotiate maximum SCSI data payload in 10583 bytes in a Data-In or a solicited Data-Out iSCSI sequence. A 10584 sequence consists of one or more consecutive Data-In or Data-Out 10585 PDUs that end with a Data-In or Data-Out PDU with the F bit set to 10586 one. 10588 13.14. FirstBurstLength 10590 Use: LO 10591 Senders: Initiator and Target 10592 Scope: SW 10593 Irrelevant when: SessionType=Discovery 10594 Irrelevant when: ( InitialR2T=Yes and ImmediateData=No ) 10596 FirstBurstLength= 10597 Default is 65536 (64 Kbytes). 10598 Result function is Minimum. 10600 The initiator and target negotiate the maximum amount in bytes of 10601 unsolicited data an iSCSI initiator may send to the target during 10602 the execution of a single SCSI command. This covers the immediate 10603 data (if any) and the sequence of unsolicited Data-Out PDUs (if 10604 any) that follow the command. 10606 FirstBurstLength MUST NOT exceed MaxBurstLength. 10608 13.15. DefaultTime2Wait 10610 Use: LO 10611 Senders: Initiator and Target 10612 Scope: SW 10614 DefaultTime2Wait= 10616 Default is 2. 10617 Result function is Maximum. 10619 The initiator and target negotiate the minimum time, in seconds, 10620 to wait before attempting an explicit/implicit logout or an active 10621 task reassignment after an unexpected connection termination or a 10622 connection reset. 10624 A value of 0 indicates that logout or active task reassignment can 10625 be attempted immediately. 10627 13.16. DefaultTime2Retain 10629 Use: LO 10630 Senders: Initiator and Target 10631 Scope: SW 10633 DefaultTime2Retain= 10635 Default is 20. 10636 Result function is Minimum. 10638 The initiator and target negotiate the maximum time, in seconds 10639 after an initial wait (Time2Wait), before which an active task 10640 reassignment is still possible after an unexpected connection 10641 termination or a connection reset. 10643 This value is also the session state timeout if the connection in 10644 question is the last LOGGED_IN connection in the session. 10646 A value of 0 indicates that connection/task state is immediately 10647 discarded by the target. 10649 13.17. MaxOutstandingR2T 10651 Use: LO 10652 Senders: Initiator and Target 10653 Scope: SW 10655 MaxOutstandingR2T= 10656 Irrelevant when: SessionType=Discovery 10658 Default is 1. 10659 Result function is Minimum. 10661 Initiator and target negotiate the maximum number of outstanding 10662 R2Ts per task, excluding any implied initial R2T that might be 10663 part of that task. An R2T is considered outstanding until the last 10664 data PDU (with the F bit set to 1) is transferred, or a sequence 10665 reception timeout (Section 7.1.4.1) is encountered for that data 10666 sequence. 10668 13.18. DataPDUInOrder 10670 Use: LO 10671 Senders: Initiator and Target 10672 Scope: SW 10673 Irrelevant when: SessionType=Discovery 10675 DataPDUInOrder= 10677 Default is Yes. 10678 Result function is OR. 10680 No is used by iSCSI to indicate that the data PDUs within 10681 sequences can be in any order. Yes is used to indicate that data 10682 PDUs within sequences have to be at continuously increasing 10683 addresses and overlays are forbidden. 10685 13.19. DataSequenceInOrder 10687 Use: LO 10688 Senders: Initiator and Target 10689 Scope: SW 10690 Irrelevant when: SessionType=Discovery 10692 DataSequenceInOrder= 10694 Default is Yes. 10695 Result function is OR. 10697 A Data Sequence is a sequence of Data-In or Data-Out PDUs that end 10698 with a Data-In or Data-Out PDU with the F bit set to one. A Data- 10699 out sequence is sent either unsolicited or in response to an R2T. 10700 Sequences cover an offset-range. 10702 If DataSequenceInOrder is set to No, Data PDU sequences may be 10703 transferred in any order. 10705 If DataSequenceInOrder is set to Yes, Data Sequences MUST be 10706 transferred using continuously non-decreasing sequence offsets 10707 (R2T buffer offset for writes, or the smallest SCSI Data-In buffer 10708 offset within a read data sequence). 10710 If DataSequenceInOrder is set to Yes, a target may retry at most 10711 the last R2T, and an initiator may at most request retransmission 10712 for the last read data sequence. For this reason, if 10713 ErrorRecoveryLevel is not 0 and DataSequenceInOrder is set to Yes 10714 then MaxOustandingR2T MUST be set to 1. 10716 13.20. ErrorRecoveryLevel 10718 Use: LO 10719 Senders: Initiator and Target 10720 Scope: SW 10721 ErrorRecoveryLevel= 10723 Default is 0. 10724 Result function is Minimum. 10726 The initiator and target negotiate the recovery level supported. 10728 Recovery levels represent a combination of recovery capabilities. 10729 Each recovery level includes all the capabilities of the lower 10730 recovery levels and adds some new ones to them. 10732 In the description of recovery mechanisms, certain recovery 10733 classes are specified. Section 7.1.5 describes the mapping between 10734 the classes and the levels. 10736 13.21. SessionType 10738 Use: LO, Declarative, Any-Stage 10739 Senders: Initiator 10740 Scope: SW 10742 SessionType= 10744 Default is Normal. 10746 The Initiator indicates the type of session it wants to create. 10747 The target can either accept it or reject it. 10749 A Discovery session indicates to the Target that the only purpose 10750 of this Session is discovery. The only requests a target accepts 10751 in this type of session are a text request with a SendTargets key 10752 and a logout request with reason "close the session". 10754 The Discovery session implies MaxConnections = 1 and overrides 10755 both the default and an explicit setting. As Section 7.4.1 10756 states, ErrorRecoveryLevel MUST be 0 (zero) for Discovery 10757 sessions. 10759 Depending on the type of the session, a target may decide on 10760 resources to allocate and the security to enforce, etc. for thion. 10761 If the SessionType key is thus going to be offered as "Discovery", 10763 it SHOULD be offered in the initial Login request by the 10764 initiator. 10766 13.22. The Private Extension Key Format 10768 Use: ALL 10769 Senders: Initiator and Target 10770 Scope: specific key dependent 10772 X-reversed.vendor.dns_name.do_something= 10774 Keys with this format are used for private extension purposes. 10775 These keys always start with X- if unregistered with IANA 10776 (private). New public keys (if registered with IANA via an IETF 10777 Review, [RFC5226]) no longer have an X# name prefix requirement, 10778 implementers may propose any intuitive unique name. 10780 For unregistered keys, to identify the vendor, we suggest you use 10781 the reversed DNS-name as a prefix to the key-proper. 10783 The part of key-name following X- MUST conform to the format for 10784 key-name specified in Section 6.1. 10786 Vendor specific keys MUST ONLY be used in normal sessions. 10788 Support for public or private extension keys is OPTIONAL. 10790 13.23. TaskReporting 10792 Use: LO 10793 Senders: Initiator and Target 10794 Scope: SW 10795 Irrelevant when: SessionType=Discovery 10796 TaskReporting= 10798 Default is RFC3720. 10799 Result function is AND. 10801 This key is used to negotiate the task completion reporting 10802 semantics from the SCSI target. The following table describes the 10803 semantics that an iSCSI target MUST support for respective 10804 negotiated key values. Whenever this key is negotiated, at least 10805 the RFC3720 and ResponseFence values MUST be offered as options by 10806 the negotiation originator. 10807 +--------------+------------------------------------------+ 10808 | Name | Description | 10809 +--------------+------------------------------------------+ 10810 | RFC3720 | RFC 3720-compliant semantics. Response | 10811 | | fencing is not guaranteed and fast | 10812 | | completion of multi-task aborting is not | 10813 | | supported | 10814 +--------------+------------------------------------------+ 10815 | ResponseFence| Response Fence (Section 4.2.2.3.3) | 10816 | | semantics MUST be supported in reporting | 10817 | | task completions | 10818 +--------------+------------------------------------------+ 10819 | FastAbort | Updated fast multi-task abort semantics | 10820 | | defined in Section 4.2.3.4 MUST be | 10821 | | supported. Support for Response Fence is | 10822 | | implied -- i.e., (Section 4.2.2.3.3) | 10823 | | semantics MUST be supported as well | 10824 +--------------+------------------------------------------+ 10825 When TaskReporting is not negotiated to FastAbort, the standard 10826 multi-task abort semantics in Section 4.2.3.3 MUST be used. 10828 13.24. iSCSIProtocolLevel Negotiation 10830 The iSCSIProtocolLevel associated with this document is "1". As a 10831 responder or an originator in a negotiation of this key, an iSCSI 10832 implementation compliant to this document alone, without any 10833 future protocol extensions, MUST use this value as defined by the 10834 [iSCSI-SAM] document. 10836 13.25. Obsoleted Keys 10838 This document obsoletes the following keys defined in [RFC3720]: 10839 IFMarker, OFMarker, OFMarkInt, IFMarkInt. However, iSCSI 10840 implementations compliant to this document may still receive these 10841 obsoleted keys - i.e. in a responder role - in a text negotiation. 10843 When IFMarker or OFMarker key is received, a compliant iSCSI 10844 implementation SHOULD respond with the constant "Reject" value. 10845 The implementation MAY alternatively respond with a "No" value. 10847 However, the implementation MUST NOT respond with a 10848 "NotUnderstood" value for either of these keys. 10850 When IFMarkInt or OFMarkInt key is received, a compliant iSCSI 10851 implementation MUST respond with the constant "Reject" value. 10852 The implementation MUST NOT respond with a "NotUnderstood" value 10853 for either of these keys. 10855 13.26. X#NodeArchitecture 10857 13.26.1. Definition 10859 Use: LO, Declarative 10860 Senders: Initiator and Target 10861 Scope: SW 10863 X#NodeArchitecture= 10865 Default is none. 10867 Examples: 10868 X#NodeArchitecture=ExampleOS/v1234,ExampleInc_SW_Initiator/1.05a 10869 X#NodeArchitecture=ExampleInc_HW_Initiator/4010,Firmware/2.0.0.5 10870 X#NodeArchitecture=ExampleInc_SW_Initiator/2.1,CPU_Arch/i686 10872 This document does not define the structure or content of the list 10873 of values. 10875 The initiator or target declares the details of its iSCSI node 10876 architecture to the remote endpoint. These details may include, 10877 but are not limited to, iSCSI vendor software, firmware, or 10878 hardware versions, the OS version, or hardware architecture. This 10879 key may be declared on a Discovery session or a Normal session. 10881 The length of the key value (total length of the list-of-values) 10882 MUST NOT be greater than 255 bytes. 10884 X#NodeArchitecture MUST NOT be redeclared during the login phase. 10886 13.26.2. Implementation Requirements 10888 Functional behavior of the iSCSI node (this includes the iSCSI 10889 protocol logic -- the SCSI, iSCSI, and TCP/IP protocols) MUST NOT 10890 depend on the presence, absence, or content of the 10891 X#NodeArchitecture key. The key MUST NOT be used by iSCSI nodes 10892 for interoperability, or exclusion of other nodes. To ensure 10893 proper use, key values SHOULD be set by the node itself, and there 10894 SHOULD NOT be provisions for the key values to contain user- 10895 defined text. 10897 Nodes implementing this key MUST choose one of the following 10898 implementation options: 10900 - only transmit the key, 10902 - only log the key values received from other nodes, or 10904 - both transmit and log the key values. 10906 Each node choosing to implement transmission of the key values 10907 MUST be prepared to handle the response of iSCSI Nodes that do not 10908 understand the key. 10910 Nodes that implement transmission and/or logging of the key values 10911 may also implement administrative mechanisms that disable and/or 10912 change the logging and key transmission detail (see Section 9.4). 10913 Thus, a valid behavior for this key may be that a node is 10914 completely silent (the node does not transmit any key value, and 10915 simply discards any key values it receives without issuing a 10916 NotUnderstood response). 10918 14. Rationale for revised IANA Considerations 10920 This document makes rather significant changes in this area, and 10921 this Section outlines the reasons behind the changes. As 10922 previously specified in [RFC3720], iSCSI had used text string 10923 prefixes, such as X- and X#, to distinguish extended login/text 10924 keys, digest algorithms and authentication methods from their 10925 standardized counterparts. Based on experience with other 10926 protocols, [RFC6648] however strongly recommends against this 10927 practice, in large part because extensions that use such prefixes 10928 may become standard over time at which point it can be infeasible 10929 to change their text string names due to widespread usage under 10930 the existing text string name. 10932 iSCSI's experience with public extensions supports the 10933 recommendations in [RFC6648], as the only extension item ever 10934 registered with IANA, the X#NodeArchitecture key, was specified as 10935 a standard key in a standards-track RFC [RFC4850], and hence did 10936 not require the X# prefix. In addition, that key is the only 10937 public iSCSI extension that has been registered with IANA since 10938 RFC 3720 was originally published, so there has been effectively 10939 no use of the X#, Y# and Z# public extension formats. 10941 Therefore, this document makes the following changes to the IANA 10942 registration procedures for iSCSI: 10944 (1) The separate registries for X#, Y# and Z# public 10945 extensions are removed. The single entry in the registry for 10946 X# login/text keys(X#NodeArchitecture) is transferred to the 10947 main login/text key registry. IANA has never created the 10948 latter two registries because there have been no 10949 registration requests for them. These public extension 10950 formats (X#, Y#, Z#) MUST NOT be used with the exception of 10951 the existing X#NodeArchitecture key. 10953 (2) The Registration Procedures for the main login/text key, 10954 digest algorithm and authentication method IANA registries 10955 are changed to IETF Review [RFC5226] for possible future 10956 extensions to iSCSI. This change includes a deliberate 10957 decision to remove the possibility of specifying an IANA- 10958 registered iSCSI extension in an RFC published via an RFC 10960 Editor independent submission, as the level of review in 10961 that process is insufficient for iSCSI extensions. 10963 (3) The restriction against registering items using the 10964 private extension formats (X-, Y-, Z-) in the main IANA 10965 registries is removed. Extensions using these formats MAY be 10966 registered under the IETF Review registration procedures, 10967 but each format is restricted to the type of extension for 10968 which it is specified in this RFC and MUST NOT be used for 10969 other types. For example, the X- extension format for 10970 extension login/text keys MUST NOT be used for digest 10971 algorithms or authentication methods. 10973 15. IANA Considerations 10975 The well-known TCP port number for iSCSI connections assigned by 10976 IANA is 3260 and this is the default iSCSI port. Implementations 10977 needing a system TCP port number may use port 860, the port 10978 assigned by IANA as the iSCSI system port; however in order to use 10979 port 860, it MUST be explicitly specified - implementations MUST 10980 NOT default to use of port 860, as 3260 is the only allowed 10981 default. 10983 IANA is requested to update all references to RFC 3720, RFC 4850 10984 and RFC 5048 to instead reference this RFC in all of the iSCSI 10985 registries that are part of the "Internet Small Computer System 10986 Interface (iSCSI) Parameters" set of registries. This change 10987 reflects the fact that those three RFCs are obsoleted by this RFC. 10988 References to other RFCs that are not being obsoleted (e.g., RFC 10989 3723, RFC 5046) should not be changed. 10991 IANA is requested to perform the following actions on the iSCSI 10992 Login/Text Keys registry: 10994 - Change the registration procedure to IETF Review from 10995 Standard Required. 10997 - Change the RFC 5048 reference for the registry to reference 10998 this RFC. 11000 - Add the X#NodeArchitecture Key from the iSCSI extended key 11001 registry and change its reference to this RFC. 11003 - Change all references of RFC 3720 and RFC 5048 to reference 11004 this RFC. 11006 IANA is requested to change the Registration Procedures for the 11007 iSCSI authentication methods and iSCSI digests registries to IETF 11008 Review from RFC Required. 11010 IANA is requested to remove the iSCSI extended key registry, as 11011 its one entry is to be added to the iSCSI login/text keys 11012 registry. 11014 IANA is requested to mark obsolete the values 4 and 5, for SPKM1 11015 and SPKM2 respectively, in the iSCSI authentication methods 11016 subregistry of the Internet Small Computer System Interface 11017 (iSCSI) Parameters registries. 11019 All the other IANA considerations stated in [RFC3720] and 11020 [RFC5048] remain unchanged. 11022 This document obsoletes the SPKM1 and SPKM2 key values for the 11023 AuthMethod text key. Consequently, the SPKM_ text key prefix MUST 11024 be treated as obsolete and be not reused. 11026 References 11028 Normative References 11030 [EUI] "Guidelines for 64-bit Global Identifier (EUI-64)", 11031 http://standards.ieee.org/regauth/oui/tutorials/EUI64.html 11033 [FC-FS3] INCITS 470-2011, Fibre Channel - Framing and 11034 Signaling - 3 (FC-FS-3). 11036 [IPSEC-IPS] Black, D., Koning, P., "Securing Block Storage 11037 Protocols over IP: RFC 3723 Requirements Update for IPsec 11038 v3", draft-ietf-storm-ipsec-ips-update-03.txt (work in 11039 progress), July 2013 11041 [iSCSI-SAM] Knight, F., Chadalapaka, M., "Internet Small 11042 Computer Systems Interface (iSCSI) SCSI Architecture 11043 Features Update", draft-ietf-storm-iscsi-sam-07.txt (work in 11044 progress), July 2013 11046 [OUI] "IEEE OUI and Company_Id Assignments", 11047 http://standards.ieee.org/regauth/oui 11049 [RFC1122] R.Braden, "Requirements for Internet Hosts -- 11050 Communication Layers", October 1989. 11052 [RFC1964] J. Linn, "The Kerberos Version 5 GSS-API Mechanism", 11053 June 1996. 11055 [RFC1982] Elz, R., Bush, R., "Serial Number Arithmetic", 11056 August 1996. 11058 [RFC1994] W. Simpson, "PPP Challenge Handshake Authentication 11059 Protocol (CHAP)", August 1996. 11061 [RFC2119] Bradner, S. "Key Words for use in RFCs to Indicate 11062 Requirement Levels", BCP 14, March 1997. 11064 [RFC2404] C. Madson, R. Glenn, "The Use of HMAC-SHA-1-96 11065 within ESP and AH", November 1998. 11067 [RFC2451] R. Pereira, R. Adams "The ESP CBC-Mode Cipher 11068 Algorithms". 11070 [RFC2945] Wu, T., "The SRP Authentication and Key Exchange 11071 System", September 2000. 11073 [RFC3454] Hoffman, P. and M. Blanchet, "Preparation of 11074 Internationalized Strings ("stringprep")", RFC 3454, 11075 December 2002. 11077 [RFC3566] Frankel, S. and H. Herbert, "The AES-XCBC-MAC-96 11078 Algorithm and Its Use With IPsec", RFC 3566, September 2003. 11080 [RFC3629] Yergeau, F., "UTF-8, a Transformation Format of ISO 11081 10646", RFC 3629, November 2003 11083 [RFC3686] Housley, R., "Using Advanced Encryption Standard 11084 (AES) Counter Mode with IPsec Encapsulating Security Payload 11085 (ESP)", RFC 3686, January 2004. 11087 [RFC3722] Bakke, M., "String Profile for Internet Small 11088 Computer Systems Interface (iSCSI) Names", RFC 3722, March 11089 2004. 11091 [RFC3723] Aboba, B., Tseng, J., Walker, J., Rangan, V. and F. 11092 Travostino, "Securing Block Storage Protocols over IP", RFC 11093 3723, March 2004. 11095 [RFC3986] T. Berners-Lee, R. Fielding, L. Masinter "Uniform 11096 Resource Identifier (URI): Generic Syntax", January 2005. 11098 [RFC4106] J. Viega, D. McGrew, "The Use of Galois/Counter Mode 11099 (GCM) in IPsec Encapsulating Security Payload (ESP)", RFC 11100 4106, June 2005. 11102 [RFC4120] Neuman, C., Yu, T., Hartman, S., Raeburn, K, "The 11103 Kerberos Network Authentication Service (V5)", RFC 4120, 11104 July 2005. 11106 [RFC4171] J. Tseng, K. Gibbons, F. Travostino, C. Du Laney, J. 11107 Souza, "Internet Storage Name Service (iSNS)", September 11108 2005. 11110 [RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing 11111 Architecture", February 2006. 11113 [RFC4301] S. Kent, K.Seo, "Security Architecture for the 11114 Internet Protocol", December 2005. 11116 [RFC4303] Kent, S., "IP Encapsulating Security Payload (ESP)", 11117 RFC 4303, December 2005 11119 [RFC4543] D. McGrew, J. Viega, "The Use of Galois Message 11120 Authentication Code (GMAC) in IPsec ESP and AH", RFC 4543, 11121 May 2006 11123 [RFC4648] S. Josefsson, "The Base16, Base32, and Base64 Data 11124 Encodings", RFC 4648, October 2006 11126 [RFC5226] H. Alvestrand, T. Narten, "Guidelines for Writing an 11127 IANA Considerations Section in RFCs", RFC 5226, May 2008 11129 [RFC5996] C. Kaufman, P. Hoffman, Y. Nir, P. Eronen, "Internet 11130 Key Exchange Protocol Version 2 (IKEv2) ", RFC 5996, 11131 September 2010. 11133 [SAM2] T10/1157-D, SCSI Architecture Model - 2 (SAM-2). 11135 [SAM4] T10/1683-D, SCSI Architecture Model - 4 (SAM-4). 11137 [SPC2] T10/1236-D, SCSI Primary Commands-2. 11139 [SPC3] T10/1416-D, SCSI Primary Commands-3. 11141 [UML] ISO/IEC 19501, Unified Modeling Language 11142 Specification Version 1.4.2. 11144 [UNICODE] Unicode Standard Annex #15, "Unicode Normalization 11145 Forms", http://www.unicode.org/unicode/reports/tr15 11147 Informative References 11149 [FC-SP-2] T11/1835-D, Fibre Channel Security Protocols- 2 (FC- 11150 SP-2). 11152 [RFC1737] K. Sollins, L. Masinter "Functional Requirements for 11153 Uniform Resource Names". 11155 [RFC5433] T. Clancy, H. Tschofenig "Extensible Authentication 11156 Protocol - Generalized Pre-Shared Key (EAP-GPSK) Method", 11157 RFC 5433, February 2009. 11159 [IB] InfiniBand{tm} Architecture Specification, Vol. 1, 11160 Rel.1.0.a, InfiniBand Trade 11161 Association(http://www.infinibandta.org). 11163 [Castagnoli93] G. Castagnoli, S. Braeuer and M. Herrman 11164 "Optimization of Cyclic Redundancy-Check Codes with 24 and 11165 32 Parity Bits", IEEE Transact. on Communications, Vol. 41, 11166 No. 6, June 1993. 11168 [CRC] ISO 3309, High-Level Data Link Control (CRC 32). 11170 [RFC2401] S. Kent, R. Atkinson, "Security Architecture for the 11171 Internet Protocol ", November 1998. 11173 [RFC2406] S. Kent, R. Atkinson, "IP Encapsulating Security 11174 Payload (ESP)", November 1998. 11176 [RFC2407] D. Piper, "The Internet IP Security Domain of 11177 Interpretation for ISAKMP", November 1998. 11179 [RFC2409] D. Harkins, D. Carrel, "The Internet Key Exchange 11180 (IKE)", November 1998. 11182 [RFC2608] E. Guttman, C. Perkins, J. Veizades, M. Day, 11183 "Service Location Protocol, Version 2", June 1999. 11185 [RFC2743] J.Linn, "Generic Security Service Application 11186 Program Interface Version 2, Update 1", January 2000 11188 [RFC2865] C. Rigney, S. Willens, A. Rubens, W. Simpson, 11189 "Remote Authentication Dial In User Service (RADIUS)", June 11190 2000. 11192 [RFC3385] Sheinwald, D., Satran, J., Thaler, P. and V. 11193 Cavanna, "Internet Protocol Small Computer System Interface 11194 (iSCSI) Cyclic Redundancy Check (CRC)/Checksum 11195 Considerations", RFC 3385, September 2002. 11197 [RFC3602] S. Frankel, R. Glenn, S. Kelly, "The AES-CBC Cipher 11198 Algorithm and Its Use with IPsec", RFC 3602, September 2003. 11200 [RFC3720] Satran, J., Meth, K., Sapuntzakis, C., Chadalapaka, 11201 M., and E. Zeidner, "Internet Small Computer Systems 11202 Interface (iSCSI)", RFC 3720, April 2004. 11204 [RFC3721] Bakke, M., Hafner, J., Hufferd, J., Voruganti, K. 11205 and M. Krueger, "Internet Small Computer Systems Interface 11206 (iSCSI) Naming and Discovery", RFC 3721, March 2004 11208 [RFC3783] M. Chadalapaka, R. Elliott, "Small Computer Systems 11209 Interface (SCSI) Command Ordering Considerations with 11210 iSCSI", RFC 3783, May 2004. 11212 [RFC4121] L. Zhu, K. Jaganathan, S. Hartman, "The Kerberos 11213 Version 5 Generic Security Service Application Program 11214 Interface (GSS-API) Mechanism: Version 2", RFC 4121, July 11215 2005. 11217 [RFC4297] Romanow, A., Mogul, J., Talpey, T., and S. Bailey, 11218 "Remote Direct Memory Access (RDMA) over IP Problem 11219 Statement", RFC 4297, October 2004 11221 [RFC4850] Wysochanski, D., "Declarative Public Extension Key 11222 for Internet Small Computer Systems Interface (iSCSI) Node 11223 Architecture", RFC 4850, April 2007. 11225 [RFC5046] Ko, M., Chadalapaka, M., Hufferd, J., Elzur, U., 11226 Shah, H., and P. Thaler, "Internet Small Computer System 11227 Interface (iSCSI) Extensions for Remote Direct Memory Access 11228 (RDMA)", RFC 5046, October 2007 11230 [RFC5048] Chadalapaka, M., "Internet Small Computer Systems 11231 Interface (iSCSI) Corrections and Clarifications", RFC 5048, 11232 October 2007. 11234 [RFC6648] P. Saint-Andre, D. Crocker, M. Nottingham, 11235 "Deprecating the X- Prefix and Similar Constructs in 11236 Application Protocols", RFC 6648, June 2012 11238 [SAS] T10/2125-D, Serial Attached SCSI - 2.1 (SAS-2.1); 11239 T10/2124-D, SAS Protocol Layer (SPL); T10/2124-M, SAS 11240 Protocol Layer (SPL) Amendment #1 (SPL AM1). 11242 [SBC2] NCITS.405-205, SCSI Block Commands - 2 (SBC-2). 11244 [SPC4] T10/1731-D, SCSI Primary Commands-4. 11246 Appendix A. Examples 11248 Read Operation Example 11250 +------------------+-----------------------+---------------------+ 11251 |Initiator Function| PDU Type | Target Function | 11252 +------------------+-----------------------+---------------------+ 11253 | Command request |SCSI Command (READ)>>> | | 11254 | (read) | | | 11255 +------------------+-----------------------+---------------------+ 11256 | | |Prepare Data Transfer| 11257 +------------------+-----------------------+---------------------+ 11258 | Receive Data | <<< SCSI Data-in | Send Data | 11259 +------------------+-----------------------+---------------------+ 11260 | Receive Data | <<< SCSI Data-in | Send Data | 11261 +------------------+-----------------------+---------------------+ 11262 | Receive Data | <<< SCSI Data-in | Send Data | 11263 +------------------+-----------------------+---------------------+ 11264 | | <<< SCSI Response |Send Status and Sense| 11265 +------------------+-----------------------+---------------------+ 11266 | Command Complete | | | 11267 +------------------+-----------------------+---------------------+ 11269 Write Operation Example 11271 +------------------+-----------------------+---------------------+ 11272 |Initiator Function| PDU Type | Target Function | 11273 +------------------+-----------------------+---------------------+ 11274 | Command request |SCSI Command (WRITE)>>>| Receive command | 11275 | (write) | | and queue it | 11276 +------------------+-----------------------+---------------------+ 11277 | | | Process old commands| 11278 +------------------+-----------------------+---------------------+ 11279 | | | Ready to process | 11280 | | <<< R2T | WRITE command | 11281 +------------------+-----------------------+---------------------+ 11282 | Send Data | SCSI Data-out >>> | Receive Data | 11283 +------------------+-----------------------+---------------------+ 11284 | | <<< R2T | Ready for data | 11285 +------------------+-----------------------+---------------------+ 11286 | | <<< R2T | Ready for data | 11287 +------------------+-----------------------+---------------------+ 11288 | Send Data | SCSI Data-out >>> | Receive Data | 11289 +------------------+-----------------------+---------------------+ 11290 | Send Data | SCSI Data-out >>> | Receive Data | 11291 +------------------+-----------------------+---------------------+ 11292 | | <<< SCSI Response |Send Status and Sense| 11293 +------------------+-----------------------+---------------------+ 11294 | Command Complete | | | 11295 +------------------+-----------------------+---------------------+ 11297 R2TSN/DataSN Use Examples 11299 Output (write) data DataSN/R2TSN Example 11300 +------------------+-----------------------+---------------------+ 11301 |Initiator Function| PDU Type & Content | Target Function | 11302 +------------------+-----------------------+---------------------+ 11303 | Command request |SCSI Command (WRITE)>>>| Receive command | 11304 | (write) | | and queue it | 11305 +------------------+-----------------------+---------------------+ 11306 | | | Process old commands| 11307 +------------------+-----------------------+---------------------+ 11308 | | <<< R2T | Ready for data | 11309 | | R2TSN = 0 | | 11310 +------------------+-----------------------+---------------------+ 11311 | | <<< R2T | Ready for more data | 11312 | | R2TSN = 1 | | 11313 +------------------+-----------------------+---------------------+ 11314 | Send Data | SCSI Data-out >>> | Receive Data | 11315 | for R2TSN 0 | DataSN = 0, F=0 | | 11316 +------------------+-----------------------+---------------------+ 11317 | Send Data | SCSI Data-out >>> | Receive Data | 11318 | for R2TSN 0 | DataSN = 1, F=1 | | 11319 +------------------+-----------------------+---------------------+ 11320 | Send Data | SCSI Data >>> | Receive Data | 11321 | for R2TSN 1 | DataSN = 0, F=1 | | 11322 +------------------+-----------------------+---------------------+ 11323 | | <<< SCSI Response |Send Status and Sense| 11324 | | ExpDataSN = 0 | | 11325 +------------------+-----------------------+---------------------+ 11326 | Command Complete | | | 11327 +------------------+-----------------------+---------------------+ 11329 Input (read) data DataSN Example 11331 +------------------+-----------------------+---------------------+ 11332 |Initiator Function| PDU Type | Target Function | 11333 +------------------+-----------------------+---------------------+ 11334 | Command request |SCSI Command (READ)>>> | | 11335 | (read) | | | 11336 +------------------+-----------------------+---------------------+ 11337 | | |Prepare Data Transfer| 11338 +------------------+-----------------------+---------------------+ 11339 | Receive Data | <<< SCSI Data-in | Send Data | 11340 | | DataSN = 0, F=0 | | 11341 +------------------+-----------------------+---------------------+ 11342 | Receive Data | <<< SCSI Data-in | Send Data | 11343 | | DataSN = 1, F=0 | | 11344 +------------------+-----------------------+---------------------+ 11345 | Receive Data | <<< SCSI Data-in | Send Data | 11346 | | DataSN = 2, F=1 | | 11347 +------------------+-----------------------+---------------------+ 11348 | | <<< SCSI Response |Send Status and Sense| 11349 | | ExpDataSN = 3 | | 11350 +------------------+-----------------------+---------------------+ 11351 | Command Complete | | | 11352 +------------------+-----------------------+---------------------+ 11354 Bidirectional DataSN Example 11356 +------------------+-----------------------+---------------------+ 11357 |Initiator Function| PDU Type | Target Function | 11358 +------------------+-----------------------+---------------------+ 11359 | Command request |SCSI Command >>> | | 11360 | (Read-Write) | Read-Write | | 11361 +------------------+-----------------------+---------------------+ 11362 | | | Process old commands| 11363 +------------------+-----------------------+---------------------+ 11364 | | <<< R2T | Ready to process | 11365 | | R2TSN = 0 | WRITE command | 11366 +------------------+-----------------------+---------------------+ 11367 | * Receive Data | <<< SCSI Data-in | Send Data | 11368 | | DataSN = 0, F=0 | | 11369 +------------------+-----------------------+---------------------+ 11370 | * Receive Data | <<< SCSI Data-in | Send Data | 11371 | | DataSN = 1, F=1 | | 11372 +------------------+-----------------------+---------------------+ 11373 | * Send Data | SCSI Data-out >>> | Receive Data | 11374 | for R2TSN 0 | DataSN = 0, F=1 | | 11375 +------------------+-----------------------+---------------------+ 11376 | | <<< SCSI Response |Send Status and Sense| 11377 | | ExpDataSN = 2 | | 11378 +------------------+-----------------------+---------------------+ 11379 | Command Complete | | | 11380 +------------------+-----------------------+---------------------+ 11382 *) Send data and Receive Data may be transferred simultaneously as 11383 in an atomic Read-Old-Write-New or sequentially as in an atomic 11384 Read-Update-Write (in the latter case the R2T may follow the 11385 received data). 11387 Unsolicited and immediate output (write) data with DataSN Example 11388 +------------------+-----------------------+---------------------+ 11389 |Initiator Function| PDU Type & Content | Target Function | 11390 +------------------+-----------------------+---------------------+ 11391 | Command request |SCSI Command (WRITE)>>>| Receive command | 11392 | (write) |F=0 | and data | 11393 |+ immediate data | | and queue it | 11394 +------------------+-----------------------+---------------------+ 11395 | Send Unsolicited | SCSI Write Data >>> | Receive more Data | 11396 | Data | DataSN = 0, F=1 | | 11397 +------------------+-----------------------+---------------------+ 11398 | | | Process old commands| 11399 +------------------+-----------------------+---------------------+ 11400 | | <<< R2T | Ready for more data | 11401 | | R2TSN = 0 | | 11402 +------------------+-----------------------+---------------------+ 11403 | Send Data | SCSI Write Data >>> | Receive Data | 11404 | for R2TSN 0 | DataSN = 0, F=1 | | 11405 +------------------+-----------------------+---------------------+ 11406 | | <<< SCSI Response |Send Status and Sense| 11407 | | | | 11408 +------------------+-----------------------+---------------------+ 11409 | Command Complete | | | 11410 +------------------+-----------------------+---------------------+ 11412 CRC Examples 11414 N.B. all Values are Hexadecimal 11416 32 bytes of zeroes: 11418 Byte: 0 1 2 3 11420 0: 00 00 00 00 11421 ... 11422 28: 00 00 00 00 11424 CRC: aa 36 91 8a 11426 32 bytes of ones: 11428 Byte: 0 1 2 3 11429 0: ff ff ff ff 11430 ... 11431 28: ff ff ff ff 11433 CRC: 43 ab a8 62 11435 32 bytes of incrementing 00..1f: 11437 Byte: 0 1 2 3 11439 0: 00 01 02 03 11440 ... 11441 28: 1c 1d 1e 1f 11443 CRC: 4e 79 dd 46 11445 32 bytes of decrementing 1f..00: 11447 Byte: 0 1 2 3 11449 0: 1f 1e 1d 1c 11450 ... 11451 28: 03 02 01 00 11453 CRC: 5c db 3f 11 11455 An iSCSI - SCSI Read (10) Command PDU 11457 Byte: 0 1 2 3 11459 0: 01 c0 00 00 11460 4: 00 00 00 00 11461 8: 00 00 00 00 11462 12: 00 00 00 00 11463 16: 14 00 00 00 11464 20: 00 00 04 00 11465 24: 00 00 00 14 11466 28: 00 00 00 18 11467 32: 28 00 00 00 11468 36: 00 00 00 00 11469 40: 02 00 00 00 11470 44: 00 00 00 00 11472 CRC: 56 3a 96 d9 11474 Appendix B. Login Phase Examples 11476 In the first example, the initiator and target authenticate each 11477 other via Kerberos: 11479 I-> Login (CSG,NSG=0,1 T=1) 11480 InitiatorName=iqn.1999-07.com.os:hostid.77 11481 TargetName=iqn.1999-07.com.example:diskarray.sn.88 11482 AuthMethod=KRB5,SRP,None 11484 T-> Login (CSG,NSG=0,0 T=0) 11485 AuthMethod=KRB5 11487 I-> Login (CSG,NSG=0,1 T=1) 11488 KRB_AP_REQ= 11490 (krb_ap_req contains the Kerberos V5 ticket and authenticator with 11491 MUTUAL-REQUIRED set in the ap-options field) 11493 If the authentication is successful, the target proceeds with: 11495 T-> Login (CSG,NSG=0,1 T=1) 11496 KRB_AP_REP= 11498 (krb_ap_rep is the Kerberos V5 mutual authentication reply) 11500 If the authentication is successful, the initiator may proceed 11501 with: 11503 I-> Login (CSG,NSG=1,0 T=0) FirstBurstLength=8192 11504 T-> Login (CSG,NSG=1,0 T=0) FirstBurstLength=4096 11505 MaxBurstLength=8192 11506 I-> Login (CSG,NSG=1,0 T=0) MaxBurstLength=8192 11507 ... more iSCSI Operational Parameters 11509 T-> Login (CSG,NSG=1,0 T=0) 11510 ... more iSCSI Operational Parameters 11512 And at the end: 11514 I-> Login (CSG,NSG=1,3 T=1) 11515 optional iSCSI parameters 11517 T-> Login (CSG,NSG=1,3 T=1) "login accept" 11519 If the initiator's authentication by the target is not successful, 11520 the target responds with: 11522 T-> Login "login reject" 11524 instead of the Login KRB_AP_REP message, and terminates the 11525 connection. 11527 If the target's authentication by the initiator is not successful, 11528 the initiator terminates the connection (without responding to the 11529 Login KRB_AP_REP message). 11531 In the next example only the initiator is authenticated by the 11532 target via Kerberos: 11534 I-> Login (CSG,NSG=0,1 T=1) 11535 InitiatorName=iqn.1999-07.com.os:hostid.77 11536 TargetName=iqn.1999-07.com.example:diskarray.sn.88 11537 AuthMethod=SRP,KRB5,None 11539 T-> Login-PR (CSG,NSG=0,0 T=0) 11540 AuthMethod=KRB5 11542 I-> Login (CSG,NSG=0,1 T=1) 11543 KRB_AP_REQ=krb_ap_req 11545 (MUTUAL-REQUIRED not set in the ap-options field of krb_ap_req) 11547 If the authentication is successful, the target proceeds with: 11549 T-> Login (CSG,NSG=0,1 T=1) 11551 I-> Login (CSG,NSG=1,0 T=0) 11552 ... iSCSI parameters 11554 T-> Login (CSG,NSG=1,0 T=0) 11555 ... iSCSI parameters 11557 . . . 11559 T-> Login (CSG,NSG=1,3 T=1)"login accept" 11561 In the next example, the initiator and target authenticate each 11562 other via SRP: 11564 I-> Login (CSG,NSG=0,1 T=1) 11565 InitiatorName=iqn.1999-07.com.os:hostid.77 11566 TargetName=iqn.1999-07.com.example:diskarray.sn.88 11567 AuthMethod=KRB5,SRP,None 11569 T-> Login-PR (CSG,NSG=0,0 T=0) 11570 AuthMethod=SRP 11572 I-> Login (CSG,NSG=0,0 T=0) 11573 SRP_U= 11574 TargetAuth=Yes 11576 T-> Login (CSG,NSG=0,0 T=0) 11577 SRP_N= 11578 SRP_g= 11579 SRP_s= 11581 I-> Login (CSG,NSG=0,0 T=0) 11582 SRP_A= 11584 T-> Login (CSG,NSG=0,0 T=0) 11585 SRP_B= 11587 I-> Login (CSG,NSG=0,1 T=1) 11588 SRP_M= 11590 If the initiator authentication is successful, the target 11591 proceeds: 11593 T-> Login (CSG,NSG=0,1 T=1) 11594 SRP_HM= 11596 Where N, g, s, A, B, M, and H(A | M | K) are defined in 11597 [RFC2945]. 11599 If the target authentication is not successful, the initiator 11600 terminates the connection; otherwise, it proceeds. 11602 I-> Login (CSG,NSG=1,0 T=0) 11603 ... iSCSI parameters 11605 T-> Login (CSG,NSG=1,0 T=0) 11606 ... iSCSI parameters 11608 And at the end: 11610 I-> Login (CSG,NSG=1,3 T=1) 11611 optional iSCSI parameters 11613 T-> Login (CSG,NSG=1,3 T=1) "login accept" 11615 If the initiator authentication is not successful, the target 11616 responds with: 11618 T-> Login "login reject" 11620 Instead of the T-> Login SRP_HM= message and 11621 terminates the connection. 11623 In the next example, only the initiator is authenticated by the 11624 target via SRP: 11626 I-> Login (CSG,NSG=0,1 T=1) 11627 InitiatorName=iqn.1999-07.com.os:hostid.77 11628 TargetName=iqn.1999-07.com.example:diskarray.sn.88 11629 AuthMethod=KRB5,SRP,None 11631 T-> Login-PR (CSG,NSG=0,0 T=0) 11632 AuthMethod=SRP 11634 I-> Login (CSG,NSG=0,0 T=0) 11635 SRP_U= 11636 TargetAuth=No 11638 T-> Login (CSG,NSG=0,0 T=0) 11639 SRP_N= 11640 SRP_g= 11641 SRP_s= 11643 I-> Login (CSG,NSG=0,0 T=0) 11644 SRP_A= 11646 T-> Login (CSG,NSG=0,0 T=0) 11647 SRP_B= 11649 I-> Login (CSG,NSG=0,1 T=1) 11650 SRP_M= 11652 If the initiator authentication is successful, the target 11653 proceeds: 11655 T-> Login (CSG,NSG=0,1 T=1) 11657 I-> Login (CSG,NSG=1,0 T=0) 11659 ... iSCSI parameters 11661 T-> Login (CSG,NSG=1,0 T=0) 11663 ... iSCSI parameters 11665 And at the end: 11667 I-> Login (CSG,NSG=1,3 T=1) 11669 optional iSCSI parameters 11671 T-> Login (CSG,NSG=1,3 T=1) "login accept" 11673 In the next example the initiator and target authenticate each 11674 other via CHAP: 11676 I-> Login (CSG,NSG=0,0 T=0) 11678 InitiatorName=iqn.1999-07.com.os:hostid.77 11680 TargetName=iqn.1999-07.com.example:diskarray.sn.88 11682 AuthMethod=KRB5,CHAP,None 11684 T-> Login-PR (CSG,NSG=0,0 T=0) 11686 AuthMethod=CHAP 11688 I-> Login (CSG,NSG=0,0 T=0) 11690 CHAP_A= 11692 T-> Login (CSG,NSG=0,0 T=0) 11693 CHAP_A= 11694 CHAP_I= 11695 CHAP_C= 11697 I-> Login (CSG,NSG=0,1 T=1) 11698 CHAP_N= 11700 CHAP_R= 11702 CHAP_I= 11704 CHAP_C= 11706 If the initiator authentication is successful, the target 11707 proceeds: 11709 T-> Login (CSG,NSG=0,1 T=1) 11711 CHAP_N= 11713 CHAP_R= 11715 If the target authentication is not successful, the initiator 11716 aborts the connection; otherwise, it proceeds. 11718 I-> Login (CSG,NSG=1,0 T=0) 11720 ... iSCSI parameters 11722 T-> Login (CSG,NSG=1,0 T=0) 11724 ... iSCSI parameters 11726 And at the end: 11728 I-> Login (CSG,NSG=1,3 T=1) 11730 optional iSCSI parameters 11732 T-> Login (CSG,NSG=1,3 T=1) "login accept" 11734 If the initiator authentication is not successful, the target 11735 responds with: 11737 T-> Login "login reject" 11739 Instead of the Login CHAP_R= "proceed and change 11740 stage" message and terminates the connection. 11742 In the next example, only the initiator is authenticated by the 11743 target via CHAP: 11745 I-> Login (CSG,NSG=0,1 T=0) 11747 InitiatorName=iqn.1999-07.com.os:hostid.77 11749 TargetName=iqn.1999-07.com.example:diskarray.sn.88 11751 AuthMethod=KRB5,CHAP,None 11753 T-> Login-PR (CSG,NSG=0,0 T=0) 11755 AuthMethod=CHAP 11757 I-> Login (CSG,NSG=0,0 T=0) 11759 CHAP_A= 11761 T-> Login (CSG,NSG=0,0 T=0) 11762 CHAP_A= 11763 CHAP_I= 11764 CHAP_C= 11766 I-> Login (CSG,NSG=0,1 T=1) 11768 CHAP_N= 11770 CHAP_R= 11772 If the initiator authentication is successful, the target 11773 proceeds: 11775 T-> Login (CSG,NSG=0,1 T=1) 11777 I-> Login (CSG,NSG=1,0 T=0) 11779 ... iSCSI parameters 11781 T-> Login (CSG,NSG=1,0 T=0) 11783 ... iSCSI parameters 11785 And at the end: 11787 I-> Login (CSG,NSG=1,3 T=1) 11789 optional iSCSI parameters 11791 T-> Login (CSG,NSG=1,3 T=1) "login accept" 11793 In the next example, the initiator does not offer any security 11794 parameters. It therefore may offer iSCSI parameters on the Login 11795 PDU with the T bit set to 1, and the target may respond with a 11796 final Login Response PDU immediately: 11798 I-> Login (CSG,NSG=1,3 T=1) 11800 InitiatorName=iqn.1999-07.com.os:hostid.77 11802 TargetName=iqn.1999-07.com.example:diskarray.sn.88 11804 ... iSCSI parameters 11806 T-> Login (CSG,NSG=1,3 T=1) "login accept" 11808 ... ISCSI parameters 11810 In the next example, the initiator does offer security 11811 parameters on the Login PDU, but the target does not choose 11812 any (i.e., chooses the "None" values): 11814 I-> Login (CSG,NSG=0,1 T=1) 11816 InitiatorName=iqn.1999-07.com.os:hostid.77 11818 TargetName=iqn.1999-07.com.example:diskarray.sn.88 11820 AuthMethod=KRB5,SRP,None 11822 T-> Login-PR (CSG,NSG=0,1 T=1) 11824 AuthMethod=None 11826 I-> Login (CSG,NSG=1,0 T=0) 11828 ... iSCSI parameters 11830 T-> Login (CSG,NSG=1,0 T=0) 11832 ... iSCSI parameters 11834 And at the end: 11836 I-> Login (CSG,NSG=1,3 T=1) 11838 optional iSCSI parameters 11840 T-> Login (CSG,NSG=1,3 T=1) "login accept" 11842 Appendix C. SendTargets Operation 11844 The text in this Appendix is a normative part of this document. 11846 To reduce the amount of configuration required on an initiator, 11847 iSCSI provides the SendTargets text request. The initiator uses 11848 the SendTargets request to get a list of targets to which it may 11849 have access, as well as the list of addresses (IP address and TCP 11850 port) on which these targets may be accessed. 11852 To make use of SendTargets, an initiator must first establish one 11853 of two types of sessions. If the initiator establishes 11854 the session using the key "SessionType=Discovery", the session is 11855 a discovery session, and a target name does not need to be 11856 specified. Otherwise, the session is a normal, operational 11857 session. The SendTargets command MUST only be sent during the 11858 Full Feature Phase of a normal or discovery session. 11860 A system that contains targets MUST support discovery sessions on 11861 each of its iSCSI IP address-port pairs, and MUST support the 11862 SendTargets command on the discovery session. In a discovery 11863 session, a target MUST return all path information (IP address- 11864 port pairs and portal group tags) for the targets on the target 11865 network entity which the requesting initiator is authorized to 11866 access. 11868 A target MUST support the SendTargets command on operational 11869 sessions; these will only return path information about the target 11870 to which the session is connected, and do not need to return 11871 information about other target names that may be defined in the 11872 responding system. 11874 An initiator MAY make use of the SendTargets as it sees fit. 11876 A SendTargets command consists of a single Text request PDU. 11877 This PDU contains exactly one text key and value. The text key 11878 MUST be SendTargets. The expected response depends upon the 11879 value, as well as whether the session is a discovery or 11880 operational session. 11882 The value must be one of: 11884 All 11886 The initiator is requesting that information on all relevant 11887 targets known to the implementation be returned. This value 11888 MUST be supported on a discovery session, and MUST NOT be 11889 supported on an operational session. 11891 11893 If an iSCSI target name is specified, the session should 11894 respond with addresses for only the named target, if 11895 possible. This value MUST be supported on discovery 11896 sessions. A discovery session MUST be capable of returning 11897 addresses for those targets that would have been returned 11898 had value=All been designated. 11900 11902 The session should only respond with addresses for the target 11903 to which the session is logged in. This MUST be supported 11904 on operational sessions, and MUST NOT return targets other 11905 than the one to which the session is logged in. 11907 The response to this command is a text response that contains a 11908 list of zero or more targets and, optionally, their addresses. 11909 Each target is returned as a target record. A target record 11910 begins with the TargetName text key, followed by a list of 11911 TargetAddress text keys, and bounded by the end of the text 11912 response or the next TargetName key, which begins a new record. 11913 No text keys other than TargetName and TargetAddress are permitted 11914 within a SendTargets response. 11916 For the format of the TargetName, see Section 13.4. 11918 A discovery session MAY respond to a SendTargets request with its 11919 complete list of targets, or with a list of targets that is based 11920 on the name of the initiator logged in to the session. 11922 A SendTargets response MUST NOT contain target names if there are 11923 no targets for the requesting initiator to access. 11925 Each target record returned includes zero or more TargetAddress 11926 fields. 11928 Each target record starts with one text key of the form: 11930 TargetName= 11932 Followed by zero or more address keys of the form: 11934 TargetAddress=[:], 11937 The hostname-or-ipaddress contains a domain name, IPv4 address, or 11938 IPv6 address ([RFC4291]), as specified for the TargetAddress key. 11940 A hostname-or-ipaddress duplicated in TargetAddress responses for 11941 a given node (the port is absent or equal) would probably indicate 11942 that multiple address families are in use at once (IPv6 and IPv4). 11944 Each TargetAddress belongs to a portal group, identified by its 11945 numeric portal group tag (as in Section 13.9). The iSCSI target 11946 name, together with this tag, constitutes the SCSI port 11947 identifier; the tag only needs to be unique within a given 11948 target's name list of addresses. 11950 Multiple-connection sessions can span iSCSI addresses that belong 11951 to the same portal group. 11953 Multiple-connection sessions cannot span iSCSI addresses that 11954 belong to different portal groups. 11956 If a SendTargets response reports an iSCSI address for a target, 11957 it SHOULD also report all other addresses in its portal group in 11958 the same response. 11960 A SendTargets text response can be longer than a single Text 11961 Response PDU, and makes use of the long text responses as 11962 specified. 11964 After obtaining a list of targets from the discovery target 11965 session, 11966 an iSCSI initiator may initiate new sessions to log in to the 11967 discovered targets for full operation. The initiator MAY keep the 11968 discovery session open, and MAY send subsequent SendTargets 11969 commands to discover new targets. 11971 Examples: 11973 This example is the SendTargets response from a single target that 11974 has no other interface ports. 11976 Initiator sends text request that contains: 11978 SendTargets=All 11980 Target sends a text response that contains: 11982 TargetName=iqn.1993-11.com.example:diskarray.sn.8675309 11984 All the target had to return in the simple case was the target 11985 name. It is assumed by the initiator that the IP address and TCP 11986 port for this target are the same as used on the current 11987 connection to the default iSCSI target. 11989 The next example has two internal iSCSI targets, each accessible 11990 via two different ports with different IP addresses. The 11991 following is the text response: 11993 TargetName=iqn.1993-11.com.example:diskarray.sn.8675309 11995 TargetAddress=10.1.0.45:3000,1 11997 TargetAddress=10.1.1.45:3000,2 11999 TargetName=iqn.1993-11.com.example:diskarray.sn.1234567 12001 TargetAddress=10.1.0.45:3000,1 12003 TargetAddress=10.1.1.45:3000,2 12005 Both targets share both addresses; the multiple addresses are 12006 likely used to provide multi-path support. The initiator may 12007 connect to either target name on either address. Each of the 12008 addresses has its own portal group tag; they do not support 12009 spanning multiple-connection sessions with each other. Keep in 12010 mind that the portal group tags for the two named targets are 12011 independent of one another; portal group "1" on the first target 12012 is not necessarily the same as portal group "1" on the second 12013 target. 12015 In the above example, a DNS host name or an IPv6 address could 12016 have been returned instead of an IPv4 address. 12018 The next text response shows a target that supports spanning 12019 sessions across multiple addresses, and further illustrates the 12020 use of the portal group tags: 12022 TargetName=iqn.1993-11.com.example:diskarray.sn.8675309 12024 TargetAddress=10.1.0.45:3000,1 12026 TargetAddress=10.1.1.46:3000,1 12028 TargetAddress=10.1.0.47:3000,2 12030 TargetAddress=10.1.1.48:3000,2 12032 TargetAddress=10.1.1.49:3000,3 12034 In this example, any of the target addresses can be used to reach 12035 the same target. A single-connection session can be established 12036 to any of these TCP addresses. A multiple-connection session 12037 could span addresses .45 and .46 or .47 and .48, but cannot span 12038 any other combination. A TargetAddress with its own tag (.49) 12039 cannot be combined with any other address within the same session. 12041 This SendTargets response does not indicate whether .49 supports 12042 multiple connections per session; it is communicated via the 12043 MaxConnections text key upon login to the target. 12045 Appendix D. Algorithmic Presentation of Error Recovery Classes 12047 This Appendix illustrates the error recovery classes using a 12048 pseudo-programming-language. The procedure names are chosen to be 12049 obvious to most implementers. Each of the recovery classes 12050 described has initiator procedures as well as target procedures. 12051 These algorithms focus on outlining the mechanics of error 12052 recovery classes, and do not exhaustively describe all other 12053 aspects/cases. Examples of this approach are: 12055 - Handling for only certain Opcode types is shown. 12057 - Only certain reason codes (e.g., Recovery in Logout command) 12058 are outlined. 12060 - Resultant cases, such as recovery of Synchronization on a 12061 header digest error are considered out-of-scope in these 12062 algorithms. In this particular example, a header digest 12063 error may lead to connection recovery if some type of sync 12064 and steering layer is not implemented. 12066 These algorithms strive to convey the iSCSI error recovery 12067 concepts in the simplest terms, and are not designed to be 12068 optimal. 12070 D.1. General Data Structure and Procedure Description 12072 This Section defines the procedures and data structures that are 12073 commonly used by all the error recovery algorithms. The structures 12074 may not be the exhaustive representations of what is required for 12075 a typical implementation. 12077 Data structure definitions - 12078 struct TransferContext { 12079 int TargetTransferTag; 12080 int ExpectedDataSN; 12081 }; 12083 struct TCB { /* task control block */ 12084 Boolean SoFarInOrder; 12085 int ExpectedDataSN; /* used for both R2Ts, and Data */ 12086 int MissingDataSNList[MaxMissingDPDU]; 12087 Boolean FbitReceived; 12088 Boolean StatusXferd; 12089 Boolean CurrentlyAllegiant; 12090 int ActiveR2Ts; 12091 int Response; 12092 char *Reason; 12093 struct TransferContext 12094 TransferContextList[MaxOutStandingR2T]; 12095 int InitiatorTaskTag; 12096 int CmdSN; 12097 int SNACK_Tag; 12098 }; 12100 struct Connection { 12101 struct Session SessionReference; 12102 Boolean SoFarInOrder; 12103 int CID; 12104 int State; 12105 int CurrentTimeout; 12106 int ExpectedStatSN; 12107 int MissingStatSNList[MaxMissingSPDU]; 12108 Boolean PerformConnectionCleanup; 12109 }; 12111 struct Session { 12112 int NumConnections; 12113 int CmdSN; 12114 int Maxconnections; 12115 int ErrorRecoveryLevel; 12116 struct iSCSIEndpoint OtherEndInfo; 12117 struct Connection ConnectionList[MaxSupportedConns]; 12118 }; 12120 Procedure descriptions - 12121 Receive-a-In-PDU(transport connection, inbound PDU); 12122 check-basic-validity(inbound PDU); 12123 Start-Timer(timeout handler, argument, timeout value); 12124 Build-And-Send-Reject(transport connection, bad PDU, reason 12125 code); 12127 D.2. Within-command Error Recovery Algorithms 12129 D.2.1. Procedure Descriptions 12131 Recover-Data-if-Possible(last required DataSN, task control 12132 block); 12133 Build-And-Send-DSnack(task control block); 12134 Build-And-Send-RDSnack(task control block); 12135 Build-And-Send-Abort(task control block); 12136 SCSI-Task-Completion(task control block); 12137 Build-And-Send-A-Data-Burst(transport connection, data- 12138 descriptor, 12139 task control 12140 block); 12141 Build-And-Send-R2T(transport connection, data-descriptor, 12142 task control 12143 block); 12144 Build-And-Send-Status(transport connection, task control block); 12145 Transfer-Context-Timeout-Handler(transfer context); 12147 Notes: 12149 - One procedure used in this Section: Handle-Status-SNACK- 12150 request is defined in Within-connection recovery algorithms. 12152 - The Response processing pseudo-code, shown in the target 12153 algorithms, applies to all solicited PDUs that carry StatSN 12154 - SCSI Response, Text Response etc. 12156 D.2.2. Initiator Algorithms 12158 Recover-Data-if-Possible(LastRequiredDataSN, TCB) 12159 { 12160 if (operational ErrorRecoveryLevel > 0) { 12161 if (# of missing PDUs is trackable) { 12162 Note the missing DataSNs in TCB. 12163 if (the task spanned a change in 12164 MaxRecvDataSegmentLength) { 12165 if (TCB.StatusXferd is TRUE) 12166 drop the status PDU; 12167 Build-And-Send-RDSnack(TCB); 12168 } else { 12169 Build-And-Send-DSnack(TCB); 12170 } 12172 } else { 12173 TCB.Reason = "Protocol service CRC error"; 12174 } 12175 } else { 12176 TCB.Reason = "Protocol service CRC error"; 12177 } 12178 if (TCB.Reason == "Protocol service CRC error") { 12179 Clear the missing PDU list in the TCB. 12180 if (TCB.StatusXferd is not TRUE) 12181 Build-And-Send-Abort(TCB); 12182 } 12183 } 12185 Receive-a-In-PDU(Connection, CurrentPDU) 12186 { 12187 check-basic-validity(CurrentPDU); 12188 if (Header-Digest-Bad) discard, return; 12189 Retrieve TCB for CurrentPDU.InitiatorTaskTag. 12190 if ((CurrentPDU.type == Data) 12191 or (CurrentPDU.type = R2T)) { 12192 if (Data-Digest-Bad for Data) { 12193 send-data-SNACK = TRUE; 12194 LastRequiredDataSN = CurrentPDU.DataSN; 12195 } else { 12196 if (TCB.SoFarInOrder = TRUE) { 12197 if (current DataSN is expected) { 12198 Increment TCB.ExpectedDataSN. 12199 } else { 12200 TCB.SoFarInOrder = FALSE; 12201 send-data-SNACK = TRUE; 12202 } 12203 } else { 12204 if (current DataSN was considered 12205 missing) { 12206 remove current DataSN from missing 12207 PDU list. 12208 } else if (current DataSN is higher than 12209 expected) { 12210 send-data-SNACK = TRUE; 12211 } else { 12212 discard, return; 12213 } 12214 Adjust TCB.ExpectedDataSN if 12215 appropriate. 12216 } 12217 LastRequiredDataSN = CurrentPDU.DataSN - 1; 12218 } 12219 if (send-data-SNACK is TRUE and 12220 task is not already considered failed) { 12221 Recover-Data-if-Possible(LastRequiredDataSN, TCB); 12222 } 12223 if (missing data PDU list is empty) { 12224 TCB.SoFarInOrder = TRUE; 12225 } 12226 if (CurrentPDU.type == R2T) { 12227 Increment ActiveR2Ts for this task. 12228 Create a data-descriptor for the data burst. 12229 Build-And-Send-A-Data-Burst(Connection, data- 12230 descriptor, 12231 TCB); 12232 } 12233 } else if (CurrentPDU.type == Response) { 12234 if (Data-Digest-Bad) { 12235 send-status-SNACK = TRUE; 12236 } else { 12237 TCB.StatusXferd = TRUE; 12238 Store the status information in TCB. 12239 if (ExpDataSN does not match) { 12240 TCB.SoFarInOrder = FALSE; 12241 Recover-Data-if-Possible(current DataSN, TCB); 12242 } 12243 if (missing data PDU list is empty) { 12244 TCB.SoFarInOrder = TRUE; 12245 } 12246 } 12247 } else { /* REST UNRELATED TO WITHIN-COMMAND-RECOVERY, NOT 12248 SHOWN */ 12249 } 12250 if ((TCB.SoFarInOrder == TRUE) and 12251 (TCB.StatusXferd == TRUE)) { 12253 SCSI-Task-Completion(TCB); 12254 } 12255 } 12257 D.2.3. Target Algorithms 12259 Receive-a-In-PDU(Connection, CurrentPDU) 12260 { 12261 check-basic-validity(CurrentPDU); 12262 if (Header-Digest-Bad) discard, return; 12263 Retrieve TCB for CurrentPDU.InitiatorTaskTag. 12264 if (CurrentPDU.type == Data) { 12265 Retrieve TContext from CurrentPDU.TargetTransferTag; 12266 if (Data-Digest-Bad) { 12267 Build-And-Send-Reject(Connection, CurrentPDU, 12268 Payload-Digest-Error); 12269 Note the missing data PDUs in MissingDataRange[]. 12270 send-recovery-R2T = TRUE; 12271 } else { 12272 if (current DataSN is not expected) { 12273 Note the missing data PDUs in MissingDataRange[]. 12274 send-recovery-R2T = TRUE; 12275 } 12276 if (CurrentPDU.Fbit == TRUE) { 12277 if (current PDU is solicited) { 12278 Decrement TCB.ActiveR2Ts. 12279 } 12280 if ((current PDU is unsolicited and 12281 data received is less than I/O length and 12282 data received is less than 12283 FirstBurstLength) 12284 or (current PDU is solicited and the length of 12285 this burst is less than expected)) { 12286 send-recovery-R2T = TRUE; 12287 Note the missing data in MissingDataRange[]. 12288 } 12289 } 12290 } 12291 Increment TContext.ExpectedDataSN. 12292 if (send-recovery-R2T is TRUE and 12293 task is not already considered failed) { 12294 if (operational ErrorRecoveryLevel > 0) { 12295 Increment TCB.ActiveR2Ts. 12296 Create a data-descriptor for the data burst 12297 from MissingDataRange. 12298 Build-And-Send-R2T(Connection, data-descriptor, 12299 TCB); 12300 } else { 12301 if (current PDU is the last unsolicited) 12302 TCB.Reason = "Not enough unsolicited data"; 12303 else 12304 TCB.Reason = "Protocol service CRC error"; 12305 } 12306 } 12307 if (TCB.ActiveR2Ts == 0) { 12308 Build-And-Send-Status(Connection, TCB); 12309 } 12310 } else if (CurrentPDU.type == SNACK) { 12311 snack-failure = FALSE; 12312 if (operational ErrorRecoveryLevel > 0) { 12313 if (CurrentPDU.type == Data/R2T) { 12314 if (the request is satisfiable) { 12315 if (request for Data) { 12316 Create a data-descriptor for the data burst 12317 from BegRun and RunLength. 12318 Build-And-Send-A-Data-Burst(Connection, 12319 data-descriptor, TCB); 12320 } else { /* R2T */ 12321 Create a data-descriptor for the data burst 12322 from BegRun and RunLength. 12323 Build-And-Send-R2T(Connection, data- 12324 descriptor, 12325 TCB); 12326 } 12327 } else { 12328 snack-failure = TRUE; 12329 } 12330 } else if (CurrentPDU.type == status) { 12331 Handle-Status-SNACK-request(Connection, 12332 CurrentPDU); 12333 } else if (CurrentPDU.type == DataACK) { 12334 Consider all data upto CurrentPDU.BegRun as 12335 acknowledged. 12336 Free up the retransmission resources for that data. 12337 } else if (CurrentPDU.type == R-Data SNACK) { 12338 Create a data descriptor for a data burst 12339 covering 12340 all unacknowledged data. 12341 Build-And-Send-A-Data-Burst(Connection, 12342 data-descriptor, TCB); 12343 TCB.SNACK_Tag = CurrentPDU.SNACK_Tag; 12344 if (there's no more data to send) { 12345 Build-And-Send-Status(Connection, TCB); 12346 } 12347 } 12348 } else { /* operational ErrorRecoveryLevel = 0 */ 12349 snack-failure = TRUE; 12350 } 12351 if (snack-failure == TRUE) { 12352 Build-And-Send-Reject(Connection, CurrentPDU, 12353 SNACK-Reject); 12354 if (TCB.StatusXferd != TRUE) { 12355 TCB.Reason = "SNACK Rejected"; 12356 Build-And-Send-Status(Connection, TCB); 12357 } 12358 } 12360 } else { /* REST UNRELATED TO WITHIN-COMMAND-RECOVERY, NOT 12361 SHOWN */ 12362 } 12363 } 12365 Transfer-Context-Timeout-Handler(TContext) 12366 { 12367 Retrieve TCB and Connection from TContext. 12368 Decrement TCB.ActiveR2Ts. 12369 if (operational ErrorRecoveryLevel > 0 and 12370 task is not already considered failed) { 12371 Note the missing data PDUs in MissingDataRange[]. 12372 Create a data-descriptor for the data burst 12373 from MissingDataRange[]. 12374 Build-And-Send-R2T(Connection, data-descriptor, TCB); 12376 } else { 12377 TCB.Reason = "Protocol service CRC error"; 12378 if (TCB.ActiveR2Ts = 0) { 12379 Build-And-Send-Status(Connection, TCB); 12380 } 12381 } 12382 } 12384 D.3. Within-connection Recovery Algorithms 12386 D.3.1. Procedure Descriptions 12388 Procedure descriptions: 12389 Recover-Status-if-Possible(transport connection, 12390 currently received PDU); 12391 Evaluate-a-StatSN(transport connection, currently received PDU); 12392 Retransmit-Command-if-Possible(transport connection, CmdSN); 12393 Build-And-Send-SSnack(transport connection); 12394 Build-And-Send-Command(transport connection, task control 12395 block); 12396 Command-Acknowledge-Timeout-Handler(task control block); 12397 Status-Expect-Timeout-Handler(transport connection); 12398 Build-And-Send-Nop-Out(transport connection); 12399 Handle-Status-SNACK-request(transport connection, status SNACK 12400 PDU); 12401 Retransmit-Status-Burst(status SNACK, task control block); 12402 Is-Acknowledged(beginning StatSN, run length); 12404 Implementation-specific tunables: 12405 InitiatorProactiveSNACKEnabled 12407 Notes: 12408 - The initiator algorithms only deal with unsolicited Nop-In 12409 PDUs for generating status SNACKs. A solicited Nop-In PDU 12410 has an assigned StatSN, which, when out of order, could 12411 trigger the out of order StatSN handling in Within-command 12412 algorithms, again leading to Recover-Status-if-Possible. 12414 - The pseudo-code shown may result in the retransmission of 12415 unacknowledged commands in more cases than necessary. This 12416 will not, however, affect the correctness of the operation 12417 because the target is required to discard the duplicate 12418 CmdSNs. 12420 - The procedure Build-And-Send-Async is defined in the 12421 Connection recovery algorithms. 12423 - The procedure Status-Expect-Timeout-Handler describes how 12424 initiators may proactively attempt to retrieve the Status if 12425 they so choose. This procedure is assumed to be triggered 12426 much before the standard ULP timeout. 12428 D.3.2. Initiator Algorithms 12430 Recover-Status-if-Possible(Connection, CurrentPDU) 12431 { 12432 if ((Connection.state == LOGGED_IN) and 12433 connection is not already considered 12434 failed) { 12435 if (operational ErrorRecoveryLevel > 0) { 12436 if (# of missing PDUs is trackable) { 12437 Note the missing StatSNs in Connection 12438 that were not already requested with SNACK; 12439 Build-And-Send-SSnack(Connection); 12440 } else { 12441 Connection.PerformConnectionCleanup = TRUE; 12442 } 12443 } else { 12444 Connection.PerformConnectionCleanup = TRUE; 12445 } 12446 if (Connection.PerformConnectionCleanup == TRUE) { 12447 Start-Timer(Connection-Cleanup-Handler, Connection, 12448 0); 12449 } 12450 } 12452 } 12454 Retransmit-Command-if-Possible(Connection, CmdSN) 12455 { 12456 if (operational ErrorRecoveryLevel > 0) { 12457 Retrieve the InitiatorTaskTag, and thus TCB for the 12458 CmdSN. 12459 Build-And-Send-Command(Connection, TCB); 12460 } 12461 } 12463 Evaluate-a-StatSN(Connection, CurrentPDU) 12464 { 12465 send-status-SNACK = FALSE; 12466 if (Connection.SoFarInOrder == TRUE) { 12467 if (current StatSN is the expected) { 12468 Increment Connection.ExpectedStatSN. 12469 } else { 12470 Connection.SoFarInOrder = FALSE; 12471 send-status-SNACK = TRUE; 12472 } 12473 } else { 12474 if (current StatSN was considered missing) { 12475 remove current StatSN from the missing list. 12476 } else { 12477 if (current StatSN is higher than expected){ 12478 send-status-SNACK = TRUE; 12479 } else { 12480 send-status-SNACK = FALSE; 12481 discard the PDU; 12482 } 12483 } 12484 Adjust Connection.ExpectedStatSN if appropriate. 12485 if (missing StatSN list is empty) { 12486 Connection.SoFarInOrder = TRUE; 12487 } 12488 } 12489 return send-status-SNACK; 12490 } 12491 Receive-a-In-PDU(Connection, CurrentPDU) 12492 { 12493 check-basic-validity(CurrentPDU); 12494 if (Header-Digest-Bad) discard, return; 12495 Retrieve TCB for CurrentPDU.InitiatorTaskTag. 12496 if (CurrentPDU.type == Nop-In) { 12497 if (the PDU is unsolicited) { 12498 if (current StatSN is not expected) { 12499 Recover-Status-if-Possible(Connection, 12500 CurrentPDU); 12501 } 12502 if (current ExpCmdSN is not Session.CmdSN) { 12503 Retransmit-Command-if-Possible(Connection, 12504 CurrentPDU.ExpCmdSN); 12505 } 12506 } 12507 } else if (CurrentPDU.type == Reject) { 12508 if (it is a data digest error on immediate data) { 12509 Retransmit-Command-if-Possible(Connection, 12511 CurrentPDU.BadPDUHeader.CmdSN); 12512 } 12513 } else if (CurrentPDU.type == Response) { 12514 send-status-SNACK = Evaluate-a-StatSN(Connection, 12515 CurrentPDU); 12516 if (send-status-SNACK == TRUE) 12517 Recover-Status-if-Possible(Connection, CurrentPDU); 12518 } else { /* REST UNRELATED TO WITHIN-CONNECTION-RECOVERY, 12519 * NOT SHOWN */ 12520 } 12521 } 12523 Command-Acknowledge-Timeout-Handler(TCB) 12524 { 12525 Retrieve the Connection for TCB. 12526 Retransmit-Command-if-Possible(Connection, TCB.CmdSN); 12527 } 12529 Status-Expect-Timeout-Handler(Connection) 12530 { 12531 if (operational ErrorRecoveryLevel > 0) { 12532 Build-And-Send-Nop-Out(Connection); 12533 } else if (InitiatorProactiveSNACKEnabled){ 12534 if ((Connection.state == LOGGED_IN) and 12535 connection is not already considered 12536 failed) { 12537 Build-And-Send-SSnack(Connection); 12538 } 12539 } 12540 } 12542 D.3.3.Target Algorithms 12543 Handle-Status-SNACK-request(Connection, CurrentPDU) 12544 { 12545 if (operational ErrorRecoveryLevel > 0) { 12546 if (request for an acknowledged run) { 12547 Build-And-Send-Reject(Connection, CurrentPDU, 12548 Protocol-Error); 12549 } else if (request for an untransmitted run) { 12550 discard, return; 12551 } else { 12552 Retransmit-Status-Burst(CurrentPDU, TCB); 12553 } 12554 } else { 12555 Build-And-Send-Async(Connection, DroppedConnection, 12556 DefaultTime2Wait, 12557 DefaultTime2Retain); 12558 } 12559 } 12561 D.4. Connection Recovery Algorithms 12563 D.4.1. Procedure Descriptions 12565 Build-And-Send-Async(transport connection, reason code, 12566 minimum time, maximum time); 12567 Pick-A-Logged-In-Connection(session); 12568 Build-And-Send-Logout(transport connection, logout connection 12569 identifier, reason code); 12570 PerformImplicitLogout(transport connection, logout connection 12571 identifier, target information); 12573 PerformLogin(transport connection, target information); 12574 CreateNewTransportConnection(target information); 12575 Build-And-Send-Command(transport connection, task control 12576 block); 12577 Connection-Cleanup-Handler(transport connection); 12578 Connection-Resource-Timeout-Handler(transport connection); 12579 Quiesce-And-Prepare-for-New-Allegiance(session, task control 12580 block); 12581 Build-And-Send-Logout-Response(transport connection, 12582 CID of connection in recovery, reason 12583 code); 12584 Build-And-Send-TaskMgmt-Response(transport connection, 12585 task mgmt command PDU, response code); 12586 Establish-New-Allegiance(task control block, transport 12587 connection); 12588 Schedule-Command-To-Continue(task control block); 12590 Notes: 12591 - Transport exception conditions, such as unexpected 12592 connection termination, connection reset, and hung 12593 connection while the connection is in the full-feature 12594 phase, are all assumed to be asynchronously signaled to the 12595 iSCSI layer using the Transport_Exception_Handler procedure. 12597 D.4.2. Initiator Algorithms 12599 Receive-a-In-PDU(Connection, CurrentPDU) 12600 { 12601 check-basic-validity(CurrentPDU); 12602 if (Header-Digest-Bad) discard, return; 12603 Retrieve TCB from CurrentPDU.InitiatorTaskTag. 12604 if (CurrentPDU.type == Async) { 12605 if (CurrentPDU.AsyncEvent == ConnectionDropped) { 12606 Retrieve the AffectedConnection for 12607 CurrentPDU.Parameter1. 12608 AffectedConnection.CurrentTimeout = 12609 CurrentPDU.Parameter3; 12610 AffectedConnection.State = CLEANUP_WAIT; 12611 Start-Timer(Connection-Cleanup-Handler, 12612 AffectedConnection, 12613 CurrentPDU.Parameter2); 12614 } else if (CurrentPDU.AsyncEvent == LogoutRequest)) { 12615 AffectedConnection = Connection; 12616 AffectedConnection.State = LOGOUT_REQUESTED; 12617 AffectedConnection.PerformConnectionCleanup = TRUE; 12618 AffectedConnection.CurrentTimeout = 12619 CurrentPDU.Parameter3; 12620 Start-Timer(Connection-Cleanup-Handler, 12621 AffectedConnection, 0); 12622 } else if (CurrentPDU.AsyncEvent == SessionDropped)) { 12623 for (each Connection) { 12624 Connection.State = CLEANUP_WAIT; 12625 Connection.CurrentTimeout = CurrentPDU.Parameter3; 12626 Start-Timer(Connection-Cleanup-Handler, 12627 Connection, CurrentPDU.Parameter2); 12628 } 12629 Session.state = FAILED; 12630 } 12632 } else if (CurrentPDU.type == LogoutResponse) { 12633 Retrieve the CleanupConnection for CurrentPDU.CID. 12634 if (CurrentPDU.Response = failure) { 12635 CleanupConnection.State = CLEANUP_WAIT; 12636 } else { 12637 CleanupConnection.State = FREE; 12638 } 12639 } else if (CurrentPDU.type == LoginResponse) { 12640 if (this is a response to an implicit Logout) { 12641 Retrieve the CleanupConnection. 12642 if (successful) { 12643 CleanupConnection.State = FREE; 12644 Connection.State = LOGGED_IN; 12645 } else { 12646 CleanupConnection.State = CLEANUP_WAIT; 12647 DestroyTransportConnection(Connection); 12648 } 12649 } 12650 } else { /* REST UNRELATED TO CONNECTION-RECOVERY, 12651 * NOT SHOWN */ 12653 } 12654 if (CleanupConnection.State == FREE) { 12655 for (each command that was active on CleanupConnection) { 12656 /* Establish new connection allegiance */ 12657 NewConnection = Pick-A-Logged-In- 12658 Connection(Session); 12659 Build-And-Send-Command(NewConnection, TCB); 12660 } 12661 } 12662 } 12664 Connection-Cleanup-Handler(Connection) 12665 { 12666 Retrieve Session from Connection. 12667 if (Connection can still exchange iSCSI PDUs) { 12668 NewConnection = Connection; 12669 } else { 12670 Start-Timer(Connection-Resource-Timeout-Handler, 12671 Connection, Connection.CurrentTimeout); 12672 if (there are other logged-in connections) { 12673 NewConnection = Pick-A-Logged-In- 12674 Connection(Session); 12675 } else { 12676 NewConnection = 12678 CreateTransportConnection(Session.OtherEndInfo); 12679 Initiate an implicit Logout on NewConnection for 12680 Connection.CID. 12681 return; 12682 } 12683 } 12684 Build-And-Send-Logout(NewConnection, Connection.CID, 12685 RecoveryRemove); 12686 } 12688 Transport_Exception_Handler(Connection) 12689 { 12690 Connection.PerformConnectionCleanup = TRUE; 12691 if (the event is an unexpected transport disconnect) { 12692 Connection.State = CLEANUP_WAIT; 12693 Connection.CurrentTimeout = DefaultTime2Retain; 12694 Start-Timer(Connection-Cleanup-Handler, Connection, 12695 DefaultTime2Wait); 12697 } else { 12698 Connection.State = FREE; 12699 } 12700 } 12702 D.4.3. Target Algorithms 12704 Receive-a-In-PDU(Connection, CurrentPDU) 12705 { 12706 check-basic-validity(CurrentPDU); 12707 if (Header-Digest-Bad) discard, return; 12708 else if (Data-Digest-Bad) { 12709 Build-And-Send-Reject(Connection, CurrentPDU, 12710 Payload-Digest-Error); 12711 discard, return; 12712 } 12713 Retrieve TCB and Session. 12714 if (CurrentPDU.type == Logout) { 12715 if (CurrentPDU.ReasonCode = RecoveryRemove) { 12716 Retrieve the CleanupConnection from CurrentPDU.CID). 12717 for (each command active on CleanupConnection) { 12718 Quiesce-And-Prepare-for-New-Allegiance(Session, 12719 TCB); 12720 TCB.CurrentlyAllegiant = FALSE; 12721 } 12722 Cleanup-Connection-State(CleanupConnection); 12723 if ((quiescing successful) and (cleanup successful)) 12724 { 12725 Build-And-Send-Logout-Response(Connection, 12726 CleanupConnection.CID, 12727 Success); 12728 } else { 12729 Build-And-Send-Logout-Response(Connection, 12730 CleanupConnection.CID, 12731 Failure); 12732 } 12734 } 12735 } else if ((CurrentPDU.type == Login) and 12736 operational ErrorRecoveryLevel == 2) { 12737 Retrieve the CleanupConnection from CurrentPDU.CID). 12738 for (each command active on CleanupConnection) { 12739 Quiesce-And-Prepare-for-New-Allegiance(Session, 12740 TCB); 12741 TCB.CurrentlyAllegiant = FALSE; 12742 } 12743 Cleanup-Connection-State(CleanupConnection); 12744 if ((quiescing successful) and (cleanup successful)) 12745 { 12746 Continue with the rest of the Login processing; 12747 } else { 12748 Build-And-Send-Login-Response(Connection, 12749 CleanupConnection.CID, Target 12750 Error); 12751 } 12752 } 12753 } else if (CurrentPDU.type == TaskManagement) { 12754 if (CurrentPDU.function == "TaskReassign") { 12755 if (Session.ErrorRecoveryLevel < 2) { 12756 Build-And-Send-TaskMgmt-Response(Connection, 12757 CurrentPDU, "Allegiance reassignment 12758 not supported"); 12759 } else if (task is not found) { 12760 Build-And-Send-TaskMgmt-Response(Connection, 12761 CurrentPDU, "Task not in task set"); 12762 } else if (task is currently allegiant) { 12763 Build-And-Send-TaskMgmt-Response(Connection, 12764 CurrentPDU, "Task still allegiant"); 12765 } else { 12766 Establish-New-Allegiance(TCB, Connection); 12767 TCB.CurrentlyAllegiant = TRUE; 12768 Schedule-Command-To-Continue(TCB); 12769 } 12770 } 12771 } else { /* REST UNRELATED TO CONNECTION-RECOVERY, 12772 * NOT SHOWN */ 12773 } 12775 } 12777 Transport_Exception_Handler(Connection) 12778 { 12779 Connection.PerformConnectionCleanup = TRUE; 12780 if (the event is an unexpected transport disconnect) { 12781 Connection.State = CLEANUP_WAIT; 12782 Start-Timer(Connection-Resource-Timeout-Handler, 12783 Connection, 12785 (DefaultTime2Wait+DefaultTime2Retain)); 12786 if (this Session has full-feature phase connections 12787 left) { 12788 DifferentConnection = 12789 Pick-A-Logged-In-Connection(Session); 12790 Build-And-Send-Async(DifferentConnection, 12791 DroppedConnection, DefaultTime2Wait, 12792 DefaultTime2Retain); 12793 } 12794 } else { 12795 Connection.State = FREE; 12796 } 12797 } 12798 Appendix E. Clearing Effects of Various Events on Targets 12800 E.1. Clearing Effects on iSCSI Objects 12802 The following tables describe the target behavior on receiving the 12803 events specified in the rows of the table. The second table is 12804 an extension of the first table and defines clearing actions for 12805 more objects on the same events. The legend is: 12807 Y = Yes (cleared/discarded/reset on the event specified in 12808 the row). Unless otherwise noted, the clearing action is 12809 only applicable for the issuing initiator port. 12811 N = No (not affected on the event specified in the row, 12812 i.e., stays at previous value). 12814 NA = Not Applicable or Not Defined. 12816 +-----+-----+-----+-----+-----+ 12817 |IT(1)|IC(2)|CT(5)|ST(6)|PP(7)| 12818 +---------------------+-----+-----+-----+-----+-----+ 12819 |connection failure(8)|Y |Y |N |N |Y | 12820 +---------------------+-----+-----+-----+-----+-----+ 12821 |connection state |NA |NA |Y |N |NA | 12822 |timeout (9) | | | | | | 12823 +---------------------+-----+-----+-----+-----+-----+ 12824 |session timeout/ |Y |Y |Y |Y |Y(14)| 12825 |closure/reinstatement| | | | | | 12826 |(10) | | | | | | 12827 +---------------------+-----+-----+-----+-----+-----+ 12828 |session continuation |NA |NA |N(11)|N |NA | 12829 |(12) | | | | | | 12830 +---------------------+-----+-----+-----+-----+-----+ 12831 |successful connection|Y |Y |Y |N |Y(13)| 12832 |close logout | | | | | | 12833 +---------------------+-----+-----+-----+-----+-----+ 12834 |session failure (18) |Y |Y |N |N |Y | 12835 +---------------------+-----+-----+-----+-----+-----+ 12836 |successful recovery |Y |Y |N |N |Y(13)| 12837 |Logout | | | | | | 12838 +---------------------+-----+-----+-----+-----+-----+ 12839 |failed Logout |Y |Y |N |N |Y | 12840 +---------------------+-----+-----+-----+-----+-----+ 12841 |connection Login |NA |NA |NA |Y(15)|NA | 12842 |(leading) | | | | | | 12843 +---------------------+-----+-----+-----+-----+-----+ 12844 |connection Login |NA |NA |N(11)|N |Y | 12845 |(non-leading) | | | | | | 12846 +---------------------+-----+-----+-----+-----+-----+ 12847 |target cold reset(16)|Y(20)|Y |Y |Y |Y | 12848 +---------------------+-----+-----+-----+-----+-----+ 12849 |target warm reset(16)|Y(20)|Y |Y |Y |Y | 12850 +---------------------+-----+-----+-----+-----+-----+ 12851 |LU reset(19) |Y(20)|Y |Y |Y |Y | 12852 +---------------------+-----+-----+-----+-----+-----+ 12853 |powercycle(16) |Y |Y |Y |Y |Y | 12854 +---------------------+-----+-----+-----+-----+-----+ 12856 1. Incomplete TTTs - Target Transfer Tags on which the target is 12857 still expecting PDUs to be received. Examples include TTTs 12858 received via R2T, NOP-IN, etc. 12860 2. Immediate Commands - immediate commands, but waiting for 12861 execution on a target. For example, Abort Task Set. 12863 5. Connection Tasks - tasks that are active on the iSCSI connection 12864 in question. 12866 6. Session Tasks - tasks that are active on the entire iSCSI 12867 session. A union of "connection tasks" on all participating 12868 connections. 12870 7. Partial PDUs (if any) - PDUs that are partially sent and waiting 12871 for transport window credit to complete the transmission. 12873 8. Connection failure is a connection exception condition - one of 12874 the transport connections shutdown, transport connections 12875 reset, or transport connections timed out, which abruptly 12876 terminated the iSCSI full-feature phase connection. A 12877 connection failure always takes the connection state machine to 12878 the CLEANUP_WAIT state. 12880 9. Connection state timeout happens if a connection spends more 12881 time than agreed upon during Login negotiation in the 12882 CLEANUP_WAIT state, and this takes the connection to the FREE 12883 state (M1 transition in connection cleanup state diagram). 12885 10.These are defined in Section 6.3.5. 12887 11.This clearing effect is "Y" only if it is a connection 12888 reinstatement and the operational ErrorRecoveryLevel is less 12889 than 2. 12891 12.Session continuation is defined in Section 6.3.5. 12893 13.This clearing effect is only valid if the connection is being 12894 logged out on a different connection and when the connection 12895 being logged out on the target may have some partial PDUs 12896 pending to be sent. In all other cases, the effect is "NA". 12898 14.This clearing effect is only valid for a "close the session" 12899 logout in a multi-connection session. In all other cases, the 12900 effect is "NA". 12901 15.Only applicable if this leading connection login is a session 12902 reinstatement. If this is not the case, it is "NA". 12903 16.This operation affects all logged-in initiators. 12904 18.Session failure is defined in Section 6.3.5. 12905 19.This operation affects all logged-in initiators and the clearing 12906 effects are only applicable to the LU being reset. 12907 20.With Standard multi-task abort semantics (Section 4.2.3.3), a 12908 target warm reset or a target cold reset or an LU reset would 12909 clear the active TTTs upon completion. However, the FastAbort 12910 multi-task abort semantics defined by Section 4.2.3.4 do not 12911 guarantee that the active TTTs are cleared by the end of the 12912 reset operations. In fact, the FastAbort semantics are designed 12913 to allow clearing the TTTs in a "lazy" fashion after the TMF 12914 Response is delivered. Thus, when TaskReporting=FastAbort 12915 (Section 13.23) is operational on a session, the clearing 12916 effects of reset operations on "Incomplete TTTs" is "N". 12918 +-----+-----+-----+-----+-----+ 12919 |DC(1)|DD(2)|SS(3)|CS(4)|DS(5)| 12920 +---------------------+-----+-----+-----+-----+-----+ 12921 |connection failure |N |Y |N |N |N | 12922 +---------------------+-----+-----+-----+-----+-----+ 12923 |connection state |Y |NA |Y |N |NA | 12924 |timeout | | | | | | 12925 +---------------------+-----+-----+-----+-----+-----+ 12926 |session timeout/ |Y |Y |Y(7) |Y |NA | 12927 |closure/reinstatement| | | | | | 12928 +---------------------+-----+-----+-----+-----+-----+ 12929 |session continuation |N(11)|NA*12|NA |N |NA*13| 12930 +---------------------+-----+-----+-----+-----+-----+ 12931 |successful connection|Y |Y |Y |N |NA | 12932 |close Logout | | | | | | 12933 +---------------------+-----+-----+-----+-----+-----+ 12934 |session failure |N |Y |N |N |N | 12935 +---------------------+-----+-----+-----+-----+-----+ 12936 |successful recovery |Y |Y |Y |N |N | 12937 |Logout | | | | | | 12938 +---------------------+-----+-----+-----+-----+-----+ 12939 |failed Logout |N |Y(9) |N |N |N | 12940 +---------------------+-----+-----+-----+-----+-----+ 12941 |connection Login |NA |NA |N(8) |N(8) |NA | 12942 |(leading | | | | | | 12943 +---------------------+-----+-----+-----+-----+-----+ 12944 |connection Login |N(11)|NA*12|N(8) |N |NA*13| 12945 |(non-leading) | | | | | | 12946 +---------------------+-----+-----+-----+-----+-----+ 12947 |target cold reset |Y |Y |Y |Y(10)|NA | 12948 +---------------------+-----+-----+-----+-----+-----+ 12949 |target warm reset |Y |Y |N |N |NA | 12950 +---------------------+-----+-----+-----+-----+-----+ 12951 |LU reset |N |Y |N |N |N | 12952 +---------------------+-----+-----+-----+-----+-----+ 12953 |powercycle |Y |Y |Y |Y(10)|NA | 12954 +---------------------+-----+-----+-----+-----+-----+ 12956 1. Discontiguous Commands - commands allegiant to the connection 12957 in question and waiting to be reordered in the iSCSI layer. All 12958 "Y"s in this column assume that the task causing the event (if 12959 indeed the event is the result of a task) is issued as an 12960 immediate command, because the discontiguities can be ahead of the 12961 task. 12963 2. Discontiguous Data - data PDUs received for the task in 12964 question and waiting to be reordered due to prior discontiguities 12965 in DataSN. 12967 3. StatSN 12969 4. CmdSN 12971 5. DataSN 12973 7. It clears the StatSN on all the connections. 12975 8. This sequence number is instantiated on this event. 12977 9. A logout failure drives the connection state machine to the 12978 CLEANUP_WAIT state, similar to the connection failure event. 12979 Hence, it has a similar effect on this and several other protocol 12980 aspects. 12982 10. This is cleared by virtue of the fact that all sessions with 12983 all initiators are terminated. 12985 11. This clearing effect is "Y" if it is a connection 12986 reinstatement. 12988 12. This clearing effect is "Y" only if it is a connection 12989 reinstatement and the operational ErrorRecoveryLevel is 2. 12991 13. This clearing effect is "N" only if it is a connection 12992 reinstatement and the operational ErrorRecoveryLevel is 2. 12994 E.2. Clearing Effects on SCSI Objects 12996 The only iSCSI protocol action that can effect clearing actions on 12997 SCSI objects is the "I_T nexus loss" notification (Section 6.3.5.1 12998 Loss of Nexus notification). [SPC3] describes the clearing effects 12999 of this notification on a variety of SCSI attributes. In addition, 13000 SCSI standards documents (such as [SAM2] and [SBC2]) define 13001 additional clearing actions that may take place for several SCSI 13002 objects on SCSI events such as LU resets and power-on resets. 13004 Since iSCSI defines a target cold reset as a protocol-equivalent 13005 to a target power-cycle, the iSCSI target cold reset must also be 13006 considered as the power-on reset event in interpreting the actions 13007 defined in the SCSI standards. 13009 When the iSCSI session is reconstructed (between the same SCSI 13010 ports with the same nexus identifier) reestablishing the same I_T 13011 nexus, all SCSI objects that are defined to not clear on the "I_T 13012 nexus loss" notification event, such as persistent reservations, 13013 are automatically associated to this new session. 13015 Acknowledgments 13017 Several individuals on the original IPS Working Group made 13018 significant contributions to the original RFCs 3720, 3980, 4850 13019 and 5048. 13021 Specifically, the authors of the original RFCs - which this draft 13022 consolidates into a single document - were the following: 13024 RFC 3720: Julian Satran, Kalman Meth, Costa Sapuntzakis, 13025 Mallikarjun Chadalapaka, Efri Zeidner 13027 RFC 3980: Marjorie Krueger, Mallikarjun Chadalapaka, Rob Elliott 13029 RFC 4850: David Wysochanski 13031 RFC 5048: Mallikarjun Chadalapaka 13033 Many thanks to Fred Knight for contributing to the UML notations 13034 and drawings in this draft. 13036 We would in addition like to acknowledge the following individuals 13037 who contributed to this revised draft: David Harrington, Paul 13038 Koning, Mark Edwards, Rob Elliott, Martin Stiemerling. 13040 Thanks to Yi Zeng and Nico Williams for suggesting and/or 13041 reviewing Kerberos-related security considerations text. 13043 The authors gratefully acknowledge the valuable feedback during 13044 the Last call review process from a number of individuals, which 13045 had significantly improved this draft. The individuals were: 13046 Stephen Farrell, Brian Haberman, Barry Leiba, Pete Resnick, Sean 13047 Turner, Alexey Melnikov, Kathleen Moriarty, Fred Knight, Mike 13048 Christie, Qiang Wang, Shiv Rajpal and Andy Banta. 13050 Finally, this draft also benefited from significant review 13051 contributions from the Storm Working Group at large. 13053 Authors' Addresses 13055 Mallikarjun Chadalapaka 13056 Microsoft 13057 One Microsoft Way 13058 Redmond WA 98052 USA 13059 E-mail: cbm@chadalapaka.com 13061 Julian Satran 13062 Infinidat Ltd. 13063 E-mail: julians@infinidat.com, julian@satran.net 13065 Kalman Meth 13066 IBM Haifa Research Lab 13067 Haifa University Campus - Mount Carmel 13068 Haifa 31905, Israel 13069 Phone +972.4.829.6341 13070 E-mail: meth@il.ibm.com 13072 David L. Black, 13073 EMC Corporation, 13074 176 South St., Hopkinton, MA 01748 13075 Phone +1 (508) 293-7953 13076 Email: david.black@emc.com 13078 Comments may be sent to Mallikarjun Chadalapaka 13080 Acknowledgement 13082 Funding for the RFC Editor function is currently provided by the 13083 Internet Society