idnits 2.17.1 draft-ietf-ips-iscsi-impl-guide-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 15. -- Found old boilerplate from RFC 3978, Section 5.5 on line 485. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 497. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 505. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 511. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? == There are 3 instances of lines with non-ascii characters in the document. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 3 characters in excess of 72. -- The abstract seems to indicate that this document updates RFC3720, but the header doesn't have an 'Updates:' line to match this. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 336 has weird spacing: '... of large...' == Line 491 has weird spacing: '... be clai...' == Line 500 has weird spacing: '... any ass...' == Line 501 has weird spacing: '...t of an atte...' == Line 503 has weird spacing: '...of this spec...' == (3 more instances...) == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (January 2006) is 6674 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFC 3720' is mentioned on line 205, but not defined ** Obsolete undefined reference: RFC 3720 (Obsoleted by RFC 7143) == Unused Reference: 'RFC2119' is defined on line 441, but no explicit reference was found in the text == Unused Reference: 'SAM' is defined on line 444, but no explicit reference was found in the text ** Obsolete normative reference: RFC 3720 (Obsoleted by RFC 7143) -- Possible downref: Non-RFC (?) normative reference: ref. 'SPC3' Summary: 7 errors (**), 0 flaws (~~), 13 warnings (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET DRAFT Mallikarjun Chadalapaka 3 draft-ietf-ips-iscsi-impl-guide-00.txt Hewlett-Packard Co. 4 Editor 6 Expires January 2006 8 iSCSI Implementer's Guide 10 Status of this Memo 11 By submitting this Internet-Draft, each author represents 12 that any applicable patent or other IPR claims of which he or 13 she is aware have been or will be disclosed, and any of which 14 he or she becomes aware will be disclosed, in accordance with 15 Section 6 of BCP 79. 17 Internet-Drafts are working documents of the Internet 18 Engineering Task Force (IETF), its areas, and its working 19 groups. Note that other groups may also distribute working 20 documents as Internet-Drafts. 22 Internet-Drafts are draft documents valid for a maximum of 23 six months and may be updated, replaced, or obsoleted by 24 other documents at any time. It is inappropriate to use 25 Internet-Drafts as reference material or to cite them other 26 than a "work in progress." 28 The list of current Internet-Drafts can be accessed at 29 http://www.ietf.org/1id-abstracts.html 31 The list of Internet-Draft Shadow Directories can be accessed 32 at http://www.ietf.org/shadow.html. 34 Abstract 35 iSCSI is a SCSI transport protocol and maps the SCSI family 36 of application protocols onto TCP/IP. RFC 3720 defines the 37 iSCSI protocol. This document compiles the clarifications to 38 the original protocol definition in RFC 3720 to serve as a 39 companion document for the iSCSI implementers. This document 40 updates RFC 3720 and the text in this document supersedes the 41 text in RFC 3720 when the two differ. 43 Table of Contents 45 1 Definitions and acronyms ...............................3 46 1.1 Definitions ............................................3 47 1.2 Acronyms ...............................................3 48 2 Introduction ...........................................5 49 3 iSCSI semantics for SCSI tasks .........................6 50 3.1 SCSI REPORT LUNS and Residual Overflow .................6 51 4 Task Management ........................................8 52 4.1 Requests Affecting Multiple Tasks ......................8 53 4.1.1 Scope of affected tasks...............................8 54 4.1.2 Updated semantics.....................................8 55 4.1.3 Rationale behind the new semantics....................9 56 5 iSCSI Error Handling and Recovery .....................11 57 5.1 ITT ...................................................11 58 5.2 Format Errors .........................................11 59 5.3 Digest Errors .........................................11 60 6 Security Considerations ...............................13 61 7 IANA Considerations ...................................14 62 8 References and Bibliography ...........................15 63 8.1 Normative References ..................................15 64 8.2 Informative References ................................15 65 9 Editor's Address ......................................16 66 10 Acknowledgements ......................................17 67 11 Full Copyright Statement ..............................18 68 12 Intellectual Property Statement .......................19 70 1 Definitions and acronyms 72 1.1 Definitions 74 I/O Buffer � A buffer that is used in a SCSI Read or Write 75 operation so SCSI data may be sent from or received into 76 that buffer. 78 1.2 Acronyms 80 Acronym Definition 82 ------------------------------------------------------------- 84 EDTL Expected Data Transfer Length 86 IANA Internet Assigned Numbers Authority 88 IETF Internet Engineering Task Force 90 I/O Input - Output 92 IP Internet Protocol 94 iSCSI Internet SCSI 96 iSER iSCSI Extensions for RDMA 98 ITT Initiator Task Tag 100 LO Leading Only 102 LU Logical Unit 104 LUN Logical Unit Number 106 PDU Protocol Data Unit 108 RDMA Remote Direct Memory Access 110 R2T Ready To Transfer 112 R2TSN Ready To Transfer Sequence Number 114 RFC Request For Comments 116 SAM SCSI Architecture Model 118 SCSI Small Computer Systems Interface 120 SN Sequence Number 122 SNACK Selective Negative Acknowledgment - also 124 Sequence Number Acknowledgement for data 126 TCP Transmission Control Protocol 128 TMF Task Management Function 130 TTT Target Transfer Tag 132 2 Introduction 134 Several iSCSI implementations had been built after [RFC3720] was 135 published and the iSCSI community is now richer by the resulting 136 implementation expertise. The goal of this document is to 137 leverage this expertise both to offer clarifications to the 138 [RFC3720] semantics and to address defects in [RFC3720] as 139 appropriate. This document intends to offer critical guidance 140 to implementers with regard to non-obvious iSCSI implementation 141 aspects so as to improve interoperability and accelerate iSCSI 142 adoption. This document, however, does not purport to be an 143 all-encompassing iSCSI how-to guide for implementers, nor a 144 complete revision of [RFC3720]. This document instead is 145 intended as a companion document to [RFC3720] for the iSCSI 146 implementers. 148 iSCSI implementers are required to reference [RFC3722] and 149 [RFC3723] in addition to [RFC3720] for mandatory requirements. 150 In addition, [RFC3721] also contains useful information for 151 iSCSI implementers. The text in this document, however, updates 152 and supersedes the text in all the noted RFCs whenever there is 153 such a question. 155 3 iSCSI semantics for SCSI tasks 157 3.1 SCSI REPORT LUNS and Residual Overflow 159 The specification of the SCSI REPORT LUNS command requires that 160 SCSI target limit the amount of data transferred to a maximum 161 size (ALLOCATION LENGTH) provided by the initiator in the REPORT 162 LUNS CDB. If the Expected Data Transfer Length (EDTL) in the 163 iSCSI header of the SCSI Command PDU for a REPORT LUNS command 164 is set to at least as large as that ALLOCATION LENGTH, the SCSI 165 layer truncation prevents an iSCSI Residual Overflow from 166 occurring. A SCSI initiator can detect that such truncation has 167 occurred via other information at the SCSI layer. The rest of 168 the section elaborates this required behavior. 170 iSCSI uses the (O) bit (bit 5) in the Flags field of the SCSI 171 Response and SCSI Data-Out PDUs to indicate that that an iSCSI 172 target was unable to transfer all of the SCSI data for a command 173 to the initiator because the amount of data to be transferred 174 exceeded the EDTL in the corresponding SCSI Command PDU (see 175 Section 10.4.1 of [RFC 3720]). 177 The SCSI REPORT LUNS command requests a target SCSI layer to 178 return a logical unit inventory (LUN list) to the initiator SCSI 179 layer (see section 6.21 of SPC-3 [SPC3]). The size of this LUN 180 list may not be known to the initiator SCSI layer when it issues 181 the REPORT LUNS command; to avoid transfer of more LUN list data 182 than the initiator is prepared for, the REPORT LUNS CDB contains 183 an ALLOCATION LENGTH field to specify the maximum amount of data 184 to be transferred to the initiator for this command. If the 185 initiator SCSI layer has under-estimated the number of logical 186 units at the target, it is possible that the complete logical 187 unit inventory does not fit in the specified ALLOCATION LENGTH. 188 In this situation, section 4.3.3.6 in [SPC3] requires that the 189 target SCSI layer "shall terminate transfers to the Data-In 190 Buffer" when the number of bytes specified by the ALLOCATION 191 LENGTH field have been transferred. 193 Therefore, in response to a REPORT LUNS command, the SCSI layer 194 at the target presents at most ALLOCATION LENGTH bytes of data 195 (logical unit inventory) to iSCSI for transfer to the initiator. 196 For a REPORT LUNS command, if the iSCSI EDTL is at least as 197 large as the ALLOCATION LENGTH, the SCSI truncation ensures that 198 the EDTL will accommodate all of the data to be transferred. If 199 all of the logical unit inventory data presented to the iSCSI 200 layer � i.e. the data remaining after any SCSI truncation - is 201 transferred to the initiator by the iSCSI layer, an iSCSI 202 Residual Overflow has not occurred and the iSCSI (O) bit MUST 203 NOT be set in the SCSI Response or final SCSI Data-Out PDU. 204 This is not a new requirement but is already required by the 205 combination of [RFC 3720] with the specification of the REPORT 206 LUNS command in [SPC3]. 208 The LUN LIST LENGTH field in the logical unit inventory (first 209 field in the inventory) is not affected by truncation of the 210 inventory to fit in ALLOCATION LENGTH; this enables a SCSI 211 initiator to determine that the received inventory is incomplete 212 by noticing that the LUN LIST LENGTH in the inventory is larger 213 than the ALLOCATION LENGTH that was sent in the REPORT LUNS CDB. 214 A common initiator behavior in this situation is to re-issue the 215 REPORT LUNS command with a larger ALLOCATION LENGTH. 217 4 Task Management 219 4.1 Requests Affecting Multiple Tasks 221 This section updates the original text in section 10.6.2 of 222 [RFC3720]. The clarified semantics are a superset of the 223 semantics of the original text in it the new text covers all 224 TMFs that can impact multiple tasks. 226 4.1.1 Scope of affected tasks 228 ABORT TASK SET: All outstanding tasks for the I_T_L nexus 229 identified by the LUN field in the ABORT TASK SET TMF 230 Request PDU. 231 CLEAR TASK SET: All outstanding tasks in the task set for 232 the LU identified by the LUN field in the CLEAR TASK SET 233 TMF Request PDU. See [SPC3] for the definition of a "task 234 set". 236 LOGICAL UNIT RESET: All outstanding tasks from all 237 initiators for the LU identified by the LUN field in the 238 LOGICAL UNIT RESET Request PDU. 240 TARGET WARM RESET/TARGET COLD RESET: All outstanding tasks 241 from all initiators across all LUs that the TMF-issuing 242 session has access to on the SCSI target device hosting the 243 iSCSI session. 245 Usage example: an "ABORT TASK SET TMF Request PDU" in the 246 preceding text is an iSCSI TMF Request PDU with the "Function" 247 field set to "ABORT TASK SET" as defined in [RFC3720]. Similar 248 usage is employed for other descriptions. 250 4.1.2 Updated semantics 252 The execution of ABORT TASK SET, CLEAR TASK SET, LOGICAL UNIT 253 RESET, TARGET WARM RESET, and TARGET COLD RESET TMF Requests 254 consists of the following sequence of actions in the specified 255 order on each of the entities. 257 The initiator: 259 a) Issues ABORT TASK SET/CLEAR TASK SET/LOGICAL UNIT 260 RESET/TARGET WARM RESET/TARGET COLD RESET request. 262 b) Continues to respond to each TTT received for the affected 263 tasks. 265 c) Receives any responses that the target may provide for some 266 tasks among the affected tasks (may process them as usual 267 because they are guaranteed to be valid). 269 d) Receives the task management response concluding all the 270 tasks in the set of affected tasks. 272 The Target: 274 a) Receives the ABORT TASK SET/CLEAR TASK SET/LOGICAL UNIT 275 RESET/TARGET WARM RESET/TARGET COLD RESET request. 277 b) Waits for all currently valid target transfer tags of the 278 affected tasks to be responded. 280 c) Based on the CmdSN ordering, waits (concurrent with the 281 wait in step (b)) for all commands of the affected tasks to 282 be received. In the case of target-scoped requests (i.e. 283 TARGET WARM RESET and TARGET COLD RESET), all the commands 284 that are not received, as at the end of step (b), in the 285 command stream however can be considered to have been 286 received with no command waiting period - i.e. the entire 287 CmdSN space upto the CmdSN of the task management function 288 can be "plugged" (refer section 6.9 on how aborting a 289 specific task can implicitly plug the CmdSN of the task 290 being aborted) at the end of step (b). 292 d) Propagates the TMF request to and receives the response 293 from the target SCSI layer. 295 e) Takes note of last-sent StatSN on each of the connections 296 in the iSCSI session(s) (one or more) sharing the affected 297 tasks, and waits for acknowledgement of each StatSN (may 298 solicit for acknowledgement by way of a NOP-In). If some 299 tasks originate from non-iSCSI I_T_L nexuses then the means 300 by which the target insures that all affected tasks have 301 returned their status to the initiator are defined by the 302 specific non-iSCSI transport protocol(s). 304 f) Sends the task set management response to the issuing 305 initiator. 307 4.1.3 Rationale behind the new semantics 309 There are fundamentally three basic objectives behind the 310 semantics specified in section 4.1.2. 312 1. Maintaining an ordered command flow I_T nexus abstraction 313 to the target SCSI layer even with multi-connection 314 sessions. 316 o Target iSCSI processing of a TMF request must maintain 317 the single flow illusion - steps c & d of the target 318 behavior correspond to this objective. 320 2. Maintaining a single ordered response flow I_T nexus 321 abstraction to the initiator SCSI layer even with multi- 322 connection sessions. 324 o Target must ensure that the initiator does not see 325 "old" task responses (that were placed on the wire 326 chronologically earlier than the TMF response) after 327 seeing the TMF response - step e of the target 328 behavior corresponds to this objective. 330 3. Draining all active TTTs corresponding to affected tasks 331 before the TMF is acted on. 333 o Targets are better off if the TTTs are 334 deterministically retired before the affected tasks 335 are terminated because that eliminates the possibility 336 of large-sized Data-out PDUs with stale TTTs arriving 337 after the tasks are terminated. Step b of the target 338 behavior corresponds to this objective. 340 The only other notable thing in step c of the target behavior is 341 the "plugging" part - it is an optimization that says if all 342 tasks on the I_T nexus will be aborted anyway (as with a target 343 reset), there is no need to wait, the target can simply plug all 344 missing CmdSN slots and move on with TMF processing. The first 345 objective (maintaining a single ordered command flow) is still 346 met with this optimization because target SCSI layer only sees 347 ordered commands. 349 5 iSCSI Error Handling and Recovery 351 5.1 ITT 353 Section 10.19 in [RFC3720] mentions this in passing but noted 354 here again for making it obvious. An ITT value of 0xffffffff is 355 reserved and MUST NOT be used by the initiator. The only 356 instance it may be seen on the wire is in a target-initiated 357 NOP-In PDU (and the initiator response to that PDU if 358 necessary). 360 5.2 Format Errors 362 Section 6.6 of [RFC3720] discusses format error handling. This 363 section elaborates on the "inconsistent" PDU field contents 364 noted in [RFC3720]. 366 All initiator-detected PDU construction errors MUST be 367 considered as format errors. Some examples of such errors are: 369 - NOP-In with a valid TTT but an invalid LUN 371 - NOP-In with a valid ITT (i.e. a NOP-In response) and also a 372 valid TTT 374 - SCSI Response PDU with Status=CHECK CONDITION, but 375 DataSegmentLength = 0 377 5.3 Digest Errors 379 Section 6.7 of [RFC3720] discusses digest error handling. It 380 states that "No further action is necessary for initiators if the discarded 381 PDU is an unsolicited PDU (e.g., Async, Reject)" on detecting a 382 payload digest error. This is incorrect. 384 An Asynchronous Message PDU or a Reject PDU carries the next 385 StatSN value on an iSCSI connection, advancing the StatSN. When 386 an initiator discards one of these PDUs due to a payload digest 387 error, the entire PDU including the header MUST be discarded. 388 Consequently, the initiator MUST treat the exception like a loss 389 of any other solicited response PDU � i.e. it MUST use one of 390 the following options noted in [RFC3720]: 392 a) Request PDU retransmission with a status SNACK. 394 b) Logout the connection for recovery and continue the 395 tasks on a different connection instance. 397 c) Logout to close the connection (abort all the commands 398 associated with the connection). 400 6 Security Considerations 402 This document does not introduce any new security considerations 403 other than those already noted in [RFC3720]. Consequently, all 404 the iSCSI-related security text in [RFC3723] is also directly 405 applicable to this document. 407 7 IANA Considerations 409 This draft does not have any specific IANA considerations other 410 than those already noted in [RFC3720]. 412 8 References and Bibliography 414 8.1 Normative References 416 [RFC3720] Satran, J., Meth, K., Sapuntzakis, C., Chadalapaka, 417 M., and E. Zeidner, "Internet Small Computer Systems 418 Interface (iSCSI)", RFC 3720, April 2004. 420 [RFC3722] Bakke, M., "String Profile for Internet Small 421 Computer Systems Interface (iSCSI) Names", RFC 3722, April 422 2004. 424 [RFC3723] Aboba, B., Tseng, J., Walker, J., Rangan, V., and 425 F. Travostino, "Securing Block Storage Protocols over IP", 426 RFC 3723, April 2004. 428 [SPC3] T10/1416-D, SCSI Primary Commands-3. 430 8.2 Informative References 432 [RFC3721] Bakke, M., Hafner, J., Hufferd, J., Voruganti, K., 433 and M. Krueger, "Internet Small Computer Systems Interface 434 (iSCSI) Naming and Discovery", RFC 3721, April 2004. 436 [iSER] Ko, M., Chadalapaka, M., Elzur, U., Shah, H., Thaler, 437 P., J. Hufferd, "iSCSI Extensions for RDMA", IETF 438 Internet Draft draft-ietf-ips-iser-04.txt (work in 439 progress), June 2005. 441 [RFC2119] Bradner, S. "Key Words for use in RFCs to Indicate 442 Requirement Levels", BCP 14, RFC 2119, March 1997. 444 [SAM] ANSI X3.270-1998, SCSI-3 Architecture Model (SAM). 446 9 Editor's Address 448 Mallikarjun Chadalapaka 449 Hewlett-Packard Company 450 8000 Foothills Blvd. 451 Roseville, CA 95747-5668, USA 452 Phone: +1-916-785-5621 453 E-mail: cbm@rose.hp.com 455 10 Acknowledgements 457 The IP Storage (ips) Working Group in the Transport Area of 458 IETF has been responsible for defining the iSCSI protocol 459 (apart from a host of other relevant IP Storage protocols). 460 The editor acknowledges the contributions of the entire 461 working group. 463 The following individuals directly contributed to identifying 464 [RFC3720] issues and/or suggesting resolutions to the issues 465 clarified in this document: David Black (REPORT LUNS/overflow 466 semantics), Gwendal Grignou (TMF scope), Mike Ko (digest 467 error handling for Asynchronous Message), Dmitry Fomichev 468 (reserved ITT). This document benefited from all these 469 contributions. 471 11 Full Copyright Statement 473 Copyright (C) The Internet Society (2005). This document is 474 subject to the rights, licenses and restrictions contained in 475 BCP 78, and except as set forth therein, the authors retain 476 all their rights. 478 This document and the information contained herein are 479 provided on an "AS IS" basis and THE CONTRIBUTOR, THE 480 ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), 481 THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE 482 DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT 483 NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 484 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES 485 OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 487 12 Intellectual Property Statement 489 The IETF takes no position regarding the validity or scope of 490 any Intellectual Property Rights or other rights that might 491 be claimed to pertain to the implementation or use of the 492 technology described in this document or the extent to which 493 any license under such rights might or might not be 494 available; nor does it represent that it has made any 495 independent effort to identify any such rights. Information 496 on the procedures with respect to rights in RFC documents can 497 be found in BCP 78 and BCP 79. 499 Copies of IPR disclosures made to the IETF Secretariat and 500 any assurances of licenses to be made available, or the 501 result of an attempt made to obtain a general license or 502 permission for the use of such proprietary rights by 503 implementers or users of this specification can be obtained 504 from the IETF on-line IPR repository at 505 http://www.ietf.org/ipr. 507 The IETF invites any interested party to bring to its 508 attention any copyrights, patents or patent applications, 509 or other proprietary rights that may cover technology that 510 may be required to implement this standard. Please address 511 the information to the IETF at ietf-ipr@ietf.org.