RFC 7143
Internet Small Computer System Interface (iSCSI) Protocol (Consolidated)
RFC 7143: Internet Small Computer System Interface (iSCSI) Protocol (Consolidated) 🎀
Bestie, let's get the title block tea first 💖
- Number and title: RFC 7143, the Internet Small Computer System Interface (iSCSI) Protocol (Consolidated) ✨
- Authors: M. Chadalapaka (Microsoft), J. Satran (Infinidat Ltd.), K. Meth (IBM), and D. Black (EMC) 👑
- Category: Standards Track 🧚 (ISSN: 2070-1721)
- Date: April 2014 📅
- Obsoletes: RFCs 3720, 3980, 4850, and 5048 💅
- Updates: RFC 3721 🦋
Abstract ✨
Okay so this doc describes a transport protocol for SCSI that runs on top of TCP 🚀 The iSCSI protocol is aiming to be fully compliant with the standardized SCSI Architecture Model (SAM-2), no cap 💅
Quick backstory 🌸 RFC 3720 was the original iSCSI protocol. RFC 3721 covers iSCSI naming examples and discovery techniques. Then RFC 3980 added an extra naming format, and RFC 4850 added a new public extension key to iSCSI. RFC 5048 brought a bunch of clarifications, plus some improvements and corrections to the original protocol 😭
Now the glow-up 💜 This document obsoletes RFCs 3720, 3980, 4850, and 5048 by squishing them into one consolidated doc and making extra updates to that spec ✨ It also updates RFC 3721. Wherever there's a difference in semantics, the text in this document supersedes the text in all the noted RFCs. Main character energy, periodt 👑
Status of This Memo 📜
This one is on the Internet Standards Track, so it's officially official 🫶
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). If you want more info on Internet Standards, check out Section 2 of RFC 5741 🧚
For the current status of this document, any errata, and how to give feedback on it, head to http://www.rfc-editor.org/info/rfc7143 🌈
Copyright Notice ©
Copyright (c) 2014 IETF Trust and the persons identified as the document authors. All rights reserved. 💅
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as in effect on the date of publication of this document. Please read these documents carefully, bestie, because they spell out your rights and restrictions with respect to this document 🙈
Code components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they are provided without warranty as described in the Simplified BSD License. Don't skip this part 💀
Table of Contents 📚
1. Introduction ...................................................11
2. Acronyms, Definitions, and Document Summary ....................11
2.1. Acronyms ..................................................11
2.2. Definitions ...............................................13
2.3. Summary of Changes ........................................19
2.4. Conventions ...............................................20
3. UML Conventions ................................................20
3.1. UML Conventions Overview ..................................20
3.2. Multiplicity Notion .......................................21
3.3. Class Diagram Conventions .................................22
3.4. Class Diagram Notation for Associations ...................23
3.5. Class Diagram Notation for Aggregations ...................24
3.6. Class Diagram Notation for Generalizations ................25
4. Overview .......................................................25
4.1. SCSI Concepts .............................................25
4.2. iSCSI Concepts and Functional Overview ....................26
4.2.1. Layers and Sessions ................................27
4.2.2. Ordering and iSCSI Numbering .......................28
4.2.2.1. Command Numbering and Acknowledging .......28
4.2.2.2. Response/Status Numbering and
Acknowledging .............................32
4.2.2.3. Response Ordering .........................32
4.2.2.3.1. Need for Response Ordering .....32
4.2.2.3.2. Response Ordering Model
Description ....................33
4.2.2.3.3. iSCSI Semantics with
the Interface Model ............33
4.2.2.3.4. Current List of Fenced
Response Use Cases .............34
4.2.2.4. Data Sequencing ...........................35
4.2.3. iSCSI Task Management ..............................36
4.2.3.1. Task Management Overview ..................36
4.2.3.2. Notion of Affected Tasks ..................36
4.2.3.3. Standard Multi-Task Abort Semantics .......37
4.2.3.4. FastAbort Multi-Task Abort Semantics ......38
4.2.3.5. Affected Tasks Shared across
Standard and FastAbort Sessions ...........40
4.2.3.6. Rationale behind the FastAbort Semantics ..41
4.2.4. iSCSI Login ........................................42
4.2.5. iSCSI Full Feature Phase ...........................44
4.2.5.1. Command Connection Allegiance .............44
4.2.5.2. Data Transfer Overview ....................45
4.2.5.3. Tags and Integrity Checks .................46
4.2.5.4. SCSI Task Management during iSCSI
Full Feature Phase ........................47
4.2.6. iSCSI Connection Termination .......................47
4.2.7. iSCSI Names ........................................47
4.2.7.1. iSCSI Name Properties .....................48
4.2.7.2. iSCSI Name Encoding .......................50
4.2.7.3. iSCSI Name Structure ......................51
4.2.7.4. Type "iqn." (iSCSI Qualified Name) ........52
4.2.7.5. Type "eui." (IEEE EUI-64 Format) ..........53
4.2.7.6. Type "naa." (Network Address Authority) ...54
4.2.8. Persistent State ...................................55
4.2.9. Message Synchronization and Steering ...............55
4.2.9.1. Sync/Steering and iSCSI PDU Length ........56
4.3. iSCSI Session Types .......................................56
4.4. SCSI-to-iSCSI Concepts Mapping Model ......................57
4.4.1. iSCSI Architecture Model ...........................58
4.4.2. SCSI Architecture Model ............................59
4.4.3. Consequences of the Model ..........................61
4.4.3.1. I_T Nexus State ...........................62
4.4.3.2. Reservations ..............................63
4.5. iSCSI UML Model ...........................................64
4.6. Request/Response Summary ..................................66
4.6.1. Request/Response Types Carrying SCSI Payload .......66
4.6.1.1. SCSI Command ..............................66
4.6.1.2. SCSI Response .............................66
4.6.1.3. Task Management Function Request ..........67
4.6.1.4. Task Management Function Response .........68
4.6.1.5. SCSI Data-Out and SCSI Data-In ............68
4.6.1.6. Ready To Transfer (R2T) ...................69
4.6.2. Requests/Responses Carrying SCSI and iSCSI
Payload ............................................69
4.6.2.1. Asynchronous Message ......................69
4.6.3. Requests/Responses Carrying iSCSI-Only Payload .....69
4.6.3.1. Text Requests and Text Responses ..........69
4.6.3.2. Login Requests and Login Responses ........70
4.6.3.3. Logout Requests and Logout Responses ......71
4.6.3.4. SNACK Request .............................71
4.6.3.5. Reject ....................................71
4.6.3.6. NOP-Out Request and NOP-In Response .......71
5. SCSI Mode Parameters for iSCSI .................................72
6. Login and Full Feature Phase Negotiation .......................72
6.1. Text Format ...............................................73
6.2. Text Mode Negotiation .....................................76
6.2.1. List Negotiations ..................................80
6.2.2. Simple-Value Negotiations ..........................80
6.3. Login Phase ...............................................81
6.3.1. Login Phase Start ..................................84
6.3.2. iSCSI Security Negotiation .........................87
6.3.3. Operational Parameter Negotiation during
the Login Phase ....................................87
6.3.4. Connection Reinstatement ...........................88
6.3.5. Session Reinstatement, Closure, and Timeout ........89
6.3.5.1. Loss of Nexus Notification ................90
6.3.6. Session Continuation and Failure ...................90
6.4. Operational Parameter Negotiation outside the
Login Phase ...............................................90
7. iSCSI Error Handling and Recovery ..............................92
7.1. Overview ..................................................92
7.1.1. Background .........................................92
7.1.2. Goals ..............................................92
7.1.3. Protocol Features and State Expectations ...........93
7.1.4. Recovery Classes ...................................94
7.1.4.1. Recovery Within-command ...................95
7.1.4.2. Recovery Within-connection ................96
7.1.4.3. Connection Recovery .......................96
7.1.4.4. Session Recovery ..........................97
7.1.5. Error Recovery Hierarchy ...........................97
7.2. Retry and Reassign in Recovery ............................99
7.2.1. Usage of Retry .....................................99
7.2.2. Allegiance Reassignment ...........................100
7.3. Usage of Reject PDU in Recovery ..........................101
7.4. Error Recovery Considerations for Discovery Sessions .....102
7.4.1. ErrorRecoveryLevel for Discovery Sessions .........102
7.4.2. Reinstatement Semantics for Discovery Sessions ....102
7.4.2.1. Unnamed Discovery Sessions ...............103
7.4.2.2. Named Discovery Sessions .................103
7.4.3. Target PDUs during Discovery ......................103okay the table of contents is STILL going bestie 😭 💅 here's the rest of the lineup ✨
7.5. Connection Timeout Management ............................104
7.5.1. Timeouts on Transport Exception Events ............104
7.5.2. Timeouts on Planned Decommissioning ...............104
7.6. Implicit Termination of Tasks ............................104
7.7. Format Errors ............................................105
7.8. Digest Errors ............................................106
7.9. Sequence Errors ..........................................107
7.10. Message Error Checking ..................................108
7.11. SCSI Timeouts ...........................................108
7.12. Negotiation Failures ....................................109
7.13. Protocol Errors .........................................110
7.14. Connection Failures .....................................110
7.15. Session Errors ..........................................111
8. State Transitions .............................................112
8.1. Standard Connection State Diagrams .......................112
8.1.1. State Descriptions for Initiators and Targets .....112
8.1.2. State Transition Descriptions for
Initiators and Targets ............................114
8.1.3. Standard Connection State Diagram for an
Initiator .........................................118
8.1.4. Standard Connection State Diagram for a Target ....120
8.2. Connection Cleanup State Diagram for Initiators
and Targets ..............................................122
8.2.1. State Descriptions for Initiators and Targets .....124
8.2.2. State Transition Descriptions for
Initiators and Targets ............................124
8.3. Session State Diagrams ...................................126
8.3.1. Session State Diagram for an Initiator ............126
8.3.2. Session State Diagram for a Target ................127
8.3.3. State Descriptions for Initiators and Targets .....129
8.3.4. State Transition Descriptions for
Initiators and Targets ............................129
9. Security Considerations .......................................131
9.1. iSCSI Security Mechanisms ................................132
9.2. In-Band Initiator-Target Authentication ..................132
9.2.1. CHAP Considerations ...............................134
9.2.2. SRP Considerations ................................136
9.2.3. Kerberos Considerations ...........................136
9.3. IPsec ....................................................137
9.3.1. Data Authentication and Integrity .................137
9.3.2. Confidentiality ...................................138
9.3.3. Policy, Security Associations, and
Cryptographic Key Management ......................139
9.4. Security Considerations for the X#NodeArchitecture Key ...141
9.5. SCSI Access Control Considerations .......................143
10. Notes to Implementers ........................................143
10.1. Multiple Network Adapters ...............................143
10.1.1. Conservative Reuse of ISIDs ......................143
10.1.2. iSCSI Name, ISID, and TPGT Use ...................144
10.2. Autosense and Auto Contingent Allegiance (ACA) ..........146
10.3. iSCSI Timeouts ..........................................146
10.4. Command Retry and Cleaning Old Command Instances ........147
10.5. Sync and Steering Layer, and Performance ................147
10.6. Considerations for State-Dependent Devices and
Long-Lasting SCSI Operations ............................147
10.6.1. Determining the Proper ErrorRecoveryLevel ........148
10.7. Multi-Task Abort Implementation Considerations ..........149
11. iSCSI PDU Formats ............................................150
11.1. iSCSI PDU Length and Padding ............................150
11.2. PDU Template, Header, and Opcodes .......................150
11.2.1. Basic Header Segment (BHS) .......................152
11.2.1.1. I (Immediate) Bit .......................152
11.2.1.2. Opcode ..................................152
11.2.1.3. F (Final) Bit ...........................154
11.2.1.4. Opcode-Specific Fields ..................154
11.2.1.5. TotalAHSLength ..........................154
11.2.1.6. DataSegmentLength .......................154
11.2.1.7. LUN .....................................154
11.2.1.8. Initiator Task Tag ......................154
11.2.2. Additional Header Segment (AHS) ..................155
11.2.2.1. AHSType .................................155
11.2.2.2. AHSLength ...............................155
11.2.2.3. Extended CDB AHS ........................156
11.2.2.4. Bidirectional Read Expected Data
Transfer Length AHS .....................156
11.2.3. Header Digest and Data Digest ....................156
11.2.4. Data Segment .....................................157
11.3. SCSI Command ............................................158
11.3.1. Flags and Task Attributes (Byte 1) ...............159
11.3.2. CmdSN - Command Sequence Number ..................159
11.3.3. ExpStatSN ........................................160
11.3.4. Expected Data Transfer Length ....................160
11.3.5. CDB - SCSI Command Descriptor Block ..............160
11.3.6. Data Segment - Command Data ......................161
11.4. SCSI Response ...........................................161
11.4.1. Flags (Byte 1) ...................................162
11.4.2. Status ...........................................163
11.4.3. Response .........................................163
11.4.4. SNACK Tag ........................................164
11.4.5. Residual Count ...................................164
11.4.5.1. Field Semantics .........................164
11.4.5.2. Residuals Concepts Overview .............164
11.4.5.3. SCSI REPORT LUNS Command and
Residual Overflow .......................165
11.4.6. Bidirectional Read Residual Count ................166
11.4.7. Data Segment - Sense and Response Data Segment ...167
11.4.7.1. SenseLength .............................167
11.4.7.2. Sense Data ..............................168
11.4.8. ExpDataSN ........................................168
11.4.9. StatSN - Status Sequence Number ..................168
11.4.10. ExpCmdSN - Next Expected CmdSN from This
Initiator .......................................169
11.4.11. MaxCmdSN - Maximum CmdSN from This Initiator ....169
11.5. Task Management Function Request ........................170
11.5.1. Function .........................................170
11.5.2. TotalAHSLength and DataSegmentLength .............173
11.5.3. LUN ..............................................173
11.5.4. Referenced Task Tag ..............................173
11.5.5. RefCmdSN .........................................174
11.5.6. ExpDataSN ........................................174
11.6. Task Management Function Response .......................175
11.6.1. Response .........................................176
11.6.2. TotalAHSLength and DataSegmentLength .............177
11.7. SCSI Data-Out and SCSI Data-In ..........................178
11.7.1. F (Final) Bit ....................................180
11.7.2. A (Acknowledge) Bit ..............................180
11.7.3. Flags (Byte 1) ...................................181
11.7.4. Target Transfer Tag and LUN ......................181
11.7.5. DataSN ...........................................182
11.7.6. Buffer Offset ....................................182
11.7.7. DataSegmentLength ................................182
11.8. Ready To Transfer (R2T) .................................183
11.8.1. TotalAHSLength and DataSegmentLength .............184
11.8.2. R2TSN ............................................184
11.8.3. StatSN ...........................................185
11.8.4. Desired Data Transfer Length and Buffer Offset ...185
11.8.5. Target Transfer Tag ..............................185
11.9. Asynchronous Message ....................................186
11.9.1. AsyncEvent .......................................187
11.9.2. AsyncVCode .......................................189
11.9.3. LUN ..............................................189
11.9.4. Sense Data and iSCSI Event Data ..................190
11.9.4.1. SenseLength .............................190 11.10. Text Request ...........................................191
11.10.1. F (Final) Bit ...................................192
11.10.2. C (Continue) Bit ................................192
11.10.3. Initiator Task Tag ..............................192
11.10.4. Target Transfer Tag .............................192
11.10.5. Text ............................................193
11.11. Text Response ..........................................194
11.11.1. F (Final) Bit ...................................194
11.11.2. C (Continue) Bit ................................195
11.11.3. Initiator Task Tag ..............................195
11.11.4. Target Transfer Tag .............................195
11.11.5. StatSN ..........................................196
11.11.6. Text Response Data ..............................196
11.12. Login Request ..........................................196
11.12.1. T (Transit) Bit .................................197
11.12.2. C (Continue) Bit ................................197
11.12.3. CSG and NSG .....................................198
11.12.4. Version .........................................198
11.12.4.1. Version-max ............................198
11.12.4.2. Version-min ............................198
11.12.5. ISID ............................................199
11.12.6. TSIH ............................................200
11.12.7. Connection ID (CID) .............................200
11.12.8. CmdSN ...........................................201
11.12.9. ExpStatSN .......................................201
11.12.10. Login Parameters ...............................201
11.13. Login Response .........................................202
11.13.1. Version-max .....................................202
11.13.2. Version-active ..................................203
11.13.3. TSIH ............................................203
11.13.4. StatSN ..........................................203
11.13.5. Status-Class and Status-Detail ..................203
11.13.6. T (Transit) Bit .................................206
11.13.7. C (Continue) Bit ................................206
11.13.8. Login Parameters ................................207
11.14. Logout Request .........................................207
11.14.1. Reason Code .....................................209
11.14.2. TotalAHSLength and DataSegmentLength ............209
11.14.3. CID .............................................210
11.14.4. ExpStatSN .......................................210
11.14.5. Implicit Termination of Tasks ...................210
11.15. Logout Response ........................................211
11.15.1. Response ........................................212
11.15.2. TotalAHSLength and DataSegmentLength ............212
11.15.3. Time2Wait .......................................212
11.15.4. Time2Retain .....................................212
11.16. SNACK Request ..........................................213
11.16.1. Type ............................................214
11.16.2. Data Acknowledgment .............................215
11.16.3. Resegmentation ..................................215
11.16.4. Initiator Task Tag ..............................216
11.16.5. Target Transfer Tag or SNACK Tag ................216
11.16.6. BegRun ..........................................216
11.16.7. RunLength .......................................216
11.17. Reject .................................................217
11.17.1. Reason ..........................................218
11.17.2. DataSN/R2TSN ....................................219
11.17.3. StatSN, ExpCmdSN, and MaxCmdSN ..................219
11.17.4. Complete Header of Bad PDU ......................219
11.18. NOP-Out ................................................220
11.18.1. Initiator Task Tag ..............................221
11.18.2. Target Transfer Tag .............................221
11.18.3. Ping Data .......................................221
11.19. NOP-In .................................................222
11.19.1. Target Transfer Tag .............................223
11.19.2. StatSN ..........................................223
11.19.3. LUN .............................................223
12. iSCSI Security Text Keys and Authentication Methods ..........223
12.1. AuthMethod ..............................................224
12.1.1. Kerberos .........................................226
12.1.2. Secure Remote Password (SRP) .....................226
12.1.3. Challenge Handshake Authentication
Protocol (CHAP) ..................................228
13. Login/Text Operational Text Keys .............................229
13.1. HeaderDigest and DataDigest .............................230
13.2. MaxConnections ..........................................232
13.3. SendTargets .............................................232
13.4. TargetName ..............................................232
13.5. InitiatorName ...........................................233
13.6. TargetAlias .............................................233
13.7. InitiatorAlias ..........................................234
13.8. TargetAddress ...........................................234
13.9. TargetPortalGroupTag ....................................235
13.10. InitialR2T .............................................236
13.11. ImmediateData ..........................................236
13.12. MaxRecvDataSegmentLength ...............................237
13.13. MaxBurstLength .........................................238
13.14. FirstBurstLength .......................................238
13.15. DefaultTime2Wait .......................................239
13.16. DefaultTime2Retain .....................................239
13.17. MaxOutstandingR2T ......................................239
13.18. DataPDUInOrder .........................................240
13.19. DataSequenceInOrder ....................................240
13.20. ErrorRecoveryLevel .....................................241
13.21. SessionType ............................................241
13.22. The Private Extension Key Format .......................242
13.23. TaskReporting ..........................................242
13.24. iSCSIProtocolLevel Negotiation .........................243
13.25. Obsoleted Keys .........................................243
13.26. X#NodeArchitecture .....................................244
13.26.1. Definition ......................................244
13.26.2. Implementation Requirements .....................244
14. Rationale for Revised IANA Considerations ....................245
15. IANA Considerations ..........................................246
16. References ...................................................248
16.1. Normative References ....................................248
16.2. Informative References ..................................251
Appendix A. Examples .............................................254
A.1. Read Operation Example ....................................254
A.2. Write Operation Example ...................................255
A.3. R2TSN/DataSN Use Examples .................................256
A.3.1. Output (Write) Data DataSN/R2TSN Example ...........256
A.3.2. Input (Read) Data DataSN Example ...................257
A.3.3. Bidirectional DataSN Example .......................258
A.3.4. Unsolicited and Immediate Output (Write) Data
with DataSN Example ................................259
A.4. CRC Examples ..............................................259
Appendix B. Login Phase Examples .................................261
Appendix C. SendTargets Operation ................................268
Appendix D. Algorithmic Presentation of Error Recovery
Classes ..............................................272
D.1. General Data Structure and Procedure Description ..........273
D.2. Within-command Error Recovery Algorithms ..................274
D.2.1. Procedure Descriptions .............................274
D.2.2. Initiator Algorithms ...............................275
D.2.3. Target Algorithms ..................................277
D.3. Within-connection Recovery Algorithms .....................279
D.3.1. Procedure Descriptions .............................279
D.3.2. Initiator Algorithms ...............................280
D.3.3. Target Algorithms ..................................283
D.4. Connection Recovery Algorithms ............................283
D.4.1. Procedure Descriptions .............................283
D.4.2. Initiator Algorithms ...............................284
D.4.3. Target Algorithms ..................................286
Appendix E. Clearing Effects of Various Events on Targets ........288
E.1. Clearing Effects on iSCSI Objects .........................288
E.2. Clearing Effects on SCSI Objects ..........................293
Acknowledgments ..................................................2941. Introduction ✨
okay bestie, let's get into it 🫶 SCSI (Small Computer System Interface) is a super popular family of protocols for talking to I/O devices, especially storage devices 💾 It's a client-server setup, lowkey iconic. The clients are called "initiators" 🎀 and they issue SCSI "commands" to ask for services from components. Those components are logical units living inside a server, and that server is called a "target" 🎯 A "SCSI transport" is the thing that maps this client-server SCSI protocol onto a specific interconnect 🔌 So an initiator is one endpoint of a SCSI transport, and a target is the other endpoint. Two sides, one connection, no cap 💅
The SCSI protocol has been mapped over a bunch of different transports, like Parallel SCSI, Intelligent Peripheral Interface (IPI), IEEE 1394 (FireWire), and Fibre Channel 🦋 Honestly these transports are super I/O-specific and they have limited distance capabilities, which is giving "stuck in one room" energy 🙈
Then the iSCSI protocol (the one this doc is actually about) 🌈 describes a way to transport SCSI packets over TCP/IP ✨ It's an interoperable solution that can take advantage of existing Internet infrastructure and Internet management facilities, and it addresses those distance limitations. Main character energy for sure 👑💜
2. Acronyms, Definitions, and Document Summary 🧚
2.1. Acronyms ✨
okay bestie, here's the whole acronym lineup for this spec 💅 it's a lot, but you'll see the same names everywhere so it's worth skimming 🌸
Acronym Definition
--------------------------------------------------------------
3DES Triple Data Encryption Standard
ACA Auto Contingent Allegiance
AEN Asynchronous Event Notification
AES Advanced Encryption Standard
AH Additional Header (not the IPsec AH!)
AHS Additional Header Segment
API Application Programming Interface
ASC Additional Sense Code
ASCII American Standard Code for Information Interchange
ASCQ Additional Sense Code Qualifier
ATA AT Attachment
BHS Basic Header Segment
CBC Cipher Block Chaining
CD Compact Disk
CDB Command Descriptor Block
CHAP Challenge Handshake Authentication Protocol
CID Connection ID
CO Connection Only
CRC Cyclic Redundancy Check
CRL Certificate Revocation List
CSG Current Stage
CSM Connection State Machine
DES Data Encryption Standard
DNS Domain Name Server
DOI Domain of Interpretation
DVD Digital Versatile Disk
EDTL Expected Data Transfer Length
ESP Encapsulating Security Payload
EUI Extended Unique Identifier
FFP Full Feature Phase
FFPO Full Feature Phase Only
HBA Host Bus Adapter
HMAC Hashed Message Authentication Code
I_T Initiator_Target
I_T_L Initiator_Target_LUN
IANA Internet Assigned Numbers Authority
IB InfiniBand
ID Identifier
IDN Internationalized Domain Name
IEEE Institute of Electrical and Electronics Engineers
IETF Internet Engineering Task Force
IKE Internet Key Exchange
I/O Input-Output
IO Initialize Only
IP Internet Protocol
IPsec Internet Protocol Security
IPv4 Internet Protocol Version 4
IPv6 Internet Protocol Version 6
IQN iSCSI Qualified Name
iSCSI Internet SCSI
iSER iSCSI Extensions for RDMA (see [RFC7145])
ISID Initiator Session ID
iSNS Internet Storage Name Service (see [RFC4171])
ITN iSCSI Target Name
ITT Initiator Task Tag
KRB5 Kerberos V5
LFL Lower Functional Layer
LTDS Logical-Text-Data-Segment
LO Leading Only
LU Logical Unit
LUN Logical Unit Number
MAC Message Authentication Code
NA Not Applicable
NAA Network Address Authority
NIC Network Interface Card
NOP No Operation
NSG Next Stage
OCSP Online Certificate Status Protocol
OS Operating System
PDU Protocol Data Unit
PKI Public Key Infrastructure
R2T Ready To Transfer
R2TSN Ready To Transfer Sequence Number
RDMA Remote Direct Memory Access
RFC Request For Comments
SA Security Association
SAM SCSI Architecture Model
SAM-2 SCSI Architecture Model - 2
SAN Storage Area Network
SAS Serial Attached SCSI
SATA Serial AT Attachment
SCSI Small Computer System Interface
SLP Service Location Protocol
SN Sequence Number
SNACK Selective Negative Acknowledgment - also
Sequence Number Acknowledgement for data
SPDTL SCSI-Presented Data Transfer Length
SPKM Simple Public-Key Mechanism
SRP Secure Remote Password
SSID Session ID
SW Session-Wide
TCB Task Control Block
TCP Transmission Control Protocol
TMF Task Management Function
TPGT Target Portal Group Tag
TSIH Target Session Identifying Handle
TTT Target Transfer Tag
UA Unit Attention
UFL Upper Functional Layer
ULP Upper Level Protocol
URN Uniform Resource Name
UTF Universal Transformation Format
WG Working Group2.2. Definitions 🦋
okay now the important vocab, so you can follow the rest of the spec without getting lost 🫶
- Alias: an alias string can also be attached to an iSCSI node. It lets an organization give the iSCSI name a friendly label, but it is never a replacement for the iSCSI name itself 🌈
- CID (connection ID): connections inside a session are tracked by a connection ID. It's unique to that connection within the session, from the initiator's point of view. The initiator makes it up and hands it to the target in Login Requests and in logouts that close connections 💜
- Connection: a connection is a TCP connection. The initiator and target talk over one or more of these, and they carry control messages, SCSI commands, parameters, and data inside iSCSI Protocol Data Units (iSCSI PDUs) 🎀
- I/O Buffer: an I/O Buffer is where SCSI data gets sent from, or received into, during a SCSI read or write. For a read or write data transfer to happen for a task, the initiator needs an I/O Buffer, and the target needs at least one 🧚
- INCITS: this stands for InterNational Committee for Information Technology Standards. It has a broad scope across ICT, covering storage, processing, transfer, display, management, organization, and retrieval of information. It's ANSI's Technical Advisory Group for ISO/IEC Joint Technical Committee 1 (JTC 1). Check
<http://www.incits.org>🌸 - InfiniBand: InfiniBand is an I/O architecture that was originally meant to replace Peripheral Component Interconnect (PCI), and it targets high-performance server interconnectivity [IB] ⭐
- iSCSI Device: an iSCSI device is a SCSI device that uses an iSCSI service delivery subsystem. [SAM2] defines the Service Delivery Subsystem as the transport mechanism for SCSI commands and responses 💅
- iSCSI Initiator Name: this specifies the worldwide unique name of the initiator 🍓
- iSCSI Initiator Node: an iSCSI initiator node is the "initiator" device. Wherever the context is ambiguous, the rest of the document says whether "initiator" means a port or a device. Unqualified uses of "initiator" mean an initiator port (or device), depending on the context 🔥
- iSCSI Layer: this layer builds and receives iSCSI PDUs, then relays them to and from one or more TCP connections that together form an initiator-target "session" 🦋
- iSCSI Name: the name of an iSCSI initiator or iSCSI target 💖
- iSCSI Node: an iSCSI node represents a single iSCSI initiator or iSCSI target, or one instance of each. A Network Entity holds one or more iSCSI nodes, and each node can be reached through one or more Network Portals. An iSCSI node is identified by its iSCSI name. Keeping the name separate from the addresses means several iSCSI nodes can share one address, and one iSCSI node can use several addresses 👑
- iSCSI Target Name: this specifies the worldwide unique name of the target 🌈
- iSCSI Target Node: the iSCSI target node is the "target" device. Wherever the context is ambiguous, the rest of the document says whether "target" means a port or a device. Unqualified uses of "target" mean a target port (or device), depending on the context 🧚
- iSCSI Task: an iSCSI task is an iSCSI request that expects a response 🎀
- iSCSI Transfer Direction: this is defined from the initiator's point of view. Outbound (outgoing) transfers go from the initiator to the target, and inbound (incoming) transfers go from the target to the initiator 💜
- ISID: the ISID is the initiator part of the session identifier. The initiator states it explicitly during login 🌸
- I_T Nexus: according to [SAM2], the I_T nexus is a relationship between a SCSI initiator port and a SCSI target port. For iSCSI, that relationship is a session, meaning a relationship between the iSCSI initiator's end of the session (the SCSI initiator port) and the iSCSI target's portal group. The I_T nexus can be identified by combining the SCSI port names. In other words, the I_T nexus identifier is the tuple
(iSCSI Initiator Name + ',i,' + ISID, iSCSI Target Name + ',t,' + Target Portal Group Tag)🫶 - I_T_L Nexus: this is a SCSI concept. It's the relationship between a SCSI initiator port, a SCSI target port, and a Logical Unit (LU) 🔥
- NAA: "NAA" refers to Network Address Authority, a naming format defined by the INCITS T11 Fibre Channel protocols [FC-FS3] 🍓
- Network Entity: a Network Entity is a device or gateway that you can reach from the IP network. It must have one or more Network Portals, and each one can be used to get onto the IP network by some of the iSCSI nodes inside that Network Entity 🦋
- Network Portal: a Network Portal is a part of a Network Entity that has a TCP/IP network address. An iSCSI node inside that Network Entity can use it for the connection(s) in one of its iSCSI sessions. In an initiator, a Network Portal is identified by its IP address. In a target, it's identified by its IP address and its listening TCP port ✨
- Originator: in a negotiation or exchange, the originator is the party that starts it 💅
- PDU (Protocol Data Unit): the initiator and target split their communications into messages, and the term "iSCSI Protocol Data Unit" (iSCSI PDU) refers to those messages 💖
- Portal Groups: iSCSI supports multiple connections within the same session, and some implementations can combine a session's connections across multiple Network Portals. A portal group is a set of Network Portals within an iSCSI Network Entity that together can coordinate a session whose connections span those portals. Not every Network Portal in a portal group has to take part in every session that runs through that portal group. One or more portal groups may provide access to an iSCSI node. Each Network Portal, as a given iSCSI node uses it, belongs to exactly one portal group within that node 🌈
- Portal Group Tag: this 16-bit quantity identifies a portal group within an iSCSI node. All Network Portals with the same Portal Group Tag, in the context of a given iSCSI node, are in the same portal group 👑
- Recovery R2T: a recovery R2T is an R2T that a target generates after noticing it lost one or more Data-Out PDUs. It can notice this through a digest error, a sequence error, or a sequence reception timeout. A recovery R2T carries the next unused R2TSN, but it requests all or part of the data burst that an earlier R2T (with a lower R2TSN) had already asked for 🧚
- Responder: in a negotiation or exchange, the responder is the party that answers the originator 🎀
- SAS: the Serial Attached SCSI (SAS) standard includes both a physical layer that's compatible with Serial ATA, and protocols for carrying SCSI commands to SAS devices and ATA commands to SATA devices [SAS] [SPL] 🌸
- SCSI Device: okay so this is the SAM-2 term for an entity with one or more SCSI ports hooked up to a service delivery subsystem that supports a SCSI application protocol 💅. A SCSI initiator device has one or more SCSI initiator ports and zero or more application clients. A target device has one or more SCSI target ports, one or more device servers, and the associated LUs 🎀. For iSCSI, the SCSI device is the part of an iSCSI node that does the SCSI stuff, so there can be at most one per node 🫶. You can only get to it during an iSCSI Normal operational session 🔥. And the SCSI device name is defined to be the iSCSI name of the node ✨.
- SCSI Layer: this one builds and receives SCSI CDBs (Command Descriptor Blocks) and passes them along with the rest of the Execute Command [SAM2] parameters to and from the iSCSI Layer 🦋.
- Session: a group of TCP connections linking an initiator and a target forms a session, which is loosely the same thing as a SCSI I_T nexus 🌸. Connections can be added to or removed from a session 💜. Across all the connections in a session, the initiator sees one and the same target 👑.
- SCSI Port: the SAM-2 word for an entity inside a SCSI device that gives it the SCSI functionality to plug into a service delivery subsystem 🧚. For iSCSI, the initiator port and target port definitions are different, so pay attention bestie 🙈.
- SCSI Initiator Port: this maps to the endpoint of an iSCSI Normal operational session 💖. That session gets negotiated through login between an iSCSI initiator node and an iSCSI target node 🌈. When login finishes successfully, a SCSI initiator port is created inside the SCSI initiator device ⭐. The SCSI initiator port name and the SCSI initiator port identifier are both the iSCSI Initiator Name, plus (a) a label marking it as an initiator port name/identifier and (b) the ISID portion of the session identifier 🍓.
- SCSI Port Name: a name made of UTF-8 [RFC3629] encoding of Unicode [UNICODE] characters, built from the iSCSI name +
'i'or't'+ the ISID or Target Portal Group Tag 🎀. - SCSI-Presented Data Transfer Length (SPDTL): SPDTL is the aggregate data length the SCSI layer logically "presents" to the iSCSI layer for a Data-In or Data-Out transfer within a SCSI task 💅. For a bidirectional task there are two SPDTL values, one for Data-In and one for Data-Out 🦋. "Presenting" includes immediate data per the data transfer model in [SAM2], and it excludes overlapping data transfers, if any, that the SCSI layer asked for 🙈.
- SCSI Target Port: this maps to an iSCSI target portal group 👑.
- SCSI Target Port Name and SCSI Target Port Identifier: both are defined to be the iSCSI Target Name, plus (a) a label marking it as a target port name/identifier and (b) the Target Portal Group Tag 💜.
- SSID (Session ID): a session between an iSCSI initiator and an iSCSI target is identified by a session ID, which is a tuple of an initiator part (ISID) and a target part (Target Portal Group Tag) 🌸. The initiator explicitly specifies the ISID when the session is set up 🫶. The Target Portal Group Tag is implied by the initiator when it picks the TCP endpoint at connection establishment 🧚. The target must also send back the TargetPortalGroupTag key as a confirmation during connection establishment ✨.
- T10: T10 is a technical committee inside INCITS that develops standards and technical reports on I/O interfaces, especially the SCSI (Small Computer System Interface) series 🔥. Check out
<http://www.t10.org>🌈. - T11: T11 is a technical committee inside INCITS in charge of standards for Intelligent Peripheral Interface (IPI), High-Performance Parallel Interface (HIPPI), and Fibre Channel (FC) 🦋. See
<http://www.t11.org>💅. - Target Portal Group Tag: a numerical identifier (16-bit) for an iSCSI target portal group 🍓.
- Target Transfer Tag (TTT): the TTT is an iSCSI protocol field that shows up in a few PDUs (like R2T and NOP-In) 💖. The target always sends it to the initiator first, and then the initiator quotes it back in its PDUs to the target about that same task/exchange 🫶. So the TTT basically works as an opaque handle that helps the target match incoming PDUs to the right execution context 👑.
- Third-party: this word qualifies nexus objects (I_T or I_T_L) and iSCSI sessions, meaning these objects and sessions pick up the side effects of actions that happen in a separate iSCSI session 😭. One example is an iSCSI session noticing that its I_T_L nexus to a LU got reset because of a LU reset run over a different I_T nexus 💀.
- TSIH (Target Session Identifying Handle): a target-assigned tag for a session with a specific named initiator 🧚. The target generates it during session establishment 🌈. Apart from being a 16-bit binary string, its internal format and content aren't defined by this protocol 🙈. The one exception is the value with all bits set to 0, which is reserved and used by the initiator to signal a new session 🎀. It's handed to the target during additional connection establishment for that same session 🫶.
2.3. Summary of Changes ✨
Okay bestie, here's the tea on everything that changed 🍵. Buckle up 💅.
- Consolidated RFCs 3720, 3980, 4850, and 5048, and made the necessary editorial changes 🌸.
- Specified iSCSIProtocolLevel as "1" in Section 13.24 and added a related normative reference to [RFC7144] 🎀.
- Removed markers and related keys 💀.
- Removed SPKM authentication and related keys 😭.
- Added a new Section 13.25 on responding to obsoleted keys 🦋.
- Have explicitly allowed initiator+target implementations throughout the text 👑.
- Clarified in Section 4.2.7 that implementations SHOULD NOT rely on SLP-based discovery 🔥.
- Added Unified Modeling Language (UML) diagrams and related conventions in Section 3 🧚.
- Made FastAbort implementation a "SHOULD" requirement in Section 4.2.3.4, rather than the previous "MUST" requirement 💜.
- Required in Section 4.2.7.1 that iSCSI Target Name be the same as iSCSI Initiator Name for SCSI (composite) devices with both roles 🫶.
- Changed the "MUST NOT" to "should be avoided" in Section 4.2.7.2 regarding usage of characters such as punctuation marks in iSCSI names 🙈.
- Updated Section 9.3 to require the following: MUST implement IPsec, 2400-series RFCs (IPsec v2, IKEv1); and SHOULD implement IPsec, 4300-series RFCs (IPsec v3, IKEv2) 🔥.
- Clarified in Section 10.2 that ACA is a "SHOULD" only for iSCSI targets 🌈.
- Prohibited usage of X# name prefix for new public keys in Section 6.2 💖.
- Prohibited usage of Y# name prefix for new digest extensions in Section 13.1 and Z# name prefix for new authentication method extensions in Section 12.1 🍓.
- Added a "SHOULD" in Section 6.2 that initiators and targets support at least six (6) exchanges during text negotiation ⭐.
- Added a clarification that Appendix C is normative 🎀.
- Added a normative requirement on [RFC7146] and made a few related changes in Section 9.3 to align the text in this document with that of [RFC7146] 💅.
- Added a new Section 9.2.3 covering Kerberos authentication considerations 🦋.
- Added text in Section 9.3.3 noting that OCSP is now allowed for checking certificates used with IPsec in addition to the use of CRLs 👑.
- Added text in Section 9.3.1 specifying that extended sequence numbers (ESNs) are now required for ESPv2 (part of IPsec v2) 💜.
2.4. Conventions 🎀
In examples, "I->" and "T->" show iSCSI PDUs sent by the initiator and target, respectively 🌸.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119] 💖.
3. UML Conventions 🦋
3.1. UML Conventions Overview
The SCSI Architecture Model (SAM) uses class diagrams and object diagrams with notation based on the Unified Modeling Language [UML] 🧚. So this document uses UML too, to model the relationships between SCSI and iSCSI objects 🫶.
A full treatise on UML's graphical notation is beyond the scope of this document 🙈. But since the static class diagrams are drawn in ASCII, the notational conventions used here get a description in the rest of this section 💅.
3.2. Multiplicity Notion
Not specified The number of instances of an attribute is not
specified.
1 One instance of the class or attribute exists.
0..* Zero or more instances of the class or attribute
exist.
1..* One or more instances of the class or attribute
exist.
0..1 Zero or one instance of the class or attribute
exists.
n..m n to m instances of the class or attribute exist
(e.g., 2..8).
x, n..m Multiple disjoint instances of the class or
attribute exist (e.g., 2, 8..15).3.3. Class Diagram Conventions
+--------------+ +--------------+ +--------------+
| Class Name | | Class Name | | Class Name |
+--------------+ +--------------+ +--------------+
| | | |
+--------------+ +--------------+
| |
+--------------+The previous three diagrams are examples of a class with no attributes and with no operations 🌈.
+-------------------+ +-------------------+
| Class Name | | Class Name |
+-------------------+ +-------------------+
| attribute 01[1] | | attribute 01[1] |
| attribute 02[1] | | attribute 02[1] |
+-------------------+ +-------------------+
| |
+-------------------+The preceding two diagrams are examples of a class with attributes and with no operations ⭐.
+------------------------+
| Class Name |
+------------------------+
| attribute 01[1..*] |
| attribute 02[1] |
+------------------------+
| operation 01() |
| operation 02() |
+------------------------+The preceding diagram is an example of a class with attributes that have a specified multiplicity and operations 👑.
3.4. Class Diagram Notation for Associations 🦋
Okay, associations are where the arrows get spicy 🔥. Here's the bidirectional one, where both classes know about each other:
+-----------------+
| Class A |
+-----------------+ association_name +-----------------+
| attribute 01[1] |<------------------>| Class B |
| attribute 02[1] | 1..* 0..1 +-----------------+
+-----------------+ | attribute 03[1] |
| operation 1() | +-----------------+
+-----------------+So Class A knows about Class B (you read it as "Class A association_name Class B"), and Class B knows about Class A (read as "Class B association_name Class A"). Mutual besties 🫶 The association_name part is optional, so you can skip it if you want. And those 1..* and 0..1 numbers are the multiplicity, which tells you how many instances of the object we're talking about 🌸
Next up is the one-way street where only Class B knows about Class A:
+--------------------+
| Class A |
+--------------------+ +--------------------+
| attribute 01[1] |<-------------| Class B |
| attribute 02[1] | 1 0..1 +--------------------+
+--------------------+ | attribute 03[1] |
| operation 1() | +--------------------+
+--------------------+Class B knows about Class A (read as "Class B knows about Class A"), but Class A does not know about Class B. Class A is kinda oblivious here 🙈
And the opposite one-way street, where only Class A knows about Class B:
+----------------------+
| Class A |
+----------------------+ +--------------------+
| attribute 01[1] |----------->| Class B |
| attribute 02[1] | 0..* 1 +--------------------+
+----------------------+ | attribute 03[1] |
| operation 1() | +--------------------+
+----------------------+Class A knows about Class B (read as "Class A knows about Class B"), but Class B does not know about Class A. Totally valid, no drama 💅
3.5. Class Diagram Notation for Aggregations 🧚
Aggregations are the "the whole contains the part" energy ✨ First, the hollow diamond version:
+---------------+ +--------------+
| Class whole |o------------| Class part |
+---------------+ +--------------+Class whole is an aggregate that contains Class part, and Class part may continue to exist even if Class whole is removed. Read it as "the whole contains the part." The part can literally outlive the whole, which is so iconic 👑
Now the filled diamond, which is way more committed:
+---------------+ +--------------+
| Class whole |@------------| Class part |
+---------------+ +--------------+Class whole is still an aggregate that contains Class part, but this time Class part only belongs to one Class whole, and it does not continue to exist if the Class whole is removed. Read as "the whole contains the part." Full commitment, no escape route 💀
Last one is about constraints between associations. The (a) footnote is where the rule lives:
+-------------+
| |
+-------------+
| |
+ =(a)= +
| |This diagram is an example where there is a constraint between the associations, and the (a) footnote describes that constraint. Go read the footnote, bestie 📚
3.6. Class Diagram Notation for Generalizations 🌈
Inheritance time! This is the triangle arrow pointing up at the parent:
+---------------+
| Superclass |
+-------^-------+
/_\
|
+---------------+
| Subclass |
+---------------+The subclass is a kind of superclass here. A subclass shares all the attributes and operations of the superclass, so the subclass inherits from the superclass. It's giving family resemblance 🎀
4. Overview 🌸
Okay, we've officially hit the good stuff! This section is the big-picture tour of how iSCSI works. Fair warning though: this section is just an overview, so if the later normative text says something different, that text wins 👑
4.1. SCSI Concepts 💜
The SCSI Architecture Model - 2 [SAM2] describes the architecture of the SCSI family of I/O protocols in full detail. This section gives you a quick background on SCSI architecture and is meant to get you comfy with its terminology 🫶
At the highest level, SCSI is a family of interfaces for requesting services from I/O devices. That includes hard drives, tape drives, CD and DVD drives, printers, and scanners. In SCSI terminology, an individual I/O device is called a "logical unit" (LU).
SCSI is a client-server architecture. Clients of a SCSI interface are called "initiators", and they issue SCSI "commands" to request services from components (LUs) of a server known as a "target". The "device server" on the LU is the one that accepts SCSI commands and processes them 🍓
A "SCSI transport" maps the client-server SCSI protocol to a specific interconnect. The initiator is one endpoint of a SCSI transport, and the "target" is the other endpoint. A target can contain multiple LUs, and each LU has an address within a target called a Logical Unit Number (LUN) ✨
A SCSI task is a SCSI command or possibly a linked set of SCSI commands. Some LUs support multiple pending (queued) tasks, but the queue of tasks is managed by the LU. The target uses an initiator-provided "task tag" to tell tasks apart. Only one command in a task can be outstanding at any given time, so no juggling within a single task 🤹
Each SCSI command results in an optional data phase and a required response phase. In the data phase, information can travel from the initiator to the target (that's a write), from the target to the initiator (that's a read), or in both directions. In the response phase, the target returns the final status of the operation, including any errors 📦
Command Descriptor Blocks (CDBs) are the data structures used to hold the command parameters that an initiator sends to a target. The CDB content and structure are defined by [SAM2] and device-type specific SCSI standards 💅
4.2. iSCSI Concepts and Functional Overview 🦋
The iSCSI protocol is a mapping of the SCSI command, event, and task management model (see [SAM2]) over the TCP protocol. SCSI commands are carried by iSCSI requests, and SCSI responses and status are carried by iSCSI responses. iSCSI also uses the request-response mechanism for its own iSCSI protocol mechanisms 🌈
For the rest of this document, the terms "initiator" and "target" refer to "iSCSI initiator node" and "iSCSI target node", respectively (see iSCSI), unless otherwise qualified.
As its title suggests, Section 4 gives an overview of the iSCSI concepts. The later sections of the specification hold the normative requirements, and in many cases they cover the same concepts discussed in Section 4. If there's any disagreement between the two, the normative requirements text overrides the overview text in Section 4. Remember that, bestie 🧠
In keeping with similar protocols, the initiator and target divide their communications into messages. This document uses the term "iSCSI Protocol Data Unit" (iSCSI PDU) for these messages 📨
For performance reasons, iSCSI allows a "phase-collapse". A command and its associated data may be shipped together from initiator to target, and data and responses may be shipped together from targets. Efficiency era ⚡
The iSCSI transfer direction is defined with respect to the initiator. Outbound or outgoing transfers are transfers from an initiator to a target, while inbound or incoming transfers are from a target to an initiator 🧭
An iSCSI task is an iSCSI request for which a response is expected 💌
In this document, "iSCSI request", "iSCSI command", request, or (unqualified) command have the same meaning. Also, unless otherwise specified, status, response, or numbered response have the same meaning. So many names for the same thing, lol 🙃
4.2.1. Layers and Sessions 🧚
The following conceptual layering model is used to specify initiator and target actions, and how those actions relate to transmitted and received Protocol Data Units:
- The SCSI layer builds/receives SCSI CDBs (Command Descriptor Blocks) and passes/receives them with the remaining Execute Command [SAM2] parameters to/from
- the iSCSI layer that builds/receives iSCSI PDUs and relays/receives them to/from one or more TCP connections; the group of connections form an initiator-target "session".
Communication between the initiator and target happens over one or more TCP connections. The TCP connections carry control messages, SCSI commands, parameters, and data within iSCSI Protocol Data Units (iSCSI PDUs). The group of TCP connections that link an initiator with a target form a session (equivalent to a SCSI I_T nexus; see Section 4.4.2). A session is defined by a session ID that is made up of an initiator part and a target part. TCP connections can be added and removed from a session. Each connection within a session is identified by a connection ID (CID) 🎀
Across all connections within a session, an initiator sees one "target image". All target-identifying elements, such as a LUN, are the same. A target also sees one "initiator image" across all connections within a session. Initiator-identifying elements, such as the Initiator Task Tag, are global across the session, no matter which connection they're sent or received on 🫶
iSCSI targets and initiators MUST support at least one TCP connection and MAY support several connections in a session. For error recovery purposes, targets and initiators that support a single active connection in a session SHOULD support two connections during recovery. Backup lanes for the win 🛟
4.2.2. Ordering and iSCSI Numbering 🔢
iSCSI uses command and status numbering schemes, plus a data sequencing scheme. Numbering is how everything stays in order, bestie 💖
Command numbering is session-wide and is used for ordered command delivery over multiple connections. It can also be used as a mechanism for command flow control over a session 🚦
Status numbering is per connection and is used to enable missing status detection and recovery in the presence of transient or permanent communication errors 🔍
Data sequencing is per command, or part of a command (an R2T-triggered sequence), and is used to detect missing data and/or R2T PDUs due to header digest errors 🕵️♀️
Typically, fields in the iSCSI PDUs communicate the sequence numbers between the initiator and target. During periods when traffic on a connection is unidirectional, iSCSI NOP-Out/NOP-In PDUs may be utilized to synchronize the command and status ordering counters of the target and initiator 🔄
The iSCSI session abstraction is equivalent to the SCSI I_T nexus, and the iSCSI session provides ordered command delivery from the SCSI initiator to the SCSI target. For the detailed design considerations that led to the iSCSI session model as it's defined here, and how it relates the SCSI command ordering features defined in SCSI specifications to the iSCSI concepts, see [RFC3783]. Go deep there if you're curious, it's a whole vibe 🧠✨
4.2.2.1. Command Numbering and Acknowledging ✨
Okay bestie, so iSCSI does ordered command delivery within a session 💅 Every command (that's every initiator-to-target PDU on its way over) gets a number 🔢
iSCSI treats a task as instantiated on the target every time the initiator sends a request 🎯 You can run a bunch of task management operations on an iSCSI task, including abort and reassign (see Section 11.5) 🧹 But an abort can't be performed on a task management operation, and reassign comes with some constraints. Check Section 11.5.1 for the tea ☕
Some iSCSI tasks are SCSI tasks, and a whole lot of SCSI stuff is tied to a SCSI task ([SAM2]) 🦋 Either way, the task is identified by the Initiator Task Tag for its entire life 🏷️
The command number rides along in the iSCSI PDU as the CmdSN (command sequence number) 💖 It's counted across the whole session, not per connection, and every outgoing iSCSI PDU carries it. The initiator allocates CmdSNs with a 32-bit unsigned counter (modulo 2**32). Comparisons and arithmetic on CmdSNs use Serial Number Arithmetic as defined in [RFC1982], where SERIAL_BITS = 32 🔥
Commands meant for immediate delivery get marked with an immediate delivery flag, and they MUST also carry the current CmdSN 🚀 The CmdSN MUST NOT advance after a command marked for immediate delivery is sent. Not me moving the counter on the fast lane 🙈
Command numbering kicks off with the first Login Request on the first connection of a session (the leading login on the leading connection) 🌸 For every non-immediate command issued after that, the CmdSN MUST be incremented by 1 in a Serial Number Arithmetic sense, as defined in [RFC1982] ✨
If immediate delivery is used with task management commands, these commands may reach the target before the tasks they're supposed to act on 👀 But their CmdSN works as a marker of where they sit in the stream of commands 🧭 The initiator and target MUST ensure that the SCSI task management functions specified in [SAM2] act in accordance with the [SAM2] specification 💅 For example, both commands and responses appear as if they were delivered in order. Whenever the CmdSN for an outgoing PDU isn't set by an explicit rule, the CmdSN carries the current value of the local CmdSN variable (more on that later in this section) 🦋
How an implementation decides to mark a PDU for immediate delivery, or how iSCSI decides by itself to mark one, is beyond the scope of this document 🙃 Not our problem, bestie.
The number of commands used for immediate delivery isn't limited, and their delivery to execution isn't acknowledged through the numbering scheme 🎉 An iSCSI target MAY reject immediate commands, for example because it's out of resources to fit more commands 😅 An iSCSI target MUST be able to handle at least one immediate task management command and one immediate non-task-management iSCSI command per connection at any time 🫶
In this document, delivery for execution means delivery to the SCSI execution engine, or to an iSCSI protocol-specific execution engine (for example, for Text Requests with public or private extension keys that involve an execution component) 🧚 Except for commands marked for immediate delivery, the iSCSI target layer MUST deliver commands for execution in the order specified by the CmdSN 💜 Commands marked for immediate delivery may be delivered for execution as soon as they're detected ⚡ iSCSI may avoid delivering some commands to the SCSI target layer if a prior SCSI or iSCSI action requires it. For example, a CLEAR TASK SET task management request that arrives before all the commands it was supposed to act on 🙅♀️
On any connection, the iSCSI initiator MUST send commands in increasing order of CmdSN, except for commands that are retransmitted due to digest error recovery and connection recovery 🔁
For the numbering mechanism, the initiator and target keep track of the following three variables for each session 📋
CmdSN: the current command sequence number, advanced by 1 on each command shipped, except for commands marked for immediate delivery as discussed above. TheCmdSNalways holds the number to be assigned to the next command PDU 🧁ExpCmdSN: the next command the target expects. The target acknowledges all commands up to, but not including, this number. The initiator treats all commands with aCmdSNless than theExpCmdSNas acknowledged. The target iSCSI layer sets theExpCmdSNto the largest non-immediateCmdSNit can deliver for execution, "plus 1" per [RFC1982] 🌈 There MUST NOT be any holes in the acknowledgedCmdSNsequence 🕳️🚫MaxCmdSN: the maximum number to be shipped. The queuing capacity of the receiving iSCSI layer isMaxCmdSN - ExpCmdSN + 1🍓
The initiator's ExpCmdSN and MaxCmdSN are derived from target-to-initiator PDU fields. Comparisons and arithmetic on ExpCmdSN and MaxCmdSN MUST use Serial Number Arithmetic as defined in [RFC1982], where SERIAL_BITS = 32 🔢✨
The target MUST NOT transmit a MaxCmdSN that is less than ExpCmdSN - 1 🙅♀️ For non-immediate commands, the CmdSN field can take any value from ExpCmdSN to MaxCmdSN, inclusive 🎀 The target MUST silently ignore any non-immediate command outside of this range, or any non-immediate duplicate within the range 🤫 The CmdSN carried by immediate commands may lie outside the ExpCmdSN-to-MaxCmdSN range 🦋 For example, if the initiator has already sent a non-immediate command carrying a CmdSN equal to MaxCmdSN, the target window is closed 🚪 For group task management commands issued as immediate commands, the CmdSN indicates the scope of the group action (for example, an ABORT TASK SET indicates which commands are to be aborted) 🧹
The initiator processes the MaxCmdSN and ExpCmdSN fields as follows 👑
- If the PDU
MaxCmdSNis less than the PDUExpCmdSN - 1(in a Serial Number Arithmetic sense), both are ignored. 🙈 - If the PDU
MaxCmdSNis greater than the localMaxCmdSN(in a Serial Number Arithmetic sense), it updates the localMaxCmdSN. Otherwise, it's ignored. 📈 - If the PDU
ExpCmdSNis greater than the localExpCmdSN(in a Serial Number Arithmetic sense), it updates the localExpCmdSN. Otherwise, it's ignored. 📈
This sequence is required because updates may arrive out of order (for example, when the updates are sent on different TCP connections) 🌀
iSCSI initiators and targets MUST support the command numbering scheme 💖
A numbered iSCSI request doesn't change its allocated CmdSN, no matter how many times or under what circumstances it's reissued (see Section 7.2.1) 🔒 At the target, the CmdSN only matters while the command hasn't created any state related to its execution (the execution state). After that, the CmdSN becomes irrelevant 🥱 Checking for the execution state (represented by identifying the Initiator Task Tag) MUST come before any other action at the target 🥇 If no execution state is found, ordering and delivery come next. If an execution state is found, delivery follows, but only if it hasn't already been delivered 🧩
If an initiator issues a command retry for a command with CmdSN R on a connection while the session CmdSN value is Q, it MUST NOT advance the CmdSN past R + 2**31 - 1, unless 🛑
- the connection is no longer operational (that is, it has returned to the FREE state; see Section 8.1.3) 🔌
- the connection has been reinstated (see Section 6.3.4), or 🔁
- a non-immediate command with a
CmdSNequal to or greater than Q was issued after the command retry on the same connection, and the reception of that command is acknowledged by the target (see Section 10.4) 🤝
A target command response or Data-In PDU with status MUST NOT precede the command acknowledgment. However, the acknowledgment MAY be included in the response or the Data-In PDU 🎁
4.2.2.2. Response/Status Numbering and Acknowledging 🌷
Responses on their way from the target to the initiator get numbered too 🔢 The StatSN (status sequence number) handles this job 💅 The StatSN is a counter kept per connection. The initiator uses the ExpStatSN to acknowledge status. The status sequence number space is 32-bit unsigned integers, and the arithmetic is regular mod(2**32) arithmetic 🧮
Status numbering starts with the Login Response to the first Login Request of the connection. The Login Response includes an initial value for status numbering, and any initial value is valid 🌈
To enable command recovery, the target MAY keep enough state information for data and status recovery after a connection failure 🛟 A target that does this can safely throw out all the state information it kept for recovering a command once the delivery of that command's status (numbered StatSN) is acknowledged through the ExpStatSN ✨
A large absolute difference between the StatSN and the ExpStatSN may signal a failed connection 🚨 Initiators MUST undertake recovery actions if the difference is greater than an implementation-defined constant, and that constant MUST NOT exceed 2**31 - 1 🆘
Initiators and targets MUST support the response-numbering scheme 💜
4.2.2.3. Response Ordering 🎀
4.2.2.3.1. Need for Response Ordering 🦋
Whenever an iSCSI session is made up of multiple connections, the Response PDUs (task responses or TMF Responses) that come from the target SCSI layer get spread across those connections by the target iSCSI layer, following iSCSI connection allegiance rules 🛣️ This process generally may not preserve the order of the responses by the time they reach the initiator SCSI layer 🌀
Since ordering isn't expected across SCSI Response PDUs anyway, this approach works fine in the general case 👍 But for the special cases where the SCSI layer does want some ordering, we introduce the notion of a "Response Fence" 🚧 A Response Fence is logically the attribute or property of a SCSI response message handed off to a target iSCSI layer, and it signals that there are special SCSI-level ordering considerations tied to that particular response message 🔥 Whenever a Response Fence is set or required on a SCSI response message, the semantics are defined in Section 4.2.2.3.2, with respect to how the target iSCSI layer handles those SCSI response messages 👑
4.2.2.3.2. Response Ordering Model Description 🎀
okay so bestie, the target SCSI layer hands the SCSI response messages over to the target iSCSI layer by calling the "Send Command Complete" data service ([SAM2], Clause 5.4.2) and the "Task Management Function Executed" service ([SAM2], Clause 6.9) 💅 🧚. Then when the iSCSI layer gets that response, it does the Response Fence thing for certain SCSI responses (Section 4.2.2.3.4 tells you exactly which ones, it's giving checklist 🍓).
Whenever a SCSI response needs the Response Fence, the target iSCSI layer MUST make sure these conditions are met when it delivers the response to the initiator iSCSI layer:
- A response with a Response Fence MUST be delivered chronologically after all the "preceding" responses on the I_T_L nexus, if the preceding responses are delivered at all, to the initiator iSCSI layer. 💜
- A response with a Response Fence MUST be delivered chronologically prior to all the "following" responses on the I_T_L nexus. 🌸
The words "preceding" and "following" are about the order a response gets handed off from the target SCSI layer to the target iSCSI layer ✨. Not vibes, just order 🫶.
4.2.2.3.3. iSCSI Semantics with the Interface Model 🦋
Whenever the TaskReporting key (Section 13.23) is negotiated to ResponseFence or FastAbort for an iSCSI session AND the Response Fence behavior is required for a SCSI response message, the target iSCSI layer MUST do the stuff in this section for that session 😭.
a) If it is a single-connection session, no special processing is required. The standard SCSI Response PDU build and dispatch process happens. 🌈
b) If it is a multi-connection session, the target iSCSI layer takes note of the last-sent and unacknowledged StatSN on each of the connections in the iSCSI session, and waits for an acknowledgment (NOP-In PDUs MAY be used to solicit acknowledgments as needed in order to accelerate this process) of each such StatSN to clear the fence. The SCSI Response PDU requiring the Response Fence behavior MUST NOT be sent to the initiator before acknowledgments are received for each of the unacknowledged StatSNs. 👑
c) The target iSCSI layer must wait for an acknowledgment of the SCSI Response PDU that carried the SCSI response requiring the Response Fence behavior. The fence MUST be considered cleared only after receiving the acknowledgment. 🔥
d) All further status processing for the LU is resumed only after clearing the fence. If any new responses for the I_T_L nexus are received from the SCSI layer before the fence is cleared, those Response PDUs MUST be held and queued at the iSCSI layer until the fence is cleared. 💀
4.2.2.3.4. Current List of Fenced Response Use Cases 🍓
This section lists the situations where fenced response behavior is REQUIRED in iSCSI target implementations. Heads up, this list is an exhaustive enumeration as currently identified. It's expected that as SCSI protocol specs evolve, the specs will enumerate when response fencing is required on a case-by-case basis 🧚.
Whenever the TaskReporting key (Section 13.23) is negotiated to ResponseFence or FastAbort for an iSCSI session, the target iSCSI layer MUST assume that the Response Fence is required for the following SCSI completion messages:
a) The first completion message carrying the UA after the multi-task abort on issuing and third-party sessions. See Section 4.2.3.2 for related TMF discussion.
b) The TMF Response carrying the multi-task TMF Response on the issuing session.
c) The completion message indicating ACA establishment on the issuing session.
d) The first completion message carrying the ACA ACTIVE status after ACA establishment on issuing and third-party sessions.
e) The TMF Response carrying the CLEAR ACA response on the issuing session.
f) The response to a PERSISTENT RESERVE OUT/PREEMPT AND ABORT command.
Notes:
- Due to the absence of ACA-related fencing requirements in [RFC3720], initiator implementations SHOULD NOT use ACA on multi-connection iSCSI sessions with targets complying only with [RFC3720]. This can be determined via TaskReporting key (Section 13.23) negotiation -- when the negotiation results in either "RFC3720" or "NotUnderstood". 🙈
- Initiators that want to employ ACA on multi-connection iSCSI sessions SHOULD first assess response-fencing behavior via negotiating for the "ResponseFence" or "FastAbort" value for the TaskReporting (Section 13.23) key. ✨
4.2.2.4. Data Sequencing 🌸
Data and R2T PDUs sent as part of some command execution MUST be sequenced. The DataSN field is used for data sequencing. For input (read) data PDUs, the DataSN starts with 0 for the first data PDU of an input command and goes up by 1 for each next data PDU. For output data PDUs, the DataSN starts with 0 for the first data PDU of a sequence (the initial unsolicited sequence or any data PDU sequence issued to satisfy an R2T) and goes up by 1 for each next data PDU. R2Ts are also sequenced per command. For example, the first R2T has an R2TSN of 0 and goes up by 1 for each next R2T. For bidirectional commands, the target uses the DataSN/R2TSN to sequence Data-In and R2T PDUs in one continuous sequence (undifferentiated). Unlike command and status, data PDUs and R2Ts are not acknowledged by a field in regular outgoing PDUs. Data-In PDUs can be acknowledged on demand by a special form of the SNACK PDU. Data and R2T PDUs are implicitly acknowledged by status for the command. The DataSN/R2TSN field lets the initiator detect missing data or R2T PDUs. 🫶
For any read or bidirectional command, a target MUST issue less than 232 combined R2T and Data-In PDUs. Any output data sequence MUST contain less than 232 Data-Out PDUs. 🦋
4.2.3. iSCSI Task Management 💖
4.2.3.1. Task Management Overview 🎀
iSCSI task management features let an initiator control the active iSCSI tasks on an operational iSCSI session that it has with an iSCSI target. Section 11.5 defines the task management function types that this specification defines -- ABORT TASK, ABORT TASK SET, CLEAR ACA, CLEAR TASK SET, LOGICAL UNIT RESET, TARGET WARM RESET, TARGET COLD RESET, and TASK REASSIGN.
Out of these function types, ABORT TASK and TASK REASSIGN functions manage a single active task, whereas ABORT TASK SET, CLEAR TASK SET, LOGICAL UNIT RESET, TARGET WARM RESET, and TARGET COLD RESET functions can each potentially affect multiple active tasks. 🌈
4.2.3.2. Notion of Affected Tasks 🧚
This section defines the notion of "affected tasks" in multi-task abort scenarios. Scope definitions in this section apply to both the standard multi-task abort semantics (Section 4.2.3.3) and the FastAbort multi-task abort semantics behavior (Section 4.2.3.4).
ABORT TASK SET: All outstanding tasks for the I_T_L nexus identified by the LUN field in the ABORT TASK SET TMF Request PDU.
CLEAR TASK SET: All outstanding tasks in the task set for the LU identified by the LUN field in the CLEAR TASK SET TMF Request PDU. See [SPC3] for the definition of a "task set".
LOGICAL UNIT RESET: All outstanding tasks from all initiators for the LU identified by the LUN field in the LOGICAL UNIT RESET Request PDU.
TARGET WARM RESET/TARGET COLD RESET: All outstanding tasks from all initiators across all LUs to which the TMF-issuing session has access on the SCSI target device hosting the iSCSI session.
Usage: An "ABORT TASK SET TMF Request PDU" in the preceding text is an iSCSI TMF Request PDU with the "Function" field set to "ABORT TASK SET" as defined in Section 11.5. Similar usage is employed for other scope descriptions. 💅
4.2.3.3. Standard Multi-Task Abort Semantics 👑
All iSCSI implementations MUST support the protocol behavior defined in this section as the default behavior. The execution of ABORT TASK SET, CLEAR TASK SET, LOGICAL UNIT RESET, TARGET WARM RESET, and TARGET COLD RESET TMF Requests consists of the following sequence of actions in the specified order on the specified party.
The initiator iSCSI layer:
a) MUST continue to respond to each TTT received for the affected tasks.
b) SHOULD process any responses received for affected tasks in the normal fashion. This is acceptable because the responses are guaranteed to have been sent prior to the TMF Response. 🌸
c) SHOULD receive the TMF Response concluding all the tasks in the set of affected tasks, unless the initiator has done something (e.g., LU reset, connection drop) that may prevent the TMF Response from being sent or received. The initiator MUST thus conclude all affected tasks as part of this step in either case and MUST discard any TMF Response received after the affected tasks are concluded. 😭
The target iSCSI layer:
a) MUST wait for responses on currently valid Target Transfer Tags of the affected tasks from the issuing initiator. MAY wait for responses on currently valid Target Transfer Tags of the affected tasks from third-party initiators. 🧚
b) MUST wait (concurrent with the wait in Step a) for all commands of the affected tasks to be received based on the CmdSN ordering. SHOULD NOT wait for new commands on third-party affected sessions -- only the instantiated tasks have to be considered for the purpose of determining the affected tasks. However, in the case of target-scoped requests (i.e., TARGET WARM RESET and TARGET COLD RESET), all of the commands that are not yet received on the issuing session in the command stream can be considered to have been received with no command waiting period -- i.e., the entire CmdSN space up to the CmdSN of the task management function can be "plugged". 🦋
c) MUST propagate the TMF Request to, and receive the response from, the target SCSI layer. 🎀
d) MUST provide the Response Fence behavior for the TMF Response on the issuing session as specified in Section 4.2.2.3.2. 🔥
e) MUST provide the Response Fence behavior on the first post-TMF Response on third-party sessions as specified in Section 4.2.2.3.3. If some tasks originate from non-iSCSI I_T_L nexuses, then the means by which the target ensures that all affected tasks have returned their status to the initiator are defined by the specific non-iSCSI transport protocol(s). 💜
Technically, the TMF servicing is complete in Step d). Data transfers corresponding to terminated tasks may, however, still be in progress on third-party iSCSI sessions even at the end of Step e). The TMF Response MUST NOT be sent by the target iSCSI layer before the end of Step d) and MAY be sent at the end of Step d) despite these outstanding data transfers until after Step e). 🌈
4.2.3.4. FastAbort Multi-Task Abort Semantics
okay bestie, this is the FastAbort section and it's giving speed ⚡ 💅. Implementations SHOULD follow it in general, and some steps might not match [RFC3720] semantics, but if you negotiate TaskReporting to "FastAbort" on a session, you MUST act exactly like this. 🫶 The TMFs in play are ABORT TASK SET, CLEAR TASK SET, LOGICAL UNIT RESET, TARGET WARM RESET, and TARGET COLD RESET, and each one runs these steps in this exact order, on whichever side is responsible. 🎀
The initiator iSCSI layer:
- a) You MUST NOT send any more Data-Out PDUs for affected tasks on the issuing connection of the issuing iSCSI session once the TMF has gone to the target. 🙈
- b) You SHOULD process any responses for affected tasks in the normal way. This is totally fine because the responses are guaranteed to arrive before the TMF Response. 🦋
- c) You MUST respond to each Async Message PDU with a Task Termination AsyncEvent (5), as defined in Section 11.9. 💜
- d) You MUST treat the TMF Response as terminating every affected task that hasn't gotten a response yet, and you MUST discard any responses for affected tasks that show up after the TMF Response has been passed up to the SCSI layer. (Tbh the semantics in this section make sure that out-of-order drama never happens with a compliant target. 💅✨)
The target iSCSI layer:
- a) You MUST wait for all commands of the affected tasks to be received, based on CmdSN ordering on the issuing session. You SHOULD NOT wait for new commands on third-party affected sessions, because only the instantiated tasks matter for figuring out what's affected. For target-scoped requests (TARGET WARM RESET and TARGET COLD RESET), every command that hasn't arrived yet on the issuing session's command stream can be treated as received, with no waiting period. In other words, the whole CmdSN space up to the CmdSN of the task management function can be "plugged." 🧚
- b) You MUST pass the TMF Request down to the target SCSI layer and receive its response. 🔥
- c) You MUST leave all active "affected TTTs" (that's active TTTs tied to affected tasks) valid. 🌸
- d) You MUST send an Asynchronous Message PDU with AsyncEvent=5 (Section 11.9) on:
- 1) each connection of each third-party session where at least one affected task is allegiant, but only if TaskReporting=FastAbort is operational on that third-party session, and
- 2) each connection, except the issuing connection of the issuing session, that has at least one allegiant affected task.
If there are multiple affected LUs (like after a target reset), then ONE Async Message PDU MUST go out for each such LU on each connection that has at least one allegiant affected task. The LUN field in each Asynchronous Message PDU MUST match the LUN of its LU. 🍓
- e) You MUST handle the Response Fence flag on the TMF Response on the issuing session, as defined in Section 4.2.2.3.3. 👑
- f) You MUST handle the Response Fence flag on the first post-TMF Response on third-party sessions, as defined in Section 4.2.2.3.3. If some tasks come from non-iSCSI I_T_L nexuses, the target figures out that all affected tasks have sent their status back to the initiator using whatever the specific non-iSCSI transport protocol(s) say. 🌈
- g) You MUST free up the affected TTTs (plus STags for iSER, if that applies) and their corresponding buffers, if any, once you get each NOP-Out acknowledgment the initiator sent in response to each Async Message. 🧹💖
Okay, here's the timing tea ☕. Technically the TMF servicing is finished at Step e). Data transfers for terminated tasks might still be going on even at the end of Step f). A TMF Response MUST NOT be sent by the target iSCSI layer before the end of Step e), and it MAY be sent at the end of Step e) even while those Data transfers are still outstanding, all the way until Step g). Step g) is the event that frees up any resources that were reserved to support those outstanding transfers. 🦋
4.2.3.5. Affected Tasks Shared across Standard and FastAbort Sessions
Okay so picture this: a target can support TaskReporting=FastAbort, and then it ends up with some sessions running TaskReporting=RFC3720 (RFC 3720 sessions) while other sessions run TaskReporting=FastAbort (FastAbort sessions), even while they're all touching a shared set of affected tasks (Section 4.2.3.2). That's a lot of drama, but it's real. 😭✨ If the issuing session is an RFC 3720 session, the target is FastAbort-capable, and the third-party affected session is a FastAbort session, then the target iSCSI layer SHOULD do the following:
- a) Between Steps c) and d) of the target behavior in Section 4.2.3.3, send an Asynchronous Message PDU with AsyncEvent=5 (Section 11.9) on each connection of each third-party session where at least one affected task is allegiant. If there are multiple affected LUs, send one Async Message PDU for each such LU on each connection that has at least one allegiant affected task. When sent, the LUN field in each Asynchronous Message PDU MUST match the LUN of its LU. 🎀
- b) After Step e) of the target behavior in Section 4.2.3.3, free up the affected TTTs (plus STags for iSER, if applicable) and their corresponding buffers, if any, once each associated NOP-Out acknowledgment comes back from the third-party initiator. That NOP-Out is the one it generated in response to each Async Message sent in Step a). 💜
If the issuing session is a FastAbort session, the target is FastAbort-capable, and the third-party affected session is an RFC 3720 session, the target iSCSI layer MUST NOT send Asynchronous Message PDUs on that third-party session to prompt the FastAbort behavior. Don't poke the RFC 3720 session, bestie. 🙅♀️💀
If the third-party affected session is a FastAbort session AND the issuing session is also a FastAbort session, the initiator in the third-party role MUST respond to each Async Message PDU with AsyncEvent=5, as defined in Section 11.9. Also, an initiator MAY get these Async Messages on a third-party affected session even when that session is a single-connection session. So don't be surprised when it happens. 🧚♀️
4.2.3.6. Rationale behind the FastAbort Semantics
Okay, the why. 🤓 There are basically three goals behind the semantics in Sections 4.2.3.3 and 4.2.3.4. 🌸
- a) Keeping an ordered command flow I_T nexus abstraction for the target SCSI layer, even with multi-connection sessions.
- Target iSCSI processing of a TMF Request has to keep up the single-flow illusion. The target behavior in Step b) of Section 4.2.3.3 and in Step a) of Section 4.2.3.4 is how this goal gets met. 🦋
- b) Keeping a single ordered response flow I_T nexus abstraction for the initiator SCSI layer, even with multi-connection sessions. This matters because one response (the TMF Response) can imply the status of other unfinished tasks from the initiator's point of view.
- The target has to make sure the initiator never sees "old" task responses (ones that were put on the wire chronologically before the TMF Response) after it has already seen the TMF Response. The target behavior in Step d) of Section 4.2.3.3 and in Step e) of Section 4.2.3.4 is how this goal gets met. 👑
- Whenever the result of a TMF action is visible across multiple I_T_L nexuses, [SAM2] requires the SCSI device server to trigger a UA on each of the other I_T_L nexuses. Once an initiator is told about such a UA, the application client on the receiving initiator is required to clear its task state (Clause 5.5 of [SAM2]) for the affected tasks. So it would be inappropriate to deliver a SCSI Response for a task after the task state has been cleared on the initiator, which is to say after the UA has been notified. Therefore, the UA notification carried in the first SCSI Response PDU on each affected third-party I_T_L nexus after the TMF action MUST NOT pass the affected task responses on any of the iSCSI sessions that access the LU. The target behavior in Step e) of Section 4.2.3.3 and in Step f) of Section 4.2.3.4 is how this goal gets met. 💅
- c) Draining all active TTTs that correspond to affected tasks in a deterministic fashion.
- Data-Out PDUs with stale TTTs that arrive after the tasks have been terminated can cause a buffer management problem even for traditional iSCSI implementations. For iSCSI/iSER implementations it is fatal for the connection. So either the termination of affected tasks should be postponed until the TTTs are retired (as in Step a) of Section 4.2.3.3), or the TTTs and the buffers should stay allocated beyond task termination so they can be deterministically freed up later (as in Steps c) and g) of Section 4.2.3.4). 🌈
There's one other notable optimization, and it's the plugging. 🧚 If every task on an I_T nexus is going to get aborted anyway (like with a target reset), there's no need to wait to receive all the commands just to fill the CmdSN holes. The target iSCSI layer can simply plug all the missing CmdSN slots and move on with TMF processing. The first objective (keeping a single ordered command flow) still gets met with this optimization, because the target SCSI layer only ever sees ordered commands. Slay, efficiency and correctness together. ✨💖
4.2.4. iSCSI Login ✨
okay so the login is basically the handshake bestie 🫶 its whole job is to get a TCP connection ready for iSCSI use, authenticate both parties, negotiate the session's parameters, and mark the connection as belonging to an iSCSI session 💖
A session is how a target knows about all the connections from a given initiator that belong to the same I_T nexus 🧚 (for more details on how a session relates to an I_T nexus, see Section 4.4.2).
Targets listen on a well-known TCP port or other TCP port for incoming connections 🔌 The initiator starts the login by connecting to one of these TCP ports.
As part of the login process, the initiator and target SHOULD authenticate each other and MAY set a security association protocol for the session 🔐 This can happen in lots of different ways and it's subject to negotiation, so see Section 12 for the deets.
To protect the TCP connection, an IPsec security association MAY be established before the Login Request 🛡️ For info on using IPsec security for iSCSI, see Section 9, [RFC3723], and [RFC7146].
The iSCSI Login Phase is carried through Login Requests and Responses 💬 Once suitable authentication has happened and the operational parameters are set, the session transitions to the Full Feature Phase and the initiator can start sending SCSI commands 🎀 The security policy for whether and how a target chooses to authorize an initiator is beyond the scope of this document, so that's not on us. For a more detailed description of the Login Phase, see Section 6.
The login PDU includes the ISID part of the session ID (SSID) 🍓 The target portal group that services the login is implied by which connection endpoint you picked. For a new session, the TSIH is zero, and as part of the response the target generates a TSIH.
During session establishment, the target identifies the SCSI initiator port (the "I" in the "I_T nexus") through the value pair (InitiatorName, ISID) 👑 We'll describe InitiatorName later in this section. Any persistent state on the target that's tied to a SCSI initiator port (like persistent reservations) is identified using this pair. Any state tied to the SCSI target port (the "T" in the "I_T nexus") is identified externally by the TargetName and Target Portal Group Tag (see Section 4.4.1). The ISID is subject to reuse restrictions because it's used to identify a persistent state (see Section 4.4.3) 🙈
Before the Full Feature Phase is established, only Login Request and Login Response PDUs are allowed. Login Requests and Responses MUST be used exclusively during login 🚫 On any connection, the Login Phase MUST immediately follow TCP connection establishment, and a subsequent Login Phase MUST NOT occur before tearing down the connection.
A target that receives any PDU except a Login Request before the Login Phase is started MUST immediately terminate the connection on which the PDU was received. Once the Login Phase has started, if the target receives any PDU except a Login Request, it MUST send a Login reject (with Status "invalid during login") and then disconnect. If the initiator receives any PDU except a Login Response, it MUST immediately terminate the connection. 💀
4.2.5. iSCSI Full Feature Phase 🎀
Once the two sides successfully conclude the login on the first (also called the leading) connection in the session, the iSCSI session is in the iSCSI Full Feature Phase 🥳 A connection is in the Full Feature Phase if the session is in the Full Feature Phase and the connection login has completed successfully. An iSCSI connection is not in the Full Feature Phase when:
- a) it does not have an established transport connection, or
- b) it has a valid transport connection, but a successful login was not performed or the connection is currently logged out.
In a normal Full Feature Phase, the initiator may send SCSI commands and data to the various LUs on the target by wrapping them in iSCSI PDUs that go over the established iSCSI session 📦
4.2.5.1. Command Connection Allegiance 🦋
For any iSCSI request issued over a TCP connection, the corresponding response and/or other related PDU(s) MUST be sent over the same connection. We call this "connection allegiance" 💜 If the original connection fails before the command is completed, the connection allegiance of the command may be explicitly reassigned to a different transport connection, as described in detail in Section 7.2.
So if an initiator issues a read command, the target MUST send the requested data, if any, followed by the status, to the initiator over the same TCP connection that was used to deliver the SCSI command. If an initiator issues a write command, the initiator MUST send the data, if any, for that command over the same TCP connection that was used to deliver the SCSI command. The target MUST return Ready To Transfer (R2T), if any, and the status over the same TCP connection that was used to deliver the SCSI command. Retransmission requests (SNACK PDUs), and the data and status that they generate, MUST also use the same connection 🔁
However, consecutive commands that are part of a SCSI linked command-chain task (see [SAM2]) MAY use different connections 🌈 Connection allegiance is strictly per command and not per task. During the iSCSI Full Feature Phase, the initiator and target MAY interleave unrelated SCSI commands, their SCSI data, and responses over the session 💅
4.2.5.2. Data Transfer Overview 🌸
Outgoing SCSI data (initiator-to-target user data or command parameters) gets sent as either solicited data or unsolicited data. Solicited data is sent in response to R2T PDUs. Unsolicited data can be sent as part of an iSCSI Command PDU ("immediate data") or in separate iSCSI data PDUs ✨
Immediate data is assumed to originate at offset 0 in the initiator SCSI write-buffer (outgoing data buffer). All other data PDUs have the buffer offset set explicitly in the PDU header 📍
An initiator may send unsolicited data up to FirstBurstLength (see Section 13.14) as immediate (up to the negotiated maximum PDU length), in a separate PDU sequence, or both. All subsequent data MUST be solicited. The maximum length of an individual data PDU or the immediate part of the first unsolicited burst MAY be negotiated at login 🎟️
The maximum amount of unsolicited data that can be sent with a command is negotiated at login through the FirstBurstLength (see Section 13.14) key. A target MAY separately enable immediate data (through the ImmediateData key) without enabling the more general (separate data PDUs) form of unsolicited data (through the InitialR2T key) 🧁
Unsolicited data for a write is meant to reduce the effect of latency on throughput, since no R2T is needed to start sending data 🚀 Immediate data is meant to reduce protocol overhead (both bandwidth and execution time). Iconic, honestly.
An iSCSI initiator MAY choose not to send unsolicited data, or to send only immediate data, or FirstBurstLength bytes of unsolicited data with a command. If any non-immediate unsolicited data is sent, the total unsolicited data MUST be either FirstBurstLength or all of the data, if the total amount is less than FirstBurstLength 📏
It is considered an error for an initiator to send unsolicited data PDUs to a target that operates in R2T mode (only solicited data is allowed) 🙅♀️ It is also an error for an initiator to send more unsolicited data, whether immediate or as separate PDUs, than FirstBurstLength.
An initiator MUST honor an R2T data request for a valid outstanding command (i.e., carrying a valid Initiator Task Tag) and deliver all the requested data, provided the command is supposed to deliver outgoing data and the R2T specifies data within the command bounds 🤝 The initiator action is unspecified for receiving an R2T request that specifies data, all or in part, outside of the bounds of the command.
A target SHOULD NOT silently discard data and then request retransmission through R2T 😤 Initiators SHOULD NOT keep track of the data transferred to or from the target (scoreboarding). SCSI targets perform residual count calculation to check how much data was actually transferred to or from the device by a command. This may differ from the amount the initiator sent and/or received, for reasons such as retransmissions and errors. Read or bidirectional commands implicitly solicit the transmission of the entire amount of data covered by the command. SCSI data packets are matched to their corresponding SCSI commands by using tags specified in the protocol 🏷️
In addition, iSCSI initiators and targets MUST enforce some ordering rules 📋 When unsolicited data is used, the order of the unsolicited data on each connection MUST match the order in which the commands on that connection are sent. Command and unsolicited data PDUs may be interleaved on a single connection as long as the ordering requirements of each are maintained. For example, command N + 1 MAY be sent before the unsolicited Data-Out PDUs for command N, but the unsolicited Data-Out PDUs for command N MUST precede the unsolicited Data-Out PDUs of command N + 1. A target that receives data out of order MAY terminate the session 🫣
4.2.5.3. Tags and Integrity Checks 🔍
Initiator tags for pending commands are unique initiator-wide for a session. Target tags are not strictly specified by the protocol. It is assumed that target tags are used by the target to tag (alone or in combination with the LUN) the solicited data. Target tags are generated by the target and "echoed" by the initiator 🪞
These mechanisms are designed to accomplish efficient data delivery along with a large degree of control over the data flow 🌊
As the Initiator Task Tag is used to identify a task during its execution, the iSCSI initiator and target MUST verify that all other fields used in task-related PDUs have values consistent with the values used at task instantiation, based on the Initiator Task Tag. For example, the LUN used in an R2T PDU MUST be the same as the one used in the SCSI Command PDU that instantiated the task. Using inconsistent field values is considered a protocol error 🚨
4.2.5.4. SCSI Task Management during iSCSI Full Feature Phase 👑
SCSI task management assumes that individual tasks and task groups can be aborted based solely on the task tags (for individual tasks) or the timing of the task management command (for task groups), and that the task management action is executed synchronously. That means no message involving an aborted task will be seen by the SCSI initiator after it receives the task management response 😌 In iSCSI, initiators and targets interact asynchronously over several connections, so iSCSI specifies the protocol mechanism and implementation requirements needed to present a synchronous SCSI view while using an asynchronous iSCSI infrastructure. It's giving careful engineering, periodt 💅🔥
that's the end of section 4.2.5 bestie 🎀
4.2.6. iSCSI Connection Termination ✨
Okay so an iSCSI connection can end in one of two ways: a transport connection shutdown or a transport reset 🌸 A transport reset counts as an exceptional event, so it's not the everyday exit we're going for 🙈
Graceful TCP connection shutdowns happen by sending TCP FINs 🦋 A graceful transport connection shutdown SHOULD only be initiated by either party when the connection is not in the iSCSI Full Feature Phase. A target MAY terminate a Full Feature Phase connection on internal exception events, but it SHOULD announce the fact through an Asynchronous Message PDU 📣 Connection termination with outstanding commands may require recovery actions, so keep that in mind 💅
If a connection gets terminated while in the Full Feature Phase, connection cleanup (see Section 7.14) is required before recovery starts 🧹 Doing cleanup first means the initiator and target won't receive stale PDUs after recovery. Main character energy for sure 👑
4.2.7. iSCSI Names 🎀
Both targets and initiators need names so they can be identified 🫶 Names also let iSCSI storage resources get managed no matter where they are (their address). An iSCSI Node Name is also the SCSI device name contained in the iSCSI node. The iSCSI name of a SCSI device is the principal object used when targets authenticate to initiators and initiators authenticate to targets. That same name is used to identify and manage iSCSI storage resources too 💖
iSCSI names must be unique within the operation domain of the end user. The operation domain of an IP network can be worldwide, though, so the iSCSI name formats are designed to be worldwide unique 🌈 To help naming authorities build worldwide unique names, iSCSI provides three name formats for different types of naming authorities. Three formats, one goal 🧚
iSCSI names are tied to iSCSI nodes, not to iSCSI network adapter cards. That way, swapping out a NIC doesn't force you to reconfigure all the SCSI and iSCSI resource allocation information 🙌
Some SCSI commands need protocol-specific identifiers to be communicated within SCSI CDBs. Check Section 2.2 for the definition of the SCSI port name/identifier for iSCSI ports 🔍
An initiator can discover the iSCSI Target Names it has access to, along with their addresses, using the SendTargets Text Request, or other techniques discussed in [RFC3721] 🕵️♀️
iSCSI equipment that needs discovery functions beyond SendTargets SHOULD implement iSNS (see [RFC4171]) for extended discovery management capabilities and interoperability. Now, [RFC3721] implies an SLP ([RFC2608]) implementation requirement, but SLP hasn't been widely implemented or deployed for use with iSCSI in practice 😭 So iSCSI implementations SHOULD NOT rely on SLP-based discovery interoperability. Not me being like "but the paperwork said so" 💀
4.2.7.1. iSCSI Name Properties 💜
Each iSCSI node MUST have an iSCSI name, whether it's an initiator, a target, or both 🍓 If an iSCSI node contains an iSCSI initiator node and an iSCSI target node, the iSCSI Initiator Name MUST be the same as the iSCSI Target Name for the contained Nodes. That way there's only one iSCSI Node Name for the iSCSI node overall. Check Section 9.2.1 for the related requirements on how to map CHAP names to iSCSI names in that situation 🔐
Initiators and targets MUST support receiving iSCSI names of up to the maximum length of 223 bytes 📏
The initiator MUST present both its iSCSI Initiator Name and the iSCSI Target Name it wants to connect to in the first Login Request of a new session or connection. The only exception is when a Discovery session (see Section 4.3) is being set up. In that case the iSCSI Initiator Name is still required, but the iSCSI Target Name MAY be omitted 🙈
iSCSI names have these properties:
- iSCSI names are globally unique. No two initiators or targets can have the same name.
- iSCSI names are permanent. An iSCSI initiator node or target node has the same name for its lifetime.
- iSCSI names do not imply a location or address. An iSCSI initiator or target can move or have multiple addresses. A change of address does not imply a change of name.
- iSCSI names do not rely on a central name broker; the naming authority is distributed.
- iSCSI names support integration with existing unique naming schemes.
- iSCSI names rely on existing naming authorities. iSCSI does not create any new naming authority.
The encoding of an iSCSI name has these properties:
- iSCSI names have the same encoding method, regardless of the underlying protocols.
- iSCSI names are relatively simple to compare. The algorithm for comparing two iSCSI names for equivalence does not rely on an external server.
- iSCSI names are composed only of printable ASCII and Unicode characters. iSCSI names allow international character sets, but uppercase characters are prohibited. The iSCSI stringprep profile [RFC3722] maps uppercase characters to lowercase and SHOULD be used to prepare iSCSI names from input that may include uppercase characters. No whitespace characters are used in iSCSI names; see [RFC3722] for details 🔤
- iSCSI names may be transported using both binary and ASCII-based protocols.
An iSCSI name really names a logical software entity and isn't tied to a port or other hardware that can be swapped out 💅 For example, an Initiator Name should name the iSCSI initiator node, not a particular NIC or HBA. When multiple NICs are used, they should generally all present the same iSCSI Initiator Name to the targets, because they're just paths to the same SCSI layer. In most operating systems, the named entity is the operating system image 🖥️
Same vibe for targets: a target name shouldn't be tied to hardware interfaces that can change. A target name should identify the logical target and must be the same for the target, no matter which physical portion is being addressed. This helps iSCSI initiators figure out that the two targets they discovered are really two paths to the same target 🛤️
The iSCSI name is designed to meet the functional requirements for Uniform Resource Names (URNs) [RFC1737] 🌟 For example, the name needs global scope, has to be independent of address or location, and has to be persistent and globally unique. Names must be extensible and scalable with the use of naming authorities. The name encoding should be both human and machine readable. See [RFC1737] for further requirements 🧠
4.2.7.2. iSCSI Name Encoding 🌷
An iSCSI name MUST be a UTF-8 (see [RFC3629]) encoding of a string of Unicode characters with these properties:
- It is in Normalization Form C (see "Unicode Normalization Forms" [UNICODE]).
- It only contains characters allowed by the output of the iSCSI stringprep template (described in [RFC3722]).
- The following characters are used for formatting iSCSI names:
- dash
('-'=U+002d) - dot
('.'=U+002e) - colon
(':'=U+003a)
- dash
- The UTF-8 encoding of the name is not larger than 223 bytes.
The stringprep process is described in [RFC3454], and iSCSI's use of it is described in [RFC3722] 🧩 Stringprep was designed by the Internationalized Domain Name (IDN) working group to turn human-typed strings into a format that can be compared as opaque strings. iSCSI names are expected to be used by administrators for things like system configuration, so characters that could cause human confusion between different iSCSI names (e.g., punctuation, spacing, diacritical marks) should be avoided, even when [RFC3722] allows them as stringprep processing output. The stringprep process also converts strings into equivalent strings of lowercase characters 🔡
The stringprep process doesn't need to be implemented if names are generated using only characters allowed as output by the stringprep processing specified in [RFC3722]. Those allowed characters include all ASCII lowercase and numeric characters, plus lowercase Unicode characters as specified in [RFC3722]. Once iSCSI names encoded in UTF-8 are "normalized" as described in this section, they can be safely compared byte for byte 🫶
4.2.7.3. iSCSI Name Structure 🦋
An iSCSI name has two parts: a type designator followed by a unique name string 🎀
iSCSI uses three existing naming authorities to build globally unique iSCSI names. The type designator in an iSCSI name indicates the naming authority the name is based on. The three iSCSI name formats are:
- a) iSCSI-Qualified Name: based on domain names to identify a naming authority
- b) NAA format Name: based on a naming format defined by [FC-FS3] for constructing globally unique identifiers, referred to as the Network Address Authority (NAA)
- c) EUI format Name: based on EUI names, where the IEEE Registration Authority helps form worldwide unique names (EUI-64 format)
The corresponding type designator strings currently defined are:
- a)
iqn.- iSCSI Qualified name - b)
naa.- Remainder of the string is an INCITS T11-defined Network Address Authority identifier, in ASCII-encoded hexadecimal - c)
eui.- Remainder of the string is an IEEE EUI-64 identifier, in ASCII-encoded hexadecimal
These three naming authority designators were considered sufficient when this document was written. The IETF may consider creating additional naming type designators for iSCSI and detail them in separate RFCs 🔭
The table below sums up the current SCSI transport protocols and their naming formats 📊
SCSI Transport Protocol Naming Format
+----------------------------+-------+-----+----+
| | EUI-64| NAA |IQN |
|----------------------------|-------|-----|----|
| iSCSI (Internet SCSI) | X | X | X |
|----------------------------|-------|-----|----|
| FCP (Fibre Channel) | | X | |
|----------------------------|-------|-----|----|
| SAS (Serial Attached SCSI) | | X | |
+----------------------------+-------+-----+----+4.2.7.4. Type "iqn." (iSCSI Qualified Name) 💅
okay so this type is giving "any organization that owns a domain name can use me" 🌸 It's super handy when an end user or a service provider wants to hand out iSCSI names for targets and/or initiators ✨
To make one of these, the person or org generating the name has to own a registered domain name 🎀 It doesn't even have to resolve to an address, lowkey. It just needs to be reserved so nobody else can generate iSCSI names with the same domain 🔒
Here's the tea: a domain can expire, get bought by someone else, or somehow end up used to make names by both owners 💀 So the domain name has to be qualified by a date during which the naming authority owned it. That's literally why the "iqn." format has a date code 🗓️
The iSCSI qualified name string is made of:
- The string "iqn.", which tells these names apart from "eui." formatted names 🧚
- A date code, in yyyy-mm format. This date MUST be a date during which the naming authority owned the domain name used in this format, and SHOULD be the first month in which the domain name was owned by this naming authority, at 00:01 GMT of the first day of that month. This date code uses the Gregorian calendar. All four digits in the year must be present. Both digits of the month must be present, with January == "01" and December == "12". The dash must be included. 📅
- A dot "."
- The reverse domain name of the naming authority (person or organization) creating this iSCSI name 🔁
- An optional, colon (:)-prefixed string within the character set and length boundaries that the owner of the domain name deems appropriate. This may contain product types, serial numbers, host identifiers, or software keys (e.g., it may include colons to separate organization boundaries). With the exception of the colon prefix, the owner of the domain name can assign everything after the reverse domain name as desired. It is the responsibility of the entity that is the naming authority to ensure that the iSCSI names it assigns are worldwide unique. For example, "Example Storage Arrays, Inc." might own the domain name "example.com". 🏢✨
The following are examples of iSCSI qualified names that might be generated by "EXAMPLE Storage Arrays, Inc." 👀
Naming String defined by
Type Date Auth "example.com" naming authority
+--++-----+ +---------+ +--------------------------------+
| || | | | | |
iqn.2001-04.com.example:storage:diskarrays-sn-a8675309
iqn.2001-04.com.example
iqn.2001-04.com.example:storage.tape1.sys1.xyz
iqn.2001-04.com.example:storage.disk2.sys1.xyz4.2.7.5. Type "eui." (IEEE EUI-64 Format) 🦋
The IEEE Registration Authority runs a service for assigning globally unique identifiers [EUI] 🌍 The EUI-64 format is what gets used to build a global identifier in other network protocols. For example, Fibre Channel defines a way to encode it into a WorldWideName. If you want to register for EUI identifiers, check out [OUI] 📚
The format is "eui." followed by an EUI-64 identifier (16 ASCII-encoded hexadecimal digits).
Example iSCSI name:
Type EUI-64 identifier (ASCII-encoded hexadecimal)
+--++--------------+
| || |
eui.02004567A425678DThe IEEE EUI-64 iSCSI name format might be used when a manufacturer is already registered with the IEEE Registration Authority and uses EUI-64 formatted worldwide unique names for its products. 🏭💖
More examples of name construction are discussed in [RFC3721]. 📖
4.2.7.6. Type "naa." (Network Address Authority) 💎
The INCITS T11 Framing and Signaling Specification [FC-FS3] defines a format called the Network Address Authority (NAA) format for building worldwide unique identifiers that use various identifier registration authorities. This identifier format is used by the Fibre Channel and SAS SCSI transport protocols. FC and SAS make up a big chunk of networked SCSI ports, so NAA is a super widely used format for SCSI transports 👑 The whole point of iSCSI supporting a direct representation of an NAA format Name is to make it easy to build a target device name that translates across multiple namespaces for a SCSI storage device with ports served by different transports. More specifically, it lets implementations use one NAA identifier as the basis for the SCSI device name for a SCSI target that has both SAS ports and iSCSI ports. It's giving cohesion 🫶
The iSCSI NAA naming format is "naa.", followed by an NAA identifier represented in ASCII-encoded hexadecimal digits.
An example of an iSCSI name with a 64-bit NAA value:
Type NAA identifier (ASCII-encoded hexadecimal)
+--++--------------+
| || |
naa.52004567BA64678DAn example of an iSCSI name with a 128-bit NAA value:
Type NAA identifier (ASCII-encoded hexadecimal)
+--++------------------------------+
| || |
naa.62004567BA64678D0123456789ABCDEFThe iSCSI NAA naming format might be used in an implementation when the infrastructure for generating NAA worldwide unique names is already in place because the device contains both SAS and iSCSI SCSI ports. 🧩
The NAA identifier in ASCII-hexadecimal representation has a maximum size of 32 characters (128-bit NAA format). So there's no issue with this naming format going over the maximum size for iSCSI Node Names. Phew 😮💨
4.2.8. Persistent State 🗂️
iSCSI does not require any persistent state maintenance across sessions. However, in some cases, SCSI requires persistent identification of the SCSI initiator port name (see Sections 4.4.2 and 4.4.3.) 🙈
iSCSI sessions do not persist through power cycles and boot operations. Gone when the power's gone 🔌
All iSCSI session and connection parameters are reinitialized on session and connection creation. Fresh start every time ✨
Commands persist beyond connection termination if the session persists and command recovery within the session is supported. However, when a connection is dropped, command execution, as perceived by iSCSI (i.e., involving iSCSI protocol exchanges for the affected task), is suspended until a new allegiance is established by the "TASK REASSIGN" task management function. See Section 11.5. It's like pausing a show until a new cast member shows up 🎬
4.2.9. Message Synchronization and Steering 🧵
iSCSI presents a mapping of the SCSI protocol onto TCP. This encapsulation happens by sending iSCSI PDUs of varying lengths. Unfortunately, TCP has no built-in way to signal message boundaries at the TCP layer 😭 iSCSI gets around this by putting the message length in the iSCSI message header. That marks the end of the current message and the start of the next one. Iconic problem-solving, honestly 👑
When IP packets arrive in order from the network, iSCSI message framing isn't an issue and messages are processed one after the other. But with IP packet reordering (i.e., frames being dropped), legacy TCP implementations store the "out of order" TCP segments in temporary buffers until the missing TCP segments arrive, and only then does the data have to be copied to the application buffers. In iSCSI, it's desirable to steer the SCSI data within those out-of-order TCP segments straight into the preallocated SCSI buffers instead of storing them in temporary buffers. That means less need for dedicated reassembly buffers, plus less latency and bandwidth wasted on extra copies. Efficient and unbothered 💅
Relying only on the "message length" from the iSCSI message header might make it impossible to find iSCSI message boundaries in later TCP segments if the segment carrying the message length gets lost. The missing TCP segment(s) must be received before any of the following segments can be steered to the correct SCSI buffers, because there's no way to figure out the iSCSI message boundaries without them. Since those segments can't be steered to the right place, they must be saved in temporary buffers and then copied to the SCSI buffers. Not ideal, bestie 🥲
Different schemes can recover synchronization. The details of any such scheme are beyond this protocol specification, but it's worth knowing that [RFC4297] gives an overview of the direct data placement problem on IP networks, and [RFC5046] specifies a protocol extension for iSCSI that supports this direct data placement goal. The rest of this document refers to any such direct data placement protocol usage as an example of a "Sync and Steering layer". 🧠
Under normal circumstances (no PDU loss or data reception out of order), iSCSI data steering can be done using the identifying tag and the data offset fields in the iSCSI header, plus the TCP sequence number from the TCP header. The identifying tag helps associate the PDU with a SCSI buffer address, while the data offset and TCP sequence number determine the offset within the buffer. Teamwork makes the dream work 🫶
4.2.9.1. Sync/Steering and iSCSI PDU Length 📏
When a large iSCSI message is sent, the TCP segment(s) containing the iSCSI header may be lost. The remaining TCP segment(s) up to the next iSCSI message must be buffered (in temporary buffers) because the iSCSI header that says which SCSI buffers the data should be steered to was lost. To keep the buffering small, it is recommended that the iSCSI PDU length be restricted to a small value (perhaps a few TCP segments in length). During login, each end of the iSCSI session specifies the maximum iSCSI PDU length it will accept. 🍓
4.3. iSCSI Session Types 🎀
iSCSI defines two types of sessions:
- a) Normal operational session - an unrestricted session.
- b) Discovery session - a session only opened for target discovery. The target MUST ONLY accept Text Requests with the SendTargets key and a Logout Request with reason "close the session". All other requests MUST be rejected. 🚫
The session type is defined during login with the SessionType=value parameter in the login command. 🌈
4.4. SCSI-to-iSCSI Concepts Mapping Model ✨
okay so this part is where we line up the SCSI words with the iSCSI words 🎀 The diagram below shows how several iSCSI nodes (targets, in this case) can live inside the same Network Entity and share Network Portals (IP addresses and TCP ports) 🦋 Way more complicated setups are possible too, but this one gives you the vibe. For the details on each piece, see Section 4.4.1 💅
+-----------------------------------+
| Network Entity (iSCSI Client) |
| |
| +-------------+ |
| | iSCSI Node | |
| | (Initiator) | |
| +-------------+ |
| | | |
| +--------------+ +--------------+ |
| |Network Portal| |Network Portal| |
| | 192.0.2.4 | | 192.0.2.5 | |
+-+--------------+-+--------------+-+
| |
| IP Networks |
| |
+-+--------------+-+--------------+-+
| |Network Portal| |Network Portal| |
| |198.51.100.21 | |198.51.100.3 | |
| | TCP Port 3260| | TCP Port 3260| |
| +--------------+ +--------------+ |
| | | |
| ------------------ |
| | | |
| +-------------+ +--------------+ |
| | iSCSI Node | | iSCSI Node | |
| | (Target) | | (Target) | |
| +-------------+ +--------------+ |
| |
| Network Entity (iSCSI Server) |
+-----------------------------------+4.4.1. iSCSI Architecture Model
okay this section zooms in on the bit of the iSCSI Architecture Model that matters most for how iSCSI and the SCSI Architecture Model vibe together 💖
- Network Entity 🌸 This is a device or gateway you can reach from the IP network. A Network Entity must have one or more Network Portals (see the "Network Portal" item below), and each of those can be used by some of the iSCSI nodes (see the next item) inside that Network Entity to get onto the IP network.
- iSCSI Node 🦋 This is a single iSCSI initiator or iSCSI target, or an instance of each. There are one or more iSCSI nodes within a Network Entity. The iSCSI node can be reached through one or more Network Portals (see below). An iSCSI node is identified by its iSCSI name (see Sections 4.2.7 and 13). Keeping the iSCSI name separate from the addresses the node uses is what lets multiple iSCSI nodes share the same addresses, and lets the same iSCSI node use multiple addresses. Iconic, honestly 👑
- An alias string may also be associated with an iSCSI node. The alias lets an organization attach a user-friendly string to the iSCSI name 🎀 However, the alias string is not a substitute for the iSCSI name, so don't get it twisted 🙈
- Network Portal 💜 This is a component of a Network Entity that has a TCP/IP network address and that may be used by an iSCSI node within that Network Entity for the connection(s) within one of its iSCSI sessions. In an initiator, it is identified by its IP address. In a target, it is identified by its IP address and its listening TCP port.
- Portal Groups 🧚 iSCSI supports multiple connections within the same session, and some implementations can combine connections in a session across multiple Network Portals. A portal group defines a set of Network Portals within an iSCSI node that together support coordinating a session with connections spanning those portals. Not all Network Portals within a portal group need to participate in every session connected through that portal group. One or more portal groups may provide access to an iSCSI node. Each Network Portal, as used by a given iSCSI node, belongs to exactly one portal group within that node. Portal groups are identified within an iSCSI node by a Portal Group Tag, which is a simple unsigned integer between 0 and 65535 (see Section 13.9). All Network Portals with the same Portal Group Tag in the context of a given iSCSI node are in the same portal group ✨
Both iSCSI initiators and iSCSI targets have portal groups, though only the iSCSI target portal groups are used directly in the iSCSI protocol (e.g., in SendTargets). For references to the initiator portal Groups, see Section 10.1.2.
- Portals within a portal group should support similar session parameters, because they may participate in a common session 🫶
The diagram below shows one example of this kind of setup on a target, and how a session that shares Network Portals within a portal group may be established 🌈
----------------------------IP Network---------------------
| | |
+----|----------------|----+ +----|---------+
| +---------+ +---------+ | | +---------+ |
| | Network | | Network | | | | Network | |
| | Portal | | Portal | | | | Portal | |
| +---------+ +---------+ | | +---------+ |
| | | | | | |
| | Portal | | | | Portal |
| | Group 1 | | | | Group 2 |
+--------------------------+ +--------------+
| | |
+--------|----------------|------------------|------------------+
| | | | |
| +----------------------------+ +----------------------------+ |
| | iSCSI Session (Target side)| | iSCSI Session (Target side)| |
| | | | | |
| | (TSIH = 56) | | (TSIH = 48) | |
| +----------------------------+ +----------------------------+ |
| |
| iSCSI Target Node |
| (within Network Entity, not shown) |
+---------------------------------------------------------------+4.4.2. SCSI Architecture Model
okay this section is all about how the SCSI Architecture Model [SAM2] lines up with the SCSI device, SCSI port and I_T nexus stuff, plus the iSCSI constructs from Section 4.4.1 🎀 It's giving "matching outfits" energy 👗
This relationship brings along implementation requirements if you want to conform to the SAM-2 model and the other SCSI operational functions 💅
Those requirements are detailed in Section 4.4.3 🔥
Here's the list of how SCSI architectural elements map to iSCSI 🌸
a) SCSI Device 🦋 This is the SAM-2 term for an entity that contains one or more SCSI ports connected to a service delivery subsystem and supports a SCSI application protocol. For example, a SCSI initiator device contains one or more SCSI initiator ports and zero or more application clients. A SCSI target device contains one or more SCSI target ports and one or more LUs. For iSCSI, the SCSI device is the component inside an iSCSI node that provides the SCSI functionality. So there can be at most one SCSI device within an iSCSI node. Access to the SCSI device can only be achieved in an iSCSI Normal operational session (see Section 4.3). The SCSI device name is defined to be the iSCSI name of the node and MUST be used in the iSCSI protocol 💖
b) SCSI Port 💜 This is the SAM-2 term for an entity in a SCSI device that provides the SCSI functionality for interfacing with a service delivery subsystem or transport. For iSCSI, the definitions of the SCSI initiator port and the SCSI target port are different 😭
SCSI initiator port: this maps to one endpoint of an iSCSI Normal operational session (see Section 4.3). An iSCSI Normal operational session gets negotiated through the login process between an iSCSI initiator node and an iSCSI target node. When that process completes successfully, a SCSI initiator port is created within the SCSI initiator device. The SCSI initiator port Name and SCSI initiator port Identifier are both defined to be the iSCSI Initiator Name together with (a) a label that identifies it as an initiator port name/identifier and (b) the ISID portion of the session identifier ✨
SCSI target port: this maps to an iSCSI target portal group. The SCSI Target Port Name and the SCSI Target Port Identifier are both defined to be the iSCSI Target Name together with (a) a label that identifies it as a target port name/identifier and (b) the Target Portal Group Tag 🌈
The SCSI port name MUST be used in iSCSI. When it's used in SCSI parameter data, the SCSI port name MUST be encoded as:
- the iSCSI name in UTF-8 format, followed by
- a comma separator (1 byte), followed by
- the ASCII character 'i' (for SCSI initiator port) or the ASCII character 't' (for SCSI target port) (1 byte), followed by
- a comma separator (1 byte), followed by
- a text encoding as a hex-constant (see Section 6.1) of the ISID (for SCSI initiator port) or the Target Portal Group Tag (for SCSI target port), including the initial 0X or 0x and the terminating null (15 bytes for iSCSI initiator port, 7 bytes for iSCSI target port).
The ASCII character 'i' or 't' is the label that tells you whether this port is a SCSI initiator port or a SCSI target port 🫶
c) I_T nexus 🧚 This is the relationship between a SCSI initiator port and a SCSI target port, according to [SAM2]. For iSCSI, this relationship is a session, defined as a relationship between an iSCSI initiator's end of the session (SCSI initiator port) and the iSCSI target's portal group. The I_T nexus can be identified by the combination of the SCSI port names, or by the iSCSI session identifier (SSID). iSCSI defines the I_T nexus identifier to be the tuple (iSCSI Initiator Name + ",i,0x" + ISID in text format, iSCSI Target Name + ",t,0x" + Target Portal Group Tag in text format). An uppercase hex prefix 0X may alternatively be used in place of 0x 🎀
NOTE: The I_T nexus identifier is not equal to the SSID 🙈
4.4.3. Consequences of the Model ✨
okay so this section is all about the implementation and behavior stuff that falls out once you map SCSI onto the iSCSI constructs we just covered 💅 between one SCSI initiator port and one SCSI target port, only one I_T nexus (session) can exist 🫶 [SAM2] doesn't allow parallel nexus relationships, so at any given time there's only one session with the same SSID between a given iSCSI initiator node and an iSCSI target node. so cute, right? 🎀
these assumptions lead to the following conclusions and requirements 🌸
ISID RULE: between a given iSCSI initiator and iSCSI target portal group (SCSI target port), there can only be one session with a given value for the ISID that identifies the SCSI initiator port. see Section 11.12.5.
the structure of the ISID that contains a naming authority component (see Section 11.12.5 and [RFC3721]) gives you a handy mechanism to help with compliance with the ISID RULE. see Section 10.1.1 💖
the iSCSI initiator node should manage the assignment of ISIDs before session initiation. the "ISID RULE" doesn't stop the same ISID from the same iSCSI initiator being used with different target portal groups on the same iSCSI target or on other iSCSI targets (see Section 10.1.1). this is basically like one SCSI initiator port having nexus relationships with multiple SCSI target ports on the same SCSI target device, or SCSI target ports on other SCSI target devices, which is iconic behavior 👑 it's also possible to have multiple sessions with different ISIDs going to the same target portal group. each of those sessions is treated as a different initiator, even when they come from the same initiator device 🧚 the same ISID can also be used by a different iSCSI initiator, because it's the iSCSI name together with the ISID that identifies the SCSI initiator port. main character energy 💅
NOTE: a consequence of the ISID RULE and the specification for the I_T nexus identifier is that two nexuses with the same identifier should never exist at the same time. 💀
TSIH RULE: the iSCSI target selects a non-zero value for the TSIH at session creation (when an initiator presents a 0 value at login). once it's selected, the same TSIH value MUST be used whenever the initiator or target refers to the session and a TSIH is required. no cap, this one is non-negotiable 🔥
4.4.3.1. I_T Nexus State
certain nexus relationships have explicit state (e.g., initiator-specific mode pages) that may need to be preserved by the device server [SAM2] in a LU through changes or failures in the iSCSI layer (e.g., session failures). so to get that state back, the iSCSI initiator should reestablish its session (re-login) to the same target portal group using the previous ISID 🧸 that means reinstating the session via iSCSI session reinstatement (Section 6.3.5), or continuing it via session continuation (Section 6.3.6). why? because the SCSI initiator port identifier and the SCSI target port identifier (or relative target port) together form the datum that the SCSI LU device server uses to identify the I_T nexus. it's all connected, bestie 🫶
4.4.3.2. Reservations
there are two reservation management methods defined in the SCSI standards 🔐 first up, reserve/release reservations, based on the RESERVE and RELEASE commands [SPC2]. second, persistent reservations, based on the PERSISTENT RESERVE IN and PERSISTENT RESERVE OUT commands [SPC3]. reserve/release reservations are obsolete [SPC3] and should not be used 🙈 persistent reservations are the suggested alternative; see Annex B of [SPC4].
state for persistent reservations is required to persist through changes and failures at the iSCSI layer that result in I_T nexus failures. see [SPC3] for the details and specific requirements 💜
in contrast, [SPC2] doesn't specify detailed persistence requirements for reserve/release reservation state after an I_T nexus failure. still, when reserve/release reservations are supported by an iSCSI target, the preferred approach is to preserve that state for iSCSI session reinstatement (see Section 6.3.5) or session continuation (see Section 6.3.6) ✨
two extra caveats apply to reserve/release reservations, so pay attention 👀
- retention of a failed session's reserve/release reservation state by an iSCSI target, even after that failed iSCSI session isn't reinstated or continued, may require an initiator to issue a reset (e.g., LOGICAL UNIT RESET; see Section 11.5) in order to remove that reservation state. ugh, reservations are so dramatic 😭
- reserve/release reservations may not behave as expected when persistent reservations are also used on the same LU. see the discussion of "Exceptions to SPC-2 RESERVE and RELEASE behavior" in [SPC4] 🎀
4.5. iSCSI UML Model
this section applies the UML modeling concepts from Section 3 to the iSCSI and SCSI Architecture Model we just went through in Section 4.4. it's giving diagrams 🦋
+----------------+
| Network Entity |
+----------------+
@ 1 @ 1
| |
+----------------------+ |
| |
| | 0..*
| +------------------+
| | iSCSI Node |
| +------------------+
| @ @
| | |
| +-----------+ =(a)= +-----------+
| | |
| | 0..1 | 0..1
| +------------------------+ +----------------------+
| | iSCSI Target Node | | iSCSI Initiator Node |
| +------------------------+ +----------------------+
| @ 1 @ 1
| +---------------+ |
| 1..* | | 1..*
| +-----------------------------+
| | Portal Group |
| +-----------------------------+
| O 1
| |
| | 1..*
| 1..* +------------------------+
+--------------------| Network Portal |
+------------------------+(a) each instance of an iSCSI node class MUST contain one iSCSI target node instance, one iSCSI initiator node instance, or both.
+----------------+
| Network Entity |
+----------------+
@ 1 @ 1
| | +------------------+
+---------------------+ | | iSCSI Session |
| | +------------------+
| | 0..* | SSID[1] |
| +--------------------+ | ISID[1] |
| | iSCSI Node | +------------------+
| +--------------------+ @ 1
| | iSCSI Node Name[1] | |
| | Alias [0..1] | | 0..*
| +--------------------+ +------------------+
| | | | iSCSI Connection |
| +--------------------+ +------------------+
| @ 1 @ 1 | CID[1] |
| | | +------------------+
| +-------------+ ==(b)== +---------+ 0..* |
| | 1 | 1 |
| +------------------------+ +------------------------+ |
| | iSCSI Target Node | | iSCSI Initiator Node | |
| +------------------------+ +------------------------+ |
| | iSCSI Target Name [1] | |iSCSI Initiator Name [1]| |
| +------------------------+ +------------------------+ |
| @ 1 @ 1 |
| | 1..* | 1..* |
| +--------------------------+ +------------------------+ |
| | Target Portal Group | | Initiator Portal Group | |
| +--------------------------+ +------------------------+ |
| |Target Portal Group Tag[1]| | Portal Group Tag[1] | |
| +--------------------------+ +------------------------+ |
| o 1 o 1 |
| +------------+ +----------+ |
| 1..* | | 1..* |
| +-------------------------+ |
| | Network Portal | |
| +-------------------------+ |
| 1..* | IP Address [1] | 1 |
+----------------| TCP Port [0..1] |<-----------------------+
+-------------------------+(b) each instance of an iSCSI node class MUST contain one iSCSI target node instance, one iSCSI initiator node instance, or both. however, in all scenarios, note that an iSCSI node MUST only have a single iSCSI name. note the related requirement in Section 4.2.7.1 🌈
4.6. Request/Response Summary
this section lists and briefly describes all the iSCSI PDU types, both requests and responses 📋
all iSCSI PDUs are built as a set of one or more header segments (basic and auxiliary) and zero or one data segments. the header group and the data segment may each be followed by a CRC (digest) 🍓
the basic header segment has a fixed length of 48 bytes 🧚
4.6.1. Request/Response Types Carrying SCSI Payload
4.6.1.1. SCSI Command
this request carries the SCSI CDB and all the other SCSI Execute Command [SAM2] procedure call IN arguments, like task attributes, Expected Data Transfer Length for one or both transfer directions (the latter for bidirectional commands), and a task tag (as part of the I_T_L_x nexus). the I_T_L nexus is derived by the initiator and target from the LUN field in the request, and the I_T nexus is implicit in the session identification 💅
on top of that, the SCSI Command PDU carries the info needed for iSCSI itself to work properly: the command sequence number (CmdSN) and the expected status sequence number (ExpStatSN) on the connection it's issued on 🫶
all or part of the SCSI output (write) data associated with the SCSI command may be sent as part of the SCSI Command PDU as a data segment. ngl this is so efficient 🚀
4.6.1.2. SCSI Response ✨
okay so the SCSI Response is the one that carries back all the OUT arguments from the SCSI Execute Command procedure call (see [SAM2]) 🎀 and also the return value of that same call 💅
It holds the residual counts from the operation if there are any 📊. It also tells you whether those counts are an overflow or an underflow 🌊. Then you get the SCSI status if the status is valid, or a response code (a non-zero return value for the Execute Command procedure call) if the status is not valid 🫶
When the status is valid and says the command ran but hit an exception (like a SCSI CHECK CONDITION 😭), the PDU data segment holds the matching sense data 🕵️♀️. Autosense ([SAM2]) is REQUIRED by iSCSI, no exceptions, periodt 💖
Some data segment content can also be linked to a non-zero response code ✨
And the SCSI Response PDU carries the extra stuff iSCSI needs to keep running smoothly 🧚 Here's the squad:
ExpDataSN- the number of Data-In PDUs the target has sent, so the initiator can double-check that every single one showed up 🔍StatSN- the status sequence number on this connection 🔢ExpCmdSN- the next command sequence number the target is expecting 🍓MaxCmdSN- the highest CmdSN the target will accept from this initiator 👑
4.6.1.3. Task Management Function Request
the Task Management Function Request is how an initiator gets to take the wheel and explicitly control one or more SCSI tasks or iSCSI functions 🦋 It carries a function identifier (aka which task management function to run) plus enough info to pin down exactly which task or task set to act on 🎯 Even if the task hasn't arrived yet, or got tossed out because of an error, it still works ✨
The referenced tag points to one specific task, if the function is about an individual task 🌸
The I_T_L nexus is what identifies task sets 💜 In iSCSI, the I_T_L nexus is identified by the LUN plus the session identification (the session is what identifies the I_T nexus) 🧚
For task sets, the CmdSN of the Task Management Function Request is how you figure out which tasks to act on: basically all the tasks tied to a LUN that have a CmdSN coming before the Task Management Function Request CmdSN 🕰️
For a task management function, the target is the one that coordinates the responses for the affected tasks and the Task Management Function Response 🫶
4.6.1.4. Task Management Function Response
the Task Management Function Response tells you the function is done 🎉 It includes how it finished (response and qualifier) and extra info for failure responses 🔥
Once the Task Management Function Response says the function is complete, the initiator will not get any more responses from the affected tasks 🚫 Done and dusted, bestie 💅
4.6.1.5. SCSI Data-Out and SCSI Data-In
SCSI Data-Out and SCSI Data-In are the main ways SCSI data payload moves between the initiator and the target 🚚 Each payload is tied to a specific SCSI command through the Initiator Task Tag 🏷️ For the target's convenience, outgoing solicited data also carries a Target Transfer Tag (copied from R2T) and the LUN 🎀 Every PDU has the payload length and the data offset, which is relative to the buffer address in the SCSI Execute Command procedure call 📦
In each direction, the transfer gets split into "sequences" ✂️ A sequence ends when the F bit is set 🏁
An outgoing sequence is either unsolicited (and only the first sequence can be unsolicited) or made up of all the Data-Out PDUs sent in response to an R2T 💫
Input sequences let the direction switch for bidirectional commands whenever that's needed 🔄
For input, the target can ask for a positive acknowledgment of the input data 👀 That's only for sessions that support error recovery, and it's done with the A bit in the SCSI Data-In PDU header 🌈
Data-In and Data-Out PDUs also carry the DataSN, so the initiator and target can spot missing PDUs (the ones that got discarded because of an error) 🕵️♀️
On top of that, the Data-In PDUs carry the StatSN too 🔢
Here's the efficiency flex 💪 To get a SCSI command processed with the fewest messages possible, the last SCSI Data-In PDU for a command can also include the status, but only if the status means it finished with no exceptions (no sense or response involved) ✨
4.6.1.6. Ready To Transfer (R2T)
R2T is how the SCSI target "requests" output data from the initiator 🙋♀️ It tells the initiator the offset of the requested data (relative to the buffer address from the Execute Command procedure call) and how long the solicited data should be 📏
So the target can match the resulting Data-Out to the right R2T, the R2T carries a Target Transfer Tag, and the initiator copies that tag into the solicited SCSI Data-Out PDUs 🔗 The protocol doesn't have any specific rules about what value these tags should be 🤷♀️ But the assumption is that together with the LUN, they'll let the target connect the data to its R2T 💖
R2T also carries the info iSCSI needs to work properly, like:
R2TSN(so an initiator can tell if an R2T went missing) 🕵️StatSN🔢ExpCmdSN🍓MaxCmdSN👑
4.6.2. Requests/Responses Carrying SCSI and iSCSI Payload
4.6.2.1. Asynchronous Message
Asynchronous Message PDUs carry SCSI asynchronous event notifications (AENs) and iSCSI asynchronous messages 📣
When it's carrying an AEN, the event details get reported as sense data in the data segment 🕵️♀️
4.6.3. Requests/Responses Carrying iSCSI-Only Payload
4.6.3.1. Text Requests and Text Responses
Text Requests and Responses are built for parameter negotiation and for future extensions 🧩
In the data segment, they carry text using a simple "key=value" syntax 📝
Text Requests/Responses can form extended sequences using the same Initiator Task Tag 🎀 The initiator uses the F (Final) flag bit in the Text Request header to say it's ready to end a sequence 🏁 The target uses the F bit in the Text Response header to say it agrees to the sequence ending 🤝
Text Requests and Responses also use the Target Transfer Tag to show whether an operation is continuing or starting fresh 🔁 A target that wants to keep going sets the Target Transfer Tag in a Text Response to a value other than the default 0xffffffff 🦋 If the initiator is also up for continuing, it copies that value into the Target Transfer Tag of the next Text Request 💜 And if the initiator wants to restart the current target negotiation from scratch, it sets the Target Transfer Tag to 0xffffffff 🌈
A complete exchange is always started by the initiator 🚀 But specific parameter negotiations can be kicked off by either the initiator or the target 🫶
4.6.3.2. Login Requests and Login Responses
Login Requests and Responses are only used during the Login Phase of each connection, to set up the session and connection parameters 🔐 (The Login Phase is a sequence of Login Requests and Responses carrying the same Initiator Task Tag 🏷️)
Each connection gets an arbitrarily chosen connection ID (CID) that has to be unique within its session 🆔
Just like Text Requests and Responses, Login Requests/Responses carry key=value text information with a simple syntax in the data segment 📝
The Login Phase goes through several stages (security negotiation and operational parameter negotiation) 🎢 Those stages are picked with two binary coded fields in the header: the Current Stage (CSG) and the Next Stage (NSG) 🔢 The appearance of the Next Stage is signaled by the "Transit" flag (T) 🚦
The very first Login Phase of a session is the leading login, and it's a big deal 👑 It decides some header fields, like the version number, the maximum number of connections, and the session identification 🪪
The leading login also sets the CmdSN initial value ✨
Each connection's StatSN is started by that connection's login 🔢
A Login Request can imply a logout (cleanup) of the connection it's logging into, which is a connection restart 🔄 It does this by using the same connection ID (CID) as an existing connection, plus the same session-identifying elements as the session the old connection belonged to 🧹
4.6.3.3. Logout Requests and Logout Responses
Logout Requests and Responses are for closing connections in an orderly way, whether that's for recovery or maintenance 🧹 A Logout Request can come right after a target prompt (through an Asynchronous Message) or on the initiator's own initiative 🙋♀️ When it's sent on the connection being logged out, no other request is allowed to follow it 🚫
The Logout Response says the connection or session cleanup is finished, and that no other responses will arrive on the connection (if it's received on the connection that's logging out) 🎉 It also tells you two things: how long the target will keep holding resources for recovery (like command execution that carries on over a new connection) in the Time2Retain field ⏳, and how long the initiator has to wait before starting recovery in the Time2Wait field ⏰
4.6.3.4. SNACK Request
With the SNACK Request, the initiator asks the target to resend numbered responses or data 🔁 One SNACK Request covers a contiguous set of missing items, called a run, all of one type 🧵 The type shows up in a type field in the PDU header 🏷️ A run is made of a starting item (StatSN, DataSN, or R2TSN) plus the number of missing Status, Data, or R2T PDUs 📊 For long Data-In sequences, the target can ask for a positive acknowledgment of the data sent, at predefined minimum intervals 👀 A SNACK Request with a type field that says ACK, along with the number of Data-In PDUs acknowledged, is how that positive acknowledgment gets sent 💌
4.6.3.5. Reject
Reject is how the target reports an iSCSI error condition (like a protocol problem or an unsupported option) 🚨 It uses a Reason field in the PDU header, and the complete header of the bad PDU goes into the Reject PDU data segment 🕵️♀️
4.6.3.6. NOP-Out Request and NOP-In Response
This request/response pair can be used by an initiator and a target as a "ping" 🏓 It checks that a connection or session is still active and all its parts are working ✅ Either side can trigger the ping 🙌 The side doing the triggering says it wants a reply by setting a value other than the default 0xffffffff in the matching Initiator/Target Transfer Tag 🎯
NOP-In/NOP-Out can also be used in a "unidirectional" way 💫 It conveys command, status, or data counter values to the initiator or target when there's no other "carrier" around and the other side needs an update 📬
5. SCSI Mode Parameters for iSCSI ✨
There are no iSCSI-specific mode pages 🌸
6. Login and Full Feature Phase Negotiation 🧚
okay so iSCSI parameters get negotiated when a session or connection is set up, using Login Requests and Responses (see Section 4.2.4). Then they get negotiated again during the Full Feature Phase (Section 4.2.5) with Text Requests and Responses 💅. Either way it's the same mechanism: an exchange of iSCSI-text-key=value pairs. Typing that out every time is exhausting, so the rest of this doc just calls them "keys" 🫶.
Keys are either declarative or require negotiation, and the key description tells you which one you're dealing with ✨.
For declarative keys, the declaring party sets a value for the key. The key spec says whether the initiator, the target, or both are allowed to declare it 🎀.
For keys that need negotiation, one party (the proposing party) offers a value or a set of values by putting key=value in the data part of a Login or Text Request or Response. The other party (the accepting party) picks one based on what was offered, then sends the chosen key=value back in the data part of the next Login or Text Response or Request 🦋. For most keys, both the initiator and the target can be proposing parties, so it's a total two-way vibe 👑.
Login happens in two stages: security negotiation and operational parameter negotiation. Both stages are optional, but at least one of them has to be present so that some mandatory parameters can get set 🌸. If security negotiation is there, it comes first, before operational parameter negotiation 🔒.
Moving between stages is controlled by the T (Transit) bit in the Login Request/Response PDU header. When the initiator sets T to 1, it's saying it would like to transition. The target agrees and picks the next stage once it's ready 🍓. The CSG field in the Login PDU header shows the current stage. During a transition, another field shows the next stage, proposed by the initiator and selected by the target 💜.
Text negotiation is how operational parameters get negotiated or declared, and it's driven by the F (Final) bit in the PDU header. During text negotiation, the initiator uses F to say it's ready to finish, and the target uses it to acquiesce to the end of negotiation 🙈.
Some key=value pairs won't fit in a single PDU, so the C (Continue) bit (in both Login and Text) is there to mean "more follows" 🌈.
Text negotiation has one more trick. A target can send a bigger chunk of data to an inquiring initiator. The target sets a Target Task Tag to act as a bookmark. When the initiator returns it, that means "go on" 🔥. If it gets reset to a "neutral value", that means "forget about the rest" 💀.
This section covers the types of keys and values, the syntax rules for forming parameters, and the negotiation schemes to use with each type of parameter 🎀.
6.1. Text Format 💌
The initiator and target send a set of key=value pairs encoded in UTF-8 Unicode. Every text key and text value in this document is case sensitive, so they get presented and interpreted exactly as they appear here, with no change of case 🔤.
These are the character symbols used for text items (the hexadecimal values are Unicode code points):
(a-z, A-Z) (0x61-0x7a, 0x41-0x5a) - letters
(0-9) (0x30-0x39) - digits
" " (0x20) - space
"." (0x2e) - dot
"-" (0x2d) - minus
"+" (0x2b) - plus
"@" (0x40) - commercial at
"_" (0x5f) - underscore
"=" (0x3d) - equal
":" (0x3a) - colon
"/" (0x2f) - solidus or slash
"[" (0x5b) - left bracket
"]" (0x5d) - right bracket
null (0x00) - null separator
"," (0x2c) - comma
"~" (0x7e) - tildeKey=value pairs can span PDU boundaries 🧩. An initiator or target that sends partial key=value text in a PDU says that more text is coming by setting the C bit to 1 in the Text or Login Request, or in the Text or Login Response. Data segments in a series of PDUs where the C bit is set to 1 and which ends with a PDU whose C bit is set to 0, or a single PDU whose C bit is set to 0, have to be considered as forming a single logical-text-data-segment (LTDS) 🎀.
Every key=value pair, including the last or only pair in an LTDS, MUST be followed by one null (0x00) delimiter 🛑.
A key-name is whatever comes before the first "=" in the key=value pair. The word "key" gets used a lot in this document in place of "key-name" 🗝️.
A value is whatever comes after the first "=" in the key=value pair, up to the end of that pair. The null delimiter is not included 💜.
Here are the definitions the rest of the document relies on 📚:
standard-label: a string of one or more characters made of letters, digits, dot, minus, plus, commercial at, or underscore. A standard-label MUST begin with a capital letter and must not exceed 63 characters ✨.key-name: a standard-label 🏷️.text-value: a string of zero or more characters made of letters, digits, dot, minus, plus, commercial at, underscore, slash, left bracket, right bracket, or colon 🌷.iSCSI-name-value: a string of one or more characters made of minus, dot, colon, or any character allowed by the output of the iSCSI stringprep template as specified in [RFC3722] (see also Section 4.2.7.2) 🌐.iSCSI-local-name-value: a UTF-8 string where no null characters are allowed. This encoding is for localized (internationalized) aliases 🌍.boolean-value: the string "Yes" or "No" ✅.hex-constant: a hexadecimal constant written as a string that starts with "0x" or "0X", followed by one or more digits or the letters a, b, c, d, e, f, A, B, C, D, E, or F. Hex-constants are used to encode numerical values or binary strings. When they encode numerical values, using lots of leading 0 digits is discouraged 🙃. The string after 0X (or 0x) is a base16 number that starts with the most significant base16 digit, continues with every other digit in decreasing order of significance, and ends with the least significant base16 digit. When hex-constants encode binary strings, they have an implicit byte-length that counts four bits for every hexadecimal digit, including leading zeroes. For example, a hex-constant of n hexadecimal digits has a byte-length of (the integer part of) (n + 1)/2 🧮.decimal-constant: an unsigned decimal number that is either the digit 0 or a string of one or more digits starting with a non-zero digit. Decimal-constants are used to encode numerical values or binary strings. They can only encode binary strings if the string length is explicitly specified, since there is no implicit length for decimal strings. Decimal-constants MUST NOT be used for parameter values if the values can be equal to or greater than 2**64 (numerical), or for binary strings that can be longer than 64 bits 🚫.base64-constant: a Base64 constant written as a string that starts with "0b" or "0B", followed by 1 or more digits, letters, plus signs, slashes, or equals signs. The encoding is done according to [RFC4648] 🍬.numerical-value: an unsigned integer always less than 2**64, encoded as a decimal-constant or a hex-constant. Unsigned integer arithmetic applies to numerical-values 🔢.large-numerical-value: an unsigned integer that can be larger than or equal to 2**64, encoded as a hex-constant or base64-constant. Unsigned integer arithmetic applies to large-numerical-values 🐘.numerical-range: two numerical-values separated by a tilde, where the value on the right of the tilde must not be lower than the value on the left 📏.regular-binary-value: a binary string not longer than 64 bits, encoded as a decimal-constant, hex-constant, or base64-constant. Its length is either specified by the key definition or is the implicit byte-length of the encoded string 🧃.large-binary-value: a binary string longer than 64 bits, encoded as a hex-constant or base64-constant. Its length is either specified by the key definition or is the implicit byte-length of the encoded string 🧱.binary-value: a regular-binary-value or a large-binary-value. Operations on binary values are key-specific 🫧.simple-value: a text-value, iSCSI-name-value, boolean-value, numerical-value, numerical-range, or binary-value 🍭.list-of-values: a sequence of text-values separated by a comma 📝.
If nothing else is specified, the maximum length of a simple-value (not counting its encoded form) is 255 bytes, not including the delimiter (comma or zero byte) 📐.
Any iSCSI target or initiator MUST support receiving at least 8192 bytes of key=value data in a negotiation sequence. When proposing or accepting authentication methods that explicitly require support for very long authentication items, the initiator and target MUST support receiving at least 64 kilobytes of key=value data 🚨
6.2. Text Mode Negotiation 💖
okay so during login (and honestly, whenever after that too 💅), some session or connection parameters get either declared or negotiated through a little back-and-forth of text. 🦋
The initiator kicks things off with a Text or Login Request, and it's the one who says when it's ready to wrap up. It does this by setting the F bit to 1 and keeping it at 1 in a Text Request, or by setting the T bit in the Login Request. ✨ Here's the catch: negotiation text can spill across PDU boundaries, so any Text or Login Request or Text or Login Response PDU with the C bit set to 1 MUST NOT have the F bit or T bit set to 1. no cap, that's the only way the chat stays in order 🌸
the C bit is the "more text coming" signal. if it's on, the F and T bits are off-limits. bestie, don't mix them up 🙈
When a target gets a Text or Login Request with the C bit set to 1, it MUST answer with a Text or Login Response that has no data segment (DataSegmentLength 0). When an initiator gets a Text or Login Response with the C bit set to 1, it MUST answer with a Text or Login Request that has no data segment (DataSegmentLength 0). It's like a little "k, got it, keep going" 🫶
A target or initiator SHOULD NOT use a Text or Login Response, or a Text or Login Request, with no data segment (DataSegmentLength 0), unless a general or key-specific negotiation rule explicitly says it has to. so empty messages are kinda a no-go unless the rules literally demand one 🙅♀️
There MUST NOT be more than one outstanding Text Request or Text Response PDU on an iSCSI connection. An outstanding PDU here just means one that the remote iSCSI side hasn't acknowledged yet. one at a time, periodt 💜
A declaration looks like this:
Declarer-> <key>=<valuex>And the general shape of text negotiation looks like this:
Proposer-> <key>=<valuex>
Acceptor-> <key>={<valuey>|NotUnderstood|Irrelevant|Reject}So a declaration is a one-way text exchange (unless the receiver doesn't understand the key), while a negotiation is a two-way exchange. it's giving proposal, then response 🎀
The proposer or declarer can be the initiator or the target, and the acceptor is the other one. Targets aren't stuck just answering whatever key=value pairs the initiator throws out, either. A target is allowed to propose key=value pairs of its own. main character energy for both sides 👑
All negotiations are explicit, meaning the result MUST only be based on values that were newly exchanged or declared. There are no implicit proposals, so if a proposal wasn't made, you can't expect a reply. Conservative design also means you shouldn't lean on default values when using some other value would have serious consequences. 😭
The value being proposed or declared can be a numerical-value, a numerical-range (a lower and an upper value, both integers, separated by a tilde), a binary value, a text-value, an iSCSI-name-value, an iSCSI-local-name-value, a boolean-value (Yes or No), or a list of comma-separated text-values. A range, a large-numerical-value, an iSCSI-name-value, and an iSCSI-local-name-value MAY ONLY be used if they're explicitly allowed. An accepted value can be a numerical-value, a large-numerical-value, a text-value, or a boolean-value. ✨
If a key just isn't relevant to the current negotiation, the acceptor may answer with the constant "Irrelevant" for any type of negotiation. Good news: a negotiation does NOT count as failed if the answer is "Irrelevant". 🌈 This is for when someone proposes a bunch of keys, and the acceptor's pick for one of them makes the others pointless. Here's how that looks:
I->T InitialR2T=No,ImmediateData=Yes,FirstBurstLength=4192
T->I InitialR2T=Yes,ImmediateData=No,FirstBurstLength=Irrelevant
I->T X-rdname-vkey1=(bla,alb,None), X-rdname-vkey2=(bla,alb)
T->I X-rdname-vkey1=None, X-rdname-vkey2=IrrelevantAny key the acceptor doesn't understand can be ignored without messing up the basic function. BUT the answer for a key it doesn't understand MUST be key=NotUnderstood. Also, NotUnderstood is a valid answer for both declarative and negotiated keys. The general iSCSI vibe is that comprehension comes before processing for any iSCSI key. So a proposer of an iSCSI key (negotiated or declarative) in a text key exchange MUST be able to properly handle a NotUnderstood response. being ready for rejection is a whole mood 🫠
How you handle a NotUnderstood response depends on where the key is specified and whether it's declarative or negotiated. An iSCSI implementation MUST comprehend all text keys defined in this document. So getting NotUnderstood back on any of these text keys MUST be considered a protocol error, and it gets handled accordingly. 💀 For all the other "later" keys (text keys defined in later specifications), a NotUnderstood answer wraps up the negotiation for a negotiated key. For a declarative key, though, NotUnderstood just tells the declarer that the receiver doesn't comprehend it. 🧚
Either way, a NotUnderstood answer always requires that the protocol behavior tied to that key not be used within the key's scope (connection or session), by either side. no exceptions, no drama 🍓
The constants "None", "Reject", "Irrelevant", and "NotUnderstood" are reserved, and they MUST ONLY be used the way they're described here. Breaking this rule is a protocol error. That includes using "Reject", "Irrelevant", and "NotUnderstood" as proposed values, so don't you dare 🙅♀️
"Reject" and "Irrelevant" are legit negotiation options where they're allowed, but using them a lot is discouraged. A negotiation counts as complete as soon as the acceptor has sent the key value pair, even if the value is "Reject", "Irrelevant", or "NotUnderstood". Sending the key again would be a renegotiation, and for lots of keys that's straight-up forbidden. 🙈
If the acceptor sends "Reject" as its answer, the negotiated key stays at its current value (or the default, if nothing was ever set). And if the current value isn't acceptable to the proposer on the connection or in the session where it was sent, the proposer MAY choose to terminate the connection or session. the exit door is always there 🚪✨
All keys in this document MUST be supported by iSCSI initiators and targets when they're used as specified here. And if they're used as specified, these keys MUST NOT be answered with NotUnderstood. 🌸
Implementers can make up new private keys by prefixing them with X- followed by their (reverse) domain name, or they can register new public keys with IANA. For example, the entity that owns the domain example.com could issue:
X-com.example.bar.foo.do_something=3Each new public key added during standardization MUST define the acceptable responses to the key, including NotUnderstood as appropriate. Now, unlike [RFC3720], this document prohibits the X# prefix for new public keys. Based on iSCSI implementation experience, there's no longer any need for a standard name prefix for keys that allow a NotUnderstood response. Note that NotUnderstood will generally have to be allowed for new public keys for backwards compatibility, and for private X- keys too. So the name prefix "X#" in new public key-names doesn't mean anything anymore. To avoid confusion, new public key-names MUST NOT begin with an "X#" prefix. 🎀
Implementers MAY also introduce new values, but ONLY for new keys or authentication methods (see Section 12) or digests (see Section 13.1). ✨
Whenever parameter actions or acceptance depend on other parameters, the dependency rules and parameter sequence must be specified along with the parameters. 🧩
In the Login Phase (see Section 6.3), every stage is its own separate negotiation. In the Full Feature Phase, a Text Request/Response sequence counts as a negotiation. Negotiations MUST be handled as atomic operations. So, all the negotiated values go into effect once the negotiation wraps up in agreement, or they get ignored if the negotiation fails. it's all or nothing, bestie 💅
Some parameters come with integrity rules (for example, parameter-x must not exceed parameter-y, or parameter-u not being 1 implies that parameter-v be Yes). Whenever it's needed, the integrity rules get specified along with the keys. Checking for compliance with an integrity rule must only be done after all the parameters are available (both the existing ones and the newly negotiated ones). An iSCSI target MUST perform integrity checking before the new parameters take effect. An initiator MAY perform integrity checking too. 🔍
An iSCSI initiator or target MAY terminate a negotiation that doesn't wrap up within an implementation-specific reasonable time or number of exchanges, but it SHOULD allow at least six (6) exchanges. give the people a fair shot 🫶
6.2.1. List Negotiations ✨
In list negotiation, the originator sends a list of values (which may include "None"), in order of preference. 🌈
The responding party MUST respond with the same key and the first value that it supports (and is allowed to use for that specific originator), picked from the originator's list. 🎀
The constant "None" MUST always be used to indicate a missing function. But "None" is only a valid selection if it was explicitly proposed. When "None" is proposed as a selection item in a negotiation for a key, it tells the responder that not supporting anything related to that key is legal. And if "None" ends up as the negotiation result for such a key, it means the key-specific semantics aren't operational for that negotiation scope (connection or session). 🧚
If an acceptor doesn't understand a particular value in a list, it MUST ignore it. If an acceptor doesn't support, doesn't understand, or isn't allowed to use any of the proposed options with a specific originator, it may use the constant "Reject" or terminate the negotiation. And selecting a value that was never proposed MUST be handled by the originator as a protocol error. 💀
6.2.2. Simple-Value Negotiations 🌸
For simple-value negotiations, the accepting party MUST answer with the same key. The value it picks becomes the negotiation result. 💖
If someone proposes a value that isn't admissible (for example, it's outside the specified bounds), that MAY be answered with the constant "Reject". Otherwise, the acceptor MUST select an admissible value. 🙅♀️
If the acceptor selects a value that isn't admissible under the selection rules, that's considered a protocol error. The selection rules are key-specific, so check the key's rules 🔍
For a numerical range, the selected value MUST be an integer within the proposed range, or "Reject" (if the range is unacceptable). 🦋
For Boolean negotiations (keys that take the values "Yes" or "No"), the accepting party MUST answer with the same key and the result of the negotiation, but only when the received value doesn't determine that result by itself. The last value transmitted becomes the negotiation result. The rules for picking the answer are written as Boolean functions of the value received, plus whatever value the accepting party would have picked if it had a choice. 🧠
Specifically, there are two cases where answers are OPTIONAL:
- The Boolean function is "AND" and the value "No" is received. The outcome of the negotiation is "No".
- The Boolean function is "OR" and the value "Yes" is received. The outcome of the negotiation is "Yes".
Responses are REQUIRED in all other cases, and the value the acceptor chooses and sends becomes the outcome of the negotiation. ✨
6.3. Login Phase 🧚
okay so the Login Phase is basically the glow-up setup for an iSCSI connection between an initiator and a target 💅 It creates a brand-new session, or it adds a connection to a session that already exists. It also sets the iSCSI protocol parameters and the security parameters, and it makes sure the initiator and target both verify each other 🔐✨
The Login Phase only happens through Login Requests and Responses 🎀 The whole thing counts as one single task, so it gets one Initiator Task Tag, kind of like how linked SCSI commands work 🦋
There MUST NOT be more than one outstanding Login Request or Login Response on an iSCSI connection. An outstanding PDU here just means one the other iSCSI side hasn't acknowledged yet 🙈
The default MaxRecvDataSegmentLength is used during login 🌸
Here's the order the Login Phase messages go in 🍓
- Login initial request
- Login partial response (optional)
- More Login Requests and Responses (optional)
- Login Final-Response (mandatory)
The initial Login Request on any connection MUST include the InitiatorName key=value pair ✨ The initial Login Request for the first connection of a session MAY also include the SessionType key=value pair 💜 And for any connection in a session whose type is not "Discovery", the first Login Request MUST also include the TargetName key=value pair 🫶
The Login Final-Response is the one that either accepts or rejects the Login Request 👑
The Login Phase MAY include a SecurityNegotiation stage and a LoginOperationalNegotiation stage. It MUST include at least one of them, though the stage it does include MAY be empty apart from the mandatory names 🌈
The Login Requests and Responses have a field called CSG that tells you which negotiation stage you're in (SecurityNegotiation or LoginOperationalNegotiation). If both stages get used, SecurityNegotiation MUST come before LoginOperationalNegotiation, no exceptions bestie 😭
Some operational parameters can also be negotiated outside of login, through Text Requests and Responses 🦋
Authentication-related security keys (Section 12) MUST be completely negotiated inside the Login Phase 🔥 For underlying IPsec security, check out Section 9.3, [RFC3723], and [RFC7146]. iSCSI's own in-protocol security is only authentication during the Login Phase, so that's the whole story there 🎀
In some environments, a target or an initiator just isn't interested in authenticating the other one 🙄 That's okay, because it's possible to skip authentication through the Login Request and Response ✨
The initiator and target MAY want to negotiate iSCSI authentication parameters 💅 Once that negotiation wraps up, the channel is considered secure 🔐
Most negotiation keys are only allowed in one specific stage. The keys used during SecurityNegotiation are listed in Section 12, and the keys used during LoginOperationalNegotiation are covered in Section 13. Only a limited set of keys (marked as Any-Stage in Section 13) may be used in either stage 🧚
Every Login Request or Response belongs to one specific stage, and that stage decides which negotiation keys are allowed with it 🌸 Sending a key that isn't allowed in the current stage counts as a protocol error, so don't do it, babe 💀
Stage transitions happen through a command exchange (request/response) that carries the T bit and the same CSG code 🦋 During that exchange, the target picks the next stage using the Next Stage code (NSG) 🫶 The selected NSG MUST NOT exceed the value the initiator stated. The initiator can ask for a transition whenever it's ready, but the target can only respond with a transition after the initiator has proposed one 💖
In a negotiation sequence, the T bit settings in one Login Request-Login Response pair have no effect on the T bit settings of the next pair 🌈 So an initiator that set the T bit to 1 and got a T bit of 0 back is totally allowed to send its next request with the T bit set to 0 ✨
When the initiator asks for a transition and the target acknowledges it, both sides switch over to the selected stage 🎀
Targets MUST NOT submit parameters that require an additional initiator Login Request in a Login Response with the T bit set to 1. Not allowed, no matter how much you want to 🙅♀️
Stage transitions during login (including entering and exit) are only possible as outlined in the following table 🍓
+-----------------------------------------------------------+
|From To -> | Security | Operational | FullFeature |
| | | | | |
| V | | | |
+-----------------------------------------------------------+
| (start) | yes | yes | no |
+-----------------------------------------------------------+
| Security | no | yes | yes |
+-----------------------------------------------------------+
| Operational | no | no | yes |
+-----------------------------------------------------------+The Login Final-Response that accepts a Login Request can only show up as a response to a Login Request that has the T bit set to 1 🔥 Both the request and the response MUST indicate FullFeaturePhase as the next phase via the NSG field. 💅
Neither the initiator nor the target should try to declare or negotiate a parameter more than once during login 🙈 The exception is responses to specific keys that explicitly allow repeated declarations, like TargetAddress 🧚 An attempt to renegotiate or redeclare parameters that aren't specifically allowed MUST be detected by the initiator and target. If the target detects one, the target MUST respond with a Login reject (initiator error) 😭 If the initiator detects one, the initiator MUST drop the connection 💀
6.3.1. Login Phase Start ✨
The Login Phase kicks off with a Login Request from the initiator to the target 🦋 The initial Login Request includes:
- Protocol version supported by the initiator
- iSCSI Initiator Name and iSCSI Target Name
- ISID, TSIH, and connection IDs
- Negotiation stage that the initiator is ready to enter
A login can create a brand-new session, or it can add a connection to one that already exists 🌈 For a given iSCSI initiator node (picked only by its InitiatorName) and a given iSCSI target (defined by an iSCSI TargetName and a Target Portal Group Tag), the login results follow this table 🍓
+----------------------------------------------------------------+
|ISID | TSIH | CID | Target Action |
+----------------------------------------------------------------+
|new | non-zero | any | fail the login |
| | | | ("session does not exist") |
+----------------------------------------------------------------+
|new | zero | any | instantiate a new session |
+----------------------------------------------------------------+
|existing| zero | any | do session reinstatement |
| | | | (see Section 6.3.5) |
+----------------------------------------------------------------+
|existing| non-zero | new | add a new connection to |
| | existing | | the session |
+----------------------------------------------------------------+
|existing| non-zero |existing| do connection reinstatement |
| | existing | | (see Section 7.1.4.3) |
+----------------------------------------------------------------+
|existing| non-zero | any | fail the login |
| | new | | ("session does not exist") |
+----------------------------------------------------------------+The target decides whether something is "existing" or "new" 👑
Optionally, the Login Request may also include:
- Security parameters OR
- iSCSI operational parameters AND/OR
- The next negotiation stage that the initiator is ready to enter
The target can answer the login in these ways 💖
- Login Response with Login reject. This is an immediate rejection from the target. It makes the connection terminate, and it terminates the session too if this is the first (or only) connection of a new session 💀 The T bit, the CSG field, and the NSG field are reserved here.
- Login Response with Login accept as the Final-Response (T bit set to 1, and the NSG in both request and response is set to FullFeaturePhase). The response includes the protocol version the target supports and the session ID, and it may include iSCSI operational or security parameters (depending on the current stage) 🎀
- Login Response with Login accept as a partial response (NSG not set to FullFeaturePhase in both request and response). This marks the start of a negotiation sequence 🌸 The response includes the protocol version the target supports, plus either security or iSCSI parameters (when no security mechanism is chosen) that the target supports 🦋
If the initiator decides to skip the SecurityNegotiation stage, it sends the Login with the CSG set to LoginOperationalNegotiation 🙈 The target may reply with a Login Response saying it's unwilling to accept the connection without SecurityNegotiation (see Section 11.13), and it will terminate the connection with an Authentication failure response (see Section 11.13.5) 💀
If the initiator is willing to negotiate iSCSI security, but doesn't want to make the initial parameter proposal, and it can accept a connection without iSCSI security, it issues the Login with the T bit set to 1, the CSG set to SecurityNegotiation, and the NSG set to LoginOperationalNegotiation 🧚 If the target is also ready to skip security, the Login Response only contains the TargetPortalGroupTag key (see Section 13.9), with the T bit set to 1, the CSG set to SecurityNegotiation, and the NSG set to LoginOperationalNegotiation 🫶
An initiator that wants to operate without iSCSI security, with all the operational parameters at their default values, issues the Login with the T bit set to 1, the CSG set to LoginOperationalNegotiation, and the NSG set to FullFeaturePhase 🔥 If the target is also ready to forego security and can finish its LoginOperationalNegotiation, the Login Response has the T bit set to 1, the CSG set to LoginOperationalNegotiation, and the NSG set to FullFeaturePhase in the next stage 🌈
During the Login Phase, the iSCSI target MUST return the TargetPortalGroupTag key with the first Login Response PDU that it is allowed to do so with (that is, the first Login Response issued after the first Login Request with the C bit set to 0) for all session types 👑 The TargetPortalGroupTag key value tells you which iSCSI portal group is servicing the Login Request PDU 🍓 If reconfiguring iSCSI portal groups is a concern in your environment, the iSCSI initiator should use this key to confirm it really started the Login Phase with the intended target portal group 🦋✨
6.3.2. iSCSI Security Negotiation ✨
Okay bestie, security negotiation is basically the initiator and target doing a vibe check on each other 🔐 The exchange follows whichever authentication method got picked during the negotiation phase, and it all runs on key=value parameters riding along in Login Requests and Responses 💖
Here's how an initiator-directed negotiation goes:
- The initiator sends a Login Request with an ordered list of the options it supports (authentication algorithm). The list goes in the initiator's order of preference 🎀 The initiator MAY also send private or public extension options ✨
- The target MUST reply with the first option in the list it supports and is allowed to use for the specific initiator, unless it doesn't support any, in which case it MUST answer with "Reject" (see Section 6.2). The parameters are encoded in UTF-8 as
key=value. For security parameters, see Section 12. 🫶 - When the initiator feels ready to wrap up the
SecurityNegotiationstage, it sets the T bit to 1 and the NSG to whatever it wants the next stage to be 🦋 The target then sets the T bit to 1 and sets the NSG to the next stage in the Login Response, once it's done sending its security keys. The next stage is the one the target picked. If the next stage isFullFeaturePhase, the target MUST reply with a Login Response with the TSIH value. 🔥
If the security negotiation fails at the target, the target MUST send the appropriate Login Response PDU 💀 If it fails at the initiator, the initiator SHOULD close the connection 🙈
Quick aside 📝 the negotiation can also be directed by the target, if the initiator does support security but isn't ready to be the one proposing options. Check Appendix B for an example 🧚
6.3.3. Operational Parameter Negotiation during the Login Phase
Operational parameter negotiation during the Login Phase MAY be done:
- starting with the first Login Request if the initiator does not propose any security/integrity option.
- starting immediately after the security negotiation if the initiator and target perform such a negotiation.
Operational parameter negotiation MAY involve several Login Request-Login Response exchanges, all started and terminated by the initiator 💜 The initiator MUST indicate its intent to terminate the negotiation by setting the T bit to 1, and the target sets the T bit to 1 on the last response 🌸
Even when the initiator says it wants to switch stages by setting the T bit to 1 in a Login Request, the target MAY respond with a Login Response that has the T bit set to 0 🙃 In that case, the initiator SHOULD keep setting the T bit to 1 in the Login Requests it sends after that (even empty ones), until the target sends a Login Response with the T bit set to 1, or sends a key that requires the initiator to set the T bit to 0.
Some session-specific parameters can only be set during the Login Phase of the first connection of a session (i.e., one begun by a Login Request that contains a zero-valued TSIH). That's the leading Login Phase, and it's where you'd set things like the maximum number of connections allowed for this session 👑
A session is operational once it has at least one connection in the Full Feature Phase. New or replacement connections can only be added to a session after it's operational ✨
For operational parameters, see Section 13.
6.3.4. Connection Reinstatement
Connection reinstatement is when an initiator logs in with an ISID-TSIH-CID combo that might still be active from the target's point of view 😳 That causes the connection tied to the CID to get implicitly logged out, and a new Full Feature Phase iSCSI connection takes its place (with the same CID). Thus, the TSIH in the Login Request PDU MUST be non-zero, and the CID does not change during a connection reinstatement 💅 The Login Request does the logout job for the old connection if an explicit logout wasn't done earlier. In sessions with a single connection, this may mean opening a second connection with the sole purpose of cleaning up the first 🧹 Targets MUST support opening a second connection even when they don't support multiple connections in the Full Feature Phase if ErrorRecoveryLevel is 2, and SHOULD support opening a second connection if ErrorRecoveryLevel is less than 2.
If the operational ErrorRecoveryLevel is 2, connection reinstatement enables future task reassignment ✨ If the operational ErrorRecoveryLevel is less than 2, connection reinstatement is just replacing the old CID, without enabling task reassignment. In this case, all the tasks that were active on the old CID must be immediately terminated without further notice to the initiator 🥲
The initiator connection state MUST be CLEANUP_WAIT (Section 8.1.3) when the initiator attempts a connection reinstatement.
In practical terms, besides the implicit logout of the old connection, reinstatement is the same as a new connection login 🫶
6.3.5. Session Reinstatement, Closure, and Timeout
Session reinstatement is when an initiator logs in with an ISID that might still be active from the target's point of view for that initiator 🎀 That implicitly logs out the session tied to the ISID and reinstates a new iSCSI session in its place (with the same ISID). So the TSIH in the Login PDU MUST be zero to signal session reinstatement. Session reinstatement also causes all the tasks that were active on the old session to be immediately terminated by the target, without further notice to the initiator 💀
The initiator session state MUST be FAILED (Section 8.3) when the initiator attempts a session reinstatement.
Session closure is an event that counts as one of these:
- a successful "session close" logout.
- a successful "connection close" logout for the last Full Feature Phase connection, when no other connection in the session is waiting for cleanup (Section 8.2) and no tasks in the session are waiting for reassignment.
Session timeout is an event that happens when the last connection state timeout expires and no tasks are waiting for reassignment. That takes the session to the FREE state (see the session state diagrams in Section 8.3) 🌈
6.3.5.1. Loss of Nexus Notification
The iSCSI layer tells the SCSI layer about the "I_T nexus loss" notification whenever any one of these happens:
- successful completion of session reinstatement
- session closure event
- session timeout event
Certain SCSI object clearing actions may happen because of that notification in the SCSI end nodes, as documented in Appendix E 🧚
6.3.6. Session Continuation and Failure
Session continuation is the process where the state of a session that already exists keeps getting used, either by connection reinstatement (Section 6.3.4) or by adding a connection with a new CID 🦋 Either of those actions ties the new transport connection to the session state.
Session failure is an event where the last Full Feature Phase connection reaches the CLEANUP_WAIT state (Section 8.2) or finishes a successful recovery logout. That makes all the active tasks that used to belong to the connection start waiting for task reassignment 😭
6.4. Operational Parameter Negotiation outside the Login Phase
Some operational parameters MAY be negotiated outside (after) the Login Phase 🌸
Parameter negotiation in the Full Feature Phase happens through Text Requests and Responses 💬 Operational parameter negotiation MAY involve several Text Request-Text Response exchanges, and they all use the same Initiator Task Tag. The initiator always starts and ends each of these exchanges. The initiator MUST indicate its intent to finish the negotiation by setting the F bit to 1, and the target sets the F bit to 1 on the last response ✨
If the target answers a Text Request that has the F bit set to 1 with a Text Response that has the F bit set to 0, the initiator should keep sending Text Requests (even empty ones) with the F bit set to 1 for as long as it still wants to finish the negotiation, until it gets a Text Response with the F bit set to 1. Answering a Text Request with the F bit set to 1 with an empty response (no key=value pairs) that has the F bit set to 0 is discouraged 🙅♀️
Even when the initiator says it wants to finish the negotiation by setting the F bit to 1 in a Text Request, the target MAY respond with a Text Response that has the F bit set to 0 🙃 In that case, the initiator SHOULD keep setting the F bit to 1 in the Text Requests it sends after that (even empty ones), until the target sends the final Text Response with the F bit set to 1. And note that in that same situation, the target SHOULD NOT respond with an empty (no key=value pairs) Text Response with the F bit set to 0, because that kind of response may make the initiator give up on the negotiation 😬
Targets MUST NOT submit parameters that need an additional initiator Text Request inside a Text Response with the F bit set to 1 🚫
In a negotiation sequence, the F bit settings in one Text Request-Text Response pair don't affect the F bit settings in the next pair. An initiator that has the F bit set to 1 in a request and gets answered with an F bit setting of 0 can send its next request with the F bit set to 0 🦋
Whenever the target responds with the F bit set to 0, it MUST set the Target Transfer Tag to a value other than the default 0xffffffff 🎀
An initiator MAY reset an operational parameter negotiation by sending a Text Request with the Target Transfer Tag set to 0xffffffff, after it has received a response with a Target Transfer Tag set to a value other than 0xffffffff. A target may reset an operational parameter negotiation by answering a Text Request with a Reject PDU 🔄
Neither the initiator nor the target should try to declare or negotiate a parameter more than once during any negotiation sequence, except for responses to specific keys that explicitly allow repeated key declarations (e.g., TargetAddress). If the target detects an attempt like that, the target MUST respond with a Reject PDU with a reason of "Protocol Error" 🚨 The initiator MUST reset the negotiation as outlined above.
Parameters negotiated by a text exchange negotiation sequence only become effective after the negotiation sequence is completed. 💖
7. iSCSI Error Handling and Recovery ✨
7.1. Overview 🦋
7.1.1. Background ✨
okay so two things basically kicked off the design of most of the error recovery stuff in iSCSI 💅
- an iSCSI PDU can fail the digest check and get dropped even though TCP already received it 😭 the iSCSI layer must optionally be allowed to recover those dropped PDUs.
- a TCP connection can die at literally any point during the data transfer 💀 all the active tasks must optionally be allowed to keep going on a different TCP connection inside the same session.
implementations get a LOT of freedom here 🎀 they decide how much recovery to support, when to use it, and which mechanisms get the job done. only the externally visible actions of the recovery mechanisms must be standardized so everyone stays interoperable 🫶
this section gives a general model for recovery so everything works together. see Appendix D for more on how the model may be implemented. compliant implementations don't have to match the implementation details of this model as presented, but their external behavior must correspond to the externally observable characteristics of the presented model. it's giving "you do you, as long as the outside looks right" 🦋
7.1.2. Goals 🎯
these are the major design goals of the iSCSI error recovery scheme:
- let implementations meet different requirements by defining a collection of error recovery mechanisms they can pick from 🧚
- make sure any two implementations supporting different sets of error recovery capabilities can still interoperate 💜
- define the error recovery mechanisms so command ordering holds even in the face of errors, for initiators that demand ordering 🔥
- no additions in the fast path, but moderate complexity in the error recovery path is totally fine 💅
- stop both the initiator and target from trying to recover the same set of PDUs at the same time 🙈 for example, there must be a clear "error recovery functionality distribution" between the initiator and target
7.1.3. Protocol Features and State Expectations 🧠
the initiator mechanisms for error recovery are:
- a) NOP-Out to probe sequence numbers of the target (Section 11.18)
- b) Command retry (Section 7.2.1)
- c) Recovery R2T support (Section 7.8)
- d) Requesting retransmission of status/data/R2T using the SNACK facility (Section 11.16)
- e) Acknowledging the receipt of the data (Section 11.16)
- f) Reassigning the connection allegiance of a task to a different TCP connection (Section 7.2.2)
- g) Terminating the entire iSCSI session to start afresh (Section 7.1.4.4)
the target mechanisms for error recovery are:
- a) NOP-In to probe sequence numbers of the initiator (Section 11.19)
- b) Requesting retransmission of data using the recovery R2T feature (Section 7.8)
- c) SNACK support (Section 11.16)
- d) Requesting that parts of read data be acknowledged (Section 11.7.2)
- e) Allegiance reassignment support (Section 7.2.2)
- f) Terminating the entire iSCSI session to force the initiator to start over (Section 7.1.4.4)
for any outstanding SCSI command, it is assumed that iSCSI, working together with SCSI at the initiator, can keep enough info to rebuild the command PDU, and that outgoing data is available (in host memory) for retransmission while the command is outstanding. it's also assumed that at the target, incoming data (read data) MAY be kept for recovery, or it can be reread from a device server. 📦
it's further assumed that a target will keep the "status and sense" for a command it has executed if it supports status retransmission. 🫧
a target that agrees to support data retransmission is expected to be prepared to retransmit the outgoing data (i.e., Data-In) on request until either the status for the completed command is acknowledged or the data in question has been separately acknowledged. 💌
7.1.4. Recovery Classes 🪜
iSCSI enables these classes of recovery, in order of increasing scope of affected iSCSI tasks:
- within a command (i.e., without requiring command restart)
- within a connection (i.e., without requiring the connection to be rebuilt, but perhaps requiring command restart)
- connection recovery (i.e., perhaps requiring connections to be rebuilt and commands to be reissued)
- session recovery
the recovery scenarios in the rest of this section are representative rather than exclusive. in every case, they detail the lowest recovery class that MAY be attempted. the implementer is left to decide when to escalate to the next recovery class and/or which recovery classes to implement. both the iSCSI target and initiator MAY escalate the error handling to an error recovery class, which impacts a larger number of iSCSI tasks in any of the cases identified in the following discussion. 🧩
in all classes, the implementer can choose to defer errors to the SCSI initiator (with an appropriate response code). in that case the task, if any, has to be removed from the target, and all the side effects, such as ACA, must be considered. ⚠️
the use of within-connection and within-command recovery classes MUST NOT be attempted before the connection is in the Full Feature Phase. 🚫
in the detailed description of the recovery classes, the mandating terms (MUST, SHOULD, MAY, etc.) indicate normative actions to be executed if the recovery class is supported (see Section 7.1.5 for the related negotiation semantics) and used. 📜
7.1.4.1. Recovery Within-command 🔁
at the target, these cases lend themselves to within-command recovery:
Lost data PDU, realized through one of the following:
- a) Data digest error, dealt with as specified in Section 7.8, using the option of a recovery R2T
- b) Sequence reception timeout (no data or partial-data-and-no-F-bit), considered an implicit sequence error and dealt with as specified in Section 7.9, using the option of a recovery R2T
- c) Header digest error, which manifests as a sequence reception timeout or a sequence error, dealt with as specified in Section 7.9, using the option of a recovery R2T
at the initiator, these cases lend themselves to within-command recovery:
Lost data PDU or lost R2T, realized through one of the following:
- a) Data digest error, dealt with as specified in Section 7.8, using the option of a SNACK
- b) Sequence reception timeout (no status) or response reception timeout, dealt with as specified in Section 7.9, using the option of a SNACK
- c) Header digest error, which manifests as a sequence reception timeout or a sequence error, dealt with as specified in Section 7.9, using the option of a SNACK
to avoid a race with the target, which may already have a recovery R2T or a termination response on its way, an initiator SHOULD NOT originate a SNACK for an R2T based on its internal timeouts (if any). recovery in this case is better left to the target. 🏁
the timeout values used by the initiator and target are outside the scope of this document. a sequence reception timeout is generally a large enough value to let the data sequence transfer finish. ⏳
7.1.4.2. Recovery Within-connection 🔗
at the initiator, these cases lend themselves to within-connection recovery:
- a) Requests not acknowledged for a long time. Requests are acknowledged explicitly through the ExpCmdSN or implicitly by receiving data and/or status. The initiator MAY retry non-acknowledged commands as specified in Section 7.2.
- b) Lost iSCSI numbered response. It is recognized by either identifying a data digest error on a Response PDU or a Data-In PDU carrying the status, or receiving a Response PDU with a higher StatSN than expected. In the first case, digest error handling is done as specified in Section 7.8, using the option of a SNACK. In the second case, sequence error handling is done as specified in Section 7.9, using the option of a SNACK.
at the target, these cases lend themselves to within-connection recovery:
- Status/Response not acknowledged for a long time. The target MAY issue a NOP-In (with a valid Target Transfer Tag or otherwise) that carries the next status sequence number it is going to use in the StatSN field. This helps the initiator detect any missing StatSN(s) and issue a SNACK for the status. 📣
the timeout values used by the initiator and the target are outside the scope of this document. ⏱️
7.1.4.3. Connection Recovery 🔌
at an iSCSI initiator, these cases lend themselves to connection recovery:
- a) TCP connection failure: The initiator MUST close the connection. It then MUST either implicitly or explicitly log out the failed connection with the reason code "remove the connection for recovery" and reassign connection allegiance for all commands still in progress associated with the failed connection on one or more connections (some or all of which MAY be newly established connections) using the "TASK REASSIGN" task management function (see Section 11.5.1). For an initiator, a command is in progress as long as it has not received a response or a Data-In PDU including status.
Note: The logout function is mandatory. However, a new connection establishment is only mandatory if the failed connection was the last or only connection in the session. 📝
- b) Receiving an Asynchronous Message that indicates that one or all connections in a session have been dropped. The initiator MUST handle it as a TCP connection failure for the connection(s) referred to in the message.
at an iSCSI target, these cases lend themselves to connection recovery:
- TCP connection failure: The target MUST close the connection and, if more than one connection is available, the target SHOULD send an Asynchronous Message that indicates that it has dropped the connection. Then, the target will wait for the initiator to continue recovery. 🤝
7.1.4.4. Session Recovery 🧹
session recovery should be performed when all other recovery attempts have failed. very simple initiators and targets MAY perform session recovery on all iSCSI errors and rely on recovery on the SCSI layer and above. 🫠
session recovery implies closing all TCP connections, internally aborting all executing and queued tasks for the given initiator at the target, terminating all outstanding SCSI commands with an appropriate SCSI service response at the initiator, and restarting a session on a new set of connection(s) (TCP connection establishment and login on all new connections). 🌈
for possible clearing effects of session recovery on SCSI and iSCSI objects, refer to Appendix E. 🎀
7.1.5. Error Recovery Hierarchy
okay bestie, so all the error recovery stuff we just covered gets stacked into a hierarchy 🪜✨ it's organized this way so it's easier to understand and the implementation doesn't get too messy 🧠 with just a few clear recovery levels, interoperability is way easier to pull off 🫶 here's how it works:
- a) each level is a superset of the level below it 👑 so level 1 means you get everything in level 0, plus more
- b) as a corollary, going higher means more sophistication and possibly more resources too 📈 more power, more responsibility, iykyk 💅
- c) supporting error recovery level "n" gets advertised and negotiated by each iSCSI entity by swapping the text key
ErrorRecoveryLevel=n. the lower of the two exchanged values becomes the operational ErrorRecoveryLevel for the session 🤝
here's the hierarchy diagram, it's giving pyramid 🔺
+
/ \
/ 2 \ <-- Connection recovery
+-----+
/ 1 \ <-- Digest failure recovery
+---------+
/ 0 \ <-- Session failure recovery
+-------------+and this table lists the error recovery (ER) capabilities you can expect from implementations at each level 📋🩷
+-------------------+--------------------------------------------+
|ErrorRecoveryLevel | Associated Error Recovery Capabilities |
+-------------------+--------------------------------------------+
| 0 | Session recovery class |
| | (Session Recovery) |
+-------------------+--------------------------------------------+
| 1 | Digest failure recovery (see Note below) |
| | plus the capabilities of ER Level 0 |
+-------------------+--------------------------------------------+
| 2 | Connection recovery class |
| | (Connection Recovery) |
| | plus the capabilities of ER Level 1 |
+-------------------+--------------------------------------------+Note: digest failure recovery is made up of two recovery classes: the Within-connection recovery class (recovery within-connection) and the Within-command recovery class (recovery within-command). two classes, one vibe 🌸
when an originator proposes a defined ErrorRecoveryLevel value in a text negotiation, the originator MUST support the functionality for that proposed value, and ALSO the functionality for every defined value numerically less than it 🧩 when a responder sends back a defined ErrorRecoveryLevel value, the responder MUST support the functionality for the level it's accepting 💖
if either party tries to use error recovery functionality beyond what was negotiated, those recovery attempts MAY fail, unless the two parties have an a priori agreement (outside the scope of this document) to support it 🙈
implementations MUST support error recovery level "0", but the rest are OPTIONAL to implement 🌈 here's the incremental sophistication each level step adds:
+-------------------+--------------------------------------------+
| Level Transition | Incremental Requirement |
+-------------------+--------------------------------------------+
| 0->1 | PDU retransmissions on the same connection |
+-------------------+--------------------------------------------+
| 1->2 | Retransmission across connections and |
| | allegiance reassignment |
+-------------------+--------------------------------------------+7.2. Retry and Reassign in Recovery
this section gives you the tea on two really important (and kinda related) iSCSI protocol features used in error recovery ☕✨
7.2.1. Usage of Retry
so, by resending the same iSCSI Command PDU (that's the "retry" 🔁) when there's no command acknowledgment (an ExpCmdSN update) or response, the initiator is basically trying to "plug" the holes it thinks exist in the CmdSN ordering on the target end 🕳️ discarded command PDUs (because of digest errors) can be what created those holes, so it's not totally random 🧐
retry MUST NOT be used for anything other than plugging command sequence gaps. especially, it cannot be used to request PDU retransmissions from a target 🚫 if you need a currently allegiant command in progress to get a PDU resent, you can use the SNACK mechanism described in Section 11.16, but using SNACK is OPTIONAL 🫧
if initiators accidentally retry allegiant commands that are already in progress while they're plugging gaps (aka the target never saw any holes in the CmdSN ordering), the targets just silently ignore the duplicates, as specified in Section 4.2.2.1 🤫
when an iSCSI command gets retried, the command PDU MUST carry the original Initiator Task Tag, the original operational attributes (flags, function names, LUN, CDB, etc.), and the original CmdSN 📦 the retried command MUST also go out on the same connection as the original, unless the original connection was already successfully logged out 🔐
7.2.2. Allegiance Reassignment
by sending a "TASK REASSIGN" task management request (Section 11.5.1), the initiator says it wants to keep going with a command that's already active (but has no current connection allegiance) as part of connection recovery 💫 this means it's requesting a new connection allegiance for the command, aiming to tie it to the connection where the task management request is being sent 🎀 before the reassignment is attempted for a task, an implicit or explicit Logout with the reason code "remove the connection for recovery" (see Section 11.14.1) MUST be successfully completed for the previous connection the task was allegiant to 🔚
when the target reassigns connection allegiance for a command, the target SHOULD pick up the command from where it currently is 🏃♀️ for example, when reassigning read commands, the target SHOULD use the ExpDataSN field from the Task Management Function Request (which must be set to 0 if no data was transferred) and finish the read command by sending the remaining data and then sending (or resending) the status 🎯 the ExpDataSN acknowledges all data sent up to, but NOT including, the Data-In PDU and/or R2T whose DataSN (or R2TSN) equals the ExpDataSN 📍 targets can still choose to send/receive all unacknowledged data, or all of the data, during a reassignment if they can't recover or keep accurate state 🛟 initiators MUST NOT later ask for data retransmission through a Data SNACK for PDUs numbered below the ExpDataSN (aka anything before the acknowledged sequence number) 🙅♀️
for every type of command, a reassignment request means the initiator still considers the task in progress, and the target must wrap up the task properly if it returns the "Function complete" response to the reassignment request 🎬 that might involve retransmitting data/R2T/status PDUs as needed, but it MUST include (re)transmitting the status PDU 📨
supporting allegiance reassignment is OPTIONAL for targets 💅 this capability gets negotiated through the ErrorRecoveryLevel text key during login. if a target doesn't support allegiance reassignment, it MUST respond with the task management response code "Task allegiance reassignment not supported" 🙅 if the target does support it, but the task is still allegiant to a different connection, or a successful recovery Logout of the previously allegiant connection never happened, the target MUST respond with the task management response code "Task still allegiant" 🚧
if the target supports allegiance reassignment, the task management response to the reassignment request MUST be issued BEFORE the reassignment becomes effective ⏳
if a SCSI command that involves data input gets reassigned, any SNACK Tag it holds for a final response from the original connection gets deleted, and the default value of 0 MUST be used instead 🗑️✨
7.3. Usage of Reject PDU in Recovery
targets MUST NOT implicitly terminate an active task by sending a Reject PDU for any PDU exchanged during the life of the task 🛑 if the target decides to end the task, it has to return a Response PDU (SCSI, Text, Task, etc.) to conclude it 🏁 if the task was never active before the Reject (aka the Reject is on the command PDU itself), targets should not send any further responses, because the command is being discarded anyway 🗑️
so, by the rule above, the initiator can eventually expect a response after getting Rejects, as long as the Reject is for a PDU other than the command PDU itself 🎯 the non-command Rejects are only really useful for diagnostic value (aka logging the errors), but initiators can also use them when making retransmission decisions 📝
the CmdSN of a rejected command PDU (if it's a non-immediate command) MUST NOT be considered received by the target, so a command sequence gap has to be assumed for that CmdSN, even if the CmdSN of the rejected PDU can be reliably figured out 🕳️ once the initiator gets the Reject, it MUST plug the CmdSN gap so it can keep using the session 🔧 the gap can be plugged either by sending a command PDU with that same CmdSN, or by aborting the task (see Section 7.11 for how an abort can plug a CmdSN gap) 🩹
when a data PDU gets rejected and its DataSN can be figured out, a target MUST advance the ExpDataSN for the current data burst if it's generating a recovery R2T 📈 a target MAY advance its ExpDataSN if it doesn't try to recover the lost data PDU 🌷
7.4. Error Recovery Considerations for Discovery Sessions
7.4.1. ErrorRecoveryLevel for Discovery Sessions
the ErrorRecoveryLevel key doesn't have to be negotiated for Discovery sessions (aka sessions that negotiated "SessionType=Discovery") 🔍 that's because the default value of 0 is both necessary and sufficient for them 💯 tbh though, some legacy iSCSI implementations might still try to negotiate the ErrorRecoveryLevel key on Discovery sessions 🦕 when the remote side makes that negotiation attempt, a compliant iSCSI implementation MUST propose a value of 0 (zero) in response 🫶 so the operational ErrorRecoveryLevel for Discovery sessions MUST be 0 💜 this naturally follows from the functionality constraints that Section 4.3 puts on Discovery sessions ✨
7.4.2. Reinstatement Semantics for Discovery Sessions ✨
okay so Discovery sessions are meant to be pretty short-lived 🦋 Initiators aren't really expected to open multiple Discovery sessions to the same iSCSI Network Portal. An initiator can reuse the same iSCSI Initiator Name and ISID when it's connecting to different targets and/or different portal groups. Section 10.1.1 covers this, and it's actually encouraged as conservative ISID reuse 🌸
The ISID RULE from Section 4.4.3 says there must not be more than one session with a matching 4-tuple: <InitiatorName, ISID, TargetName, TargetPortalGroupTag>. The spirit of that rule applies to Discovery sessions just like it does to Normal sessions, BUT some Discovery sessions are different from Normal ones in two big ways 👀
- a) Appendix C lets a Discovery session be set up without a
TargetNamekey in the Login Request PDU (we'll call these "Unnamed" Discovery sessions 💅). So there's no target node context to enforce the ISID RULE with. - b) Portal groups only exist in the context of a target node. If the
TargetNamekey is NULL-valued (aka not specified), theTargetPortalGroupTagcan't be figured out, so the ISID RULE can't be enforced that way either 😭
The next two sections cover Unnamed Discovery sessions and Named Discovery sessions. Let's go 🫶
7.4.2.1. Unnamed Discovery Sessions
for Unnamed Discovery sessions, targets can't see the TargetName OR the TargetPortalGroupTag, so they can't enforce the ISID RULE the usual way. That's why this rule exists 💖
UNNAMED ISID RULE: Targets MUST enforce the uniqueness of the following 4-tuple for Unnamed Discovery sessions: <InitiatorName, ISID, NULL, TargetAddress>. Here's what this uniqueness requirement implies 🎀
Targets SHOULD allow concurrent establishment of one Discovery session with each of its Network Portals by the same initiator port with a given iSCSI Node Name and an ISID. And if the same initiator port sets up concurrent Discovery sessions to other Network Portals, each one MUST be treated as independent. Basically, one session MUST NOT reinstate the other 🧚
A new Unnamed Discovery session with a matching <InitiatorName, ISID, NULL, TargetAddress> to an existing Discovery session MUST reinstate the existing Unnamed Discovery session. So ONLY an Unnamed Discovery session can reinstate another Unnamed Discovery session. No cross-drama here 🙈
7.4.2.2. Named Discovery Sessions
For Named Discovery sessions, the initiator specifies the TargetName key, so the target can clearly figure out the TargetPortalGroupTag too 🍓 Since all four elements of the 4-tuple are known, the ISID RULE MUST be enforced by targets with no changes from the Section 4.4.3 semantics. A new session with a matching <InitiatorName, ISID, TargetName, TargetPortalGroupTag> will reinstate an existing session ✨
Also, any new iSCSI session (Discovery or Normal) with the matching 4-tuple can reinstate an existing Named Discovery iSCSI session. Iconic behavior, honestly 👑
7.4.3. Target PDUs during Discovery
Targets SHOULD NOT send any responses other than a Text Response and Logout Response on a Discovery session once it's in the Full Feature Phase 💅
Implementation Note: A target may simply drop the connection in a Discovery session when it would have requested a Logout via an Async Message on Normal sessions. Quick and clean 🌈
7.5. Connection Timeout Management 🕰️
iSCSI defines two session-global timeout values (in seconds), Time2Wait and Time2Retain 🍰 They apply when a Full Feature Phase iSCSI connection is taken out of service, either on purpose or because something went wrong. Time2Wait is the initial "respite time" before trying an explicit or implicit Logout for the CID in question, or task reassignment for the affected tasks (if there are any). Time2Retain is the maximum time after that initial respite interval that the task and/or connection state(s) is/are guaranteed to be kept on the target, so a recovery attempt is possible 🦋
Recovery attempts for the connection and/or tasks SHOULD NOT be made before Time2Wait seconds have passed, but they MUST be completed within Time2Retain seconds after that initial Time2Wait waiting period. Timing is everything, bestie ⏰
7.5.1. Timeouts on Transport Exception Events
If a transport connection shuts down, or a transport reset happens with no iSCSI protocol interactions beforehand to tell the endpoints, the Full Feature Phase iSCSI connection gets abruptly terminated 😭 In this case, the timeout values are the negotiated values of the DefaultTime2Wait (Section 13.15) and DefaultTime2Retain (Section 13.16) text keys for the session 💜
7.5.2. Timeouts on Planned Decommissioning
Any planned decommissioning of a Full Feature Phase iSCSI connection comes after either a Logout Response PDU or an Async Message PDU 🎀 The Time2Wait and Time2Retain field values (Section 11.15) in a Logout Response PDU, and the Parameter2 and Parameter3 fields of an Async Message, specify the timeout values to use in each case. (For Async Messages, this is for AsyncEvent types "drop the connection" or "drop all the connections"; see Section 11.9.1 ✨)
These timeout values only apply to the affected connection and the tasks active on that connection. They have no bearing on initiator timers (if any) already running on connections or tasks associated with that session 🫶
7.6. Implicit Termination of Tasks 💀
A target implicitly terminates the active tasks due to iSCSI protocol dynamics in these cases:
- a) A connection is implicitly or explicitly logged out with the reason code "close the connection", and there are active tasks allegiant to that connection.
- b) A connection fails and eventually the connection state times out (state transition M1 in Section 8.2.2), and there are active tasks allegiant to that connection.
- c) A successful Logout with the reason code "remove the connection for recovery" happens while there are active tasks allegiant to that connection, and those tasks eventually time out after the Time2Wait and Time2Retain periods without allegiance reassignment.
- d) A connection is implicitly or explicitly logged out with the reason code "close the session", and there are active tasks in that session.
If the tasks terminated in cases a), b), c), and d) above are SCSI tasks, they must be internally terminated as if with CHECK CONDITION status. This status only matters for handling the internal SCSI state and SCSI side effects correctly with respect to ordering, because it's NEVER communicated back as a terminating status to the initiator 🙅♀️ Extra actions may still be needed at the SCSI level, depending on the SCSI context defined by the SCSI standards (e.g., queued commands and ACA; UA for the next command on the I_T nexus in cases a), b), and c); etc. See [SAM2] and [SPC3]) 🧠
7.7. Format Errors 🚨
These two explicit violations of PDU layout rules are format errors:
- a) Illegal contents of any PDU header field except the Opcode (legal values are specified in Section 11).
- b) Inconsistent field contents (consistent field contents are specified in Section 11).
Format errors mean there's a major implementation flaw in one of the parties 😬
When a target or an initiator receives an iSCSI PDU with a format error, it MUST immediately terminate all transport connections in the session, using either a connection close or a connection reset, and escalate the format error to session recovery (see Section 7.1.4.4). Pure drama, no notes 🔥
All initiator-detected PDU construction errors MUST be considered format errors. Some examples of these are:
NOP-Inwith a valid TTT but an invalid LUNNOP-Inwith a valid ITT (i.e., a NOP-In response) and also a valid TTTSCSI ResponsePDU with Status=CHECK CONDITION, butDataSegmentLength = 0
7.8. Digest Errors ✨
okay so the discussion here about the legal ways to handle digest errors leaves out session recovery as an explicit option 🙈 but either party that spots a digest error can totally choose to escalate to session recovery 🔥
When a target or an initiator gets any iSCSI PDU with a header digest error, it MUST either discard the header and all data up to the beginning of a later PDU or close the connection 💅 The digest error means the length field of the header might be corrupted, so the start of a later PDU has to be found reliably by other means, like a Sync and Steering layer 🧚
When a target gets any iSCSI PDU with a payload digest error, it MUST answer with a Reject PDU with a reason code of Data-Digest-Error and discard the PDU 💀
- If the discarded PDU is a solicited or unsolicited iSCSI data PDU (for immediate data in a command PDU, the non-data PDU rule below applies), the target MUST do one of the following:
- a) Request retransmission with a recovery R2T.
- b) Terminate the task with a SCSI Response PDU with a CHECK CONDITION Status and an iSCSI Condition of "Protocol Service CRC error" (Section 11.4.7.2). If the target chooses to implement this option, it MUST wait to receive all the data (signaled by a data PDU with the Final bit set for all outstanding R2Ts) before sending the SCSI Response PDU. A task management command (such as an ABORT TASK) from the initiator during this wait may also conclude the task.
- No further action is necessary for targets if the discarded PDU is a non-data PDU. In the case of immediate data being present on a discarded command, the immediate data is implicitly recovered when the task is retried (see Section 7.2.1), followed by the entire data transfer for the task. 🍓
When an initiator gets any iSCSI PDU with a payload digest error, it MUST discard the PDU 🫶
- If the discarded PDU is an iSCSI data PDU, the initiator MUST do one of the following:
- a) Request the desired data PDU through SNACK. In response to the SNACK, the target MUST either resend the data PDU or reject the SNACK with a Reject PDU with a reason code of "SNACK reject", in which case:
- a.1) If the status has not already been sent for the command, the target MUST terminate the command with a CHECK CONDITION Status and an iSCSI Condition of "SNACK rejected" (Section 11.4.7.2).
- a.2) If the status was already sent, no further action is necessary for the target. The initiator in this case MUST wait for the status to be received and then discard it, so as to internally signal the completion with CHECK CONDITION Status and an iSCSI Condition of "Protocol Service CRC error" (Section 11.4.7.2).
- b) Abort the task and terminate the command with an error.
- a) Request the desired data PDU through SNACK. In response to the SNACK, the target MUST either resend the data PDU or reject the SNACK with a Reject PDU with a reason code of "SNACK reject", in which case:
- If the discarded PDU is a response PDU or an unsolicited PDU (e.g., Async, Reject), the initiator MUST do one of the following:
- a) Request PDU retransmission with a status of SNACK.
- b) Log out the connection for recovery, and continue the tasks on a different connection instance as described in Section 7.2.
- c) Log out to close the connection (abort all the commands associated with the connection).
⚠️ Heads up bestie: an unsolicited PDU carries the next StatSN value on an iSCSI connection, which advances the StatSN. So when an initiator tosses one of these PDUs because of a payload digest error, the entire PDU, including the header, MUST be discarded. That means the initiator MUST treat the exception like a loss of any other solicited response PDU 😭
7.9. Sequence Errors 🌸
When an initiator gets an iSCSI R2T/data PDU with an out-of-order R2TSN/DataSN, or a SCSI Response PDU with an ExpDataSN that implies missing data PDU(s), it means the initiator must have detected a header or payload digest error on one or more earlier R2T/data PDUs. Sneaky, right? 👀
The initiator MUST address these implied digest errors as described in Section 7.8. When a target gets a data PDU with an out-of-order DataSN, it means the target must have hit a header or payload digest error on at least one of the earlier data PDUs. The target MUST address these implied digest errors as described in Section 7.8.
When an initiator gets an iSCSI status PDU with an out-of-order StatSN that implies missing responses, it MUST address the one or more missing status PDUs as described in Section 7.8. As a side effect of receiving the missing responses, the initiator may discover missing data PDUs. If the initiator wants to recover the missing data for a command, it MUST NOT acknowledge the received responses that start from the StatSN of the relevant command until it has completed receiving all the data PDUs of the command. 🔄
When an initiator gets duplicate R2TSNs (from the target proactively retransmitting R2Ts) or duplicate DataSNs (from the initiator's own proactive SNACKs), it MUST discard the duplicates ✨
7.10. Message Error Checking 💭
iSCSI implementations have been a little unsure, historically, about how much incoming messages need to be checked for protocol errors beyond what's strictly needed to process the message. This section settles that 🎀
Unless this document requires it, an iSCSI implementation is not required to do an exhaustive protocol conformance check on an incoming iSCSI PDU. The iSCSI implementation in particular is not required to double-check the remote iSCSI implementation's conformance to protocol requirements. No need to be a detective, babe 🕵️♀️
7.11. SCSI Timeouts ⏰
An iSCSI initiator MAY try to plug a command sequence gap on the target end (when there's no acknowledgment of the command through the ExpCmdSN) before the ULP timeout, by retrying the unacknowledged command as described in Section 7.2. Proactive, love that for her 🦋
On a ULP timeout for a command (one that carried a CmdSN of n), if the iSCSI initiator intends to continue the session it MUST abort the command, using either an appropriate Task Management Function Request for that specific command or a "close the connection" logout. 🚫
When using an ABORT TASK, if the ExpCmdSN is still less than (n + 1), the target may see the abort request while missing the original command itself, for one of these reasons:
- The original command was dropped due to digest error.
- The connection on which the original command was sent was successfully logged out. On logout, the unacknowledged commands issued on the connection being logged out are discarded.
If the abort request arrives and the original command is missing, targets MUST consider the original command with that RefCmdSN as received, and issue a task management response with the response code "Function complete". This response concludes the task on both ends 👑 If the abort request arrives and the target can determine (based on the Referenced Task Tag) that the command was received and executed, and also that the response was sent prior to the abort, then the target MUST respond with the response code "Task Does Not Exist". 🧠
7.12. Negotiation Failures 🎀
Text Request and Response sequences, when used to set or negotiate operational parameters, make up the negotiation/parameter setting. A negotiation failure is one or more of the following:
- For a negotiated key, none of the choices are acceptable to one of the sides in the negotiation.
- For a declarative key, the declared value is not acceptable to the other side in the negotiation.
- The Text Request timed out and possibly terminated.
- The Text Request was answered with a Reject PDU.
Two rules should be used to deal with negotiation failures 💖
- a) During login, any failure in negotiation MUST be considered a login process failure; the Login Phase, along with the connection, MUST be terminated. If the target detects the failure, it must terminate the login with the appropriate Login response code. 🚪
- b) A failure in negotiation during the Full Feature Phase will terminate the entire negotiation sequence, which may consist of a series of Text Requests that use the same Initiator Task Tag. The operational parameters of the session or the connection MUST continue to be the values agreed upon during an earlier successful negotiation (i.e., any partial results of this unsuccessful negotiation MUST NOT take effect and MUST be discarded). 🧹
7.13. Protocol Errors 🫧
Mapping framed messages over a "streaming" connection, like TCP, leaves the proposed mechanisms open to simple software framing errors. On the flip side, adding framing mechanisms to limit the fallout from these errors may be a real performance hit for simple implementations. Command sequence numbers and the mechanisms for dropping and reestablishing connections (covered earlier in Section 7 and its subsections) help handle this kind of mapping error 🧚♀️
All violations of iSCSI PDU exchange sequences specified in this document are also protocol errors. This category of errors can only be fixed by fixing the implementations, and iSCSI defines Reject and response codes to make that possible 🛠️
7.14. Connection Failures 🌈
iSCSI can keep a session running as long as it can keep or establish at least one TCP connection between the initiator and the target in a timely fashion. Targets and/or initiators may spot a failing connection through transport-level means (TCP), a gap in the command sequence number, a response stream that stays unfilled for a long time, or a failing iSCSI NOP (acting as a ping). The iSCSI NOP MAY be used periodically to speed up and improve the odds of catching connection failures ⚡ For transport-level means, as an example, initiators and targets MAY also use the keep-alive option (see [RFC1122]) on the TCP connection to get early link failure detection on otherwise idle links 🦋
On connection failure, the initiator and target MUST do one of the following:
- a) Attempt connection recovery within the session (Connection Recovery).
- b) Log out the connection with the reason code "close the connection" (Section 11.14.5), reissue missing commands, and implicitly terminate all active commands. This option requires support for the Within-connection recovery class (recovery within-connection).
- c) Perform session recovery (Session Recovery).
Either side may choose to escalate to session recovery (via the initiator dropping all the connections, or via an Async Message that announces the same intent from a target), and the other side MUST give it precedence 👑 On a connection failure, a target MUST terminate and/or discard all of the active immediate commands, no matter which of the above options is used. In other words, immediate commands are not recoverable across connection failures 💀
7.15. Session Errors ✨
okay so if all of a session's connections die and can't come back in a short time, or the initiator keeps running into protocol errors over and over, the initiator is allowed to terminate the session and set up a brand new one 💀🫶
When that happens, the initiator does these things:
- Resets or closes all the transport connections. 🔌
- Terminates all outstanding requests with an appropriate response before starting a new session. If the same I_T nexus is meant to be reestablished, the initiator MUST employ session reinstatement (see Section 6.3.5). 🦋
Now the target's side. When the session timeout hits (that's the connection state timeout for the last failed connection) on the target, it does this:
- Resets or closes the TCP connections, which closes the session. 🌸
- Terminates all active tasks that were allegiant to the connection(s) that made up the session. 💅
And one more thing, the target MUST also be prepared to handle a session reinstatement request from the initiator that might be dealing with session errors. It's not optional, bestie 🔥
8. State Transitions ✨
iSCSI connections and iSCSI sessions go through a bunch of well-defined states from the moment they get created to the moment they get cleared. It's giving life cycle 🦋
The connection state transitions are written up as two separate but related sets of state diagrams, just to make them easier to follow. The first set, the "standard connection state diagrams," covers the connection state transitions when the iSCSI connection is NOT waiting for, or going through, a cleanup by way of an explicit or implicit logout. The second set, the "connection cleanup state diagram," covers the transitions while the iSCSI connection cleanup is happening. The first set has two diagrams, one each for initiator and target, while the second set has one diagram that works for both. 🎀
The "session state diagram" shows the state transitions an iSCSI session goes through during its whole lifetime. It depends on the states of possibly several iSCSI connections that are part of the session. 🧚
Everything is described in text, tables, and diagrams. The diagrams are there for illustration, but the text and the tables are the governing specification, so those are the ones to trust 📜✨
8.1. Standard Connection State Diagrams
8.1.1. State Descriptions for Initiators and Targets
Here's what each state means for the standard connection state diagram 👑
S1: FREE
- initiator: The state on instantiation, or after a successful connection closure.
- target: The state on instantiation, or after a successful connection closure.
S2: XPT_WAIT
- initiator: Waiting for a response to its transport connection establishment request.
- target: Illegal. 🙈
S3: XPT_UP
- initiator: Illegal. 🙈
- target: Waiting for the login process to commence.
S4: IN_LOGIN
- initiator: Waiting for the login process to conclude, which might involve several PDU exchanges.
- target: Waiting for the login process to conclude, which might involve several PDU exchanges.
S5: LOGGED_IN
- initiator: In the Full Feature Phase, waiting for all internal, iSCSI, and transport events.
- target: In the Full Feature Phase, waiting for all internal, iSCSI, and transport events.
S6: IN_LOGOUT
- initiator: Waiting for a Logout Response.
- target: Waiting for an internal event signaling that logout processing is complete.
S7: LOGOUT_REQUESTED
- initiator: Waiting for an internal event signaling readiness to proceed with Logout.
- target: Waiting for the Logout process to start after having requested a Logout via an Async Message.
S8: CLEANUP_WAIT
- initiator: Waiting for the context and/or resources to start the cleanup processing for this CSM.
- target: Waiting for the cleanup process to start for this CSM.
8.1.2. State Transition Descriptions for Initiators and Targets
Now the transitions, the fun part 🌈💜
T1
- initiator: A transport connect request was made (e.g., TCP SYN sent).
- target: Illegal. 🙈
T2
- initiator: The transport connection request timed out, a transport reset was received, or an internal event of receiving a Logout Response (success) on another connection for a "close the session" Logout Request was received.
- target: Illegal. 🙈
T3
- initiator: Illegal. 🙈
- target: A valid transport connection request was received that establishes the transport connection.
T4
- initiator: The transport connection was established, which prompts the initiator to start the iSCSI Login.
- target: The initial iSCSI Login Request was received.
T5
- initiator: The final iSCSI Login Response with a Status-Class of zero was received.
- target: The final iSCSI Login Request to conclude the Login Phase was received, which prompts the target to send the final iSCSI Login Response with a Status-Class of zero.
T6
- initiator: Illegal. 🙈
- target: Login timed out, a transport disconnect indication was received, a transport reset was received, or an internal event indicating a transport timeout was received. In all of these cases, the connection is to be closed. 🔒
T7
- initiator: One of the following events caused the transition:
- a) The final iSCSI Login Response was received with a non-zero Status-Class.
- b) Login timed out.
- c) A transport disconnect indication was received.
- d) A transport reset was received.
- e) An internal event indicating a transport timeout was received.
- f) An internal event of receiving a Logout Response (success) on another connection for a "close the session" Logout Request was received.
In all of these cases, the transport connection is closed.
- target: One of the following events caused the transition:
- a) The final iSCSI Login Request to conclude the Login Phase was received, which prompts the target to send the final iSCSI Login Response with a non-zero Status-Class.
- b) Login timed out.
- c) A transport disconnect indication was received.
- d) A transport reset was received.
- e) An internal event indicating a transport timeout was received.
- f) On another connection, a "close the session" Logout Request was received.
In all of these cases, the connection is to be closed.
T8
- initiator: An internal event of receiving a Logout Response (success) on another connection for a "close the session" Logout Request was received, which closes this connection and means no further cleanup is needed.
- target: An internal event of sending a Logout Response (success) on another connection for a "close the session" Logout Request was received, or an internal event of a successful connection/session reinstatement was received, which prompts the target to close this connection cleanly. 🧹
T9, T10
- initiator: An internal event that indicates readiness to start the Logout process was received, which prompts an iSCSI Logout to be sent by the initiator.
- target: An iSCSI Logout Request was received.
T11, T12
- initiator: An Async PDU with AsyncEvent "Request Logout" was received.
- target: An internal event that requires the decommissioning of the connection was received, which causes an Async PDU with an AsyncEvent "Request Logout" to be sent.
T13
- initiator: An iSCSI Logout Response (success) was received, or an internal event of receiving a Logout Response (success) on another connection for a "close the session" Logout Request was received.
- target: An internal event was received that indicates the Logout was processed successfully, which prompts an iSCSI Logout Response (success) to be sent; an internal event of sending a Logout Response (success) on another connection for a "close the session" Logout Request was received; or an internal event of a successful connection/session reinstatement was received. In all of these cases, the transport connection is closed. 💖
T14
- initiator: An Async PDU with AsyncEvent "Request Logout" was received again.
- target: Illegal. 🙈
T15, T16
- initiator: One or more of the following events caused this transition:
- a) An internal event that indicates a transport connection timeout was received, which prompts a transport reset or transport connection closure.
- b) A transport reset was received.
- c) A transport disconnect indication was received.
- d) An Async PDU with AsyncEvent "Drop connection" (for this CID) was received.
- e) An Async PDU with AsyncEvent "Drop all connections" was received.
- target: One or more of the following events caused this transition:
- a) An internal event that indicates a transport connection timeout was received, which prompts a transport reset or transport connection closure.
- b) An internal event of a failed connection/session reinstatement was received.
- c) A transport reset was received.
- d) A transport disconnect indication was received.
- e) An internal emergency cleanup event was received, which prompts an Async PDU with AsyncEvent "Drop connection" (for this CID), or the event "Drop all connections".
T17
- initiator: One or more of the following events caused this transition:
- a) A Logout Response (failure, i.e., a non-zero status) was received, or Logout timed out.
- b) Any of the events specified for T15 and T16 occurred.
- target: One or more of the following events caused this transition:
- a) An internal event that indicates a failure of the Logout processing was received, which prompts a Logout Response (failure, i.e., a non-zero status) to be sent.
- b) Any of the events specified for T15 and T16 occurred.
T18
- initiator: An internal event of receiving a Logout Response (success) on another connection for a "close the session" Logout Request was received.
- target: An internal event of sending a Logout Response (success) on another connection for a "close the session" Logout Request was received, or an internal event of a successful connection/session reinstatement was received. In both of these cases, the connection is closed.
The CLEANUP_WAIT state (S8) means there may be iSCSI tasks that haven't reached a conclusion and are still considered busy. So it's not done until those tasks are sorted out 🫶💜
8.1.3. Standard Connection State Diagram for an Initiator ✨
Okay bestie, here's the initiator's connection state machine 🎀 Symbolic names for states:
S1: FREES2: XPT_WAITS4: IN_LOGINS5: LOGGED_INS6: IN_LOGOUTS7: LOGOUT_REQUESTEDS8: CLEANUP_WAIT
States S5, S6, and S7 make up the Full Feature Phase of the connection 💖
The state diagram looks like this 🦋
-------<-------------+
+--------->/ S1 \<----+ |
T13| +->\ /<-+ \ |
| / ---+--- \ \ |
| / | T2 \ | |
| T8 | |T1 | | |
| | | / |T7 |
| | | / | |
| | | / | |
| | V / / |
| | ------- / / |
| | / S2 \ / |
| | \ / / |
| | ---+--- / |
| | |T4 / |
| | V / | T18
| | ------- / |
| | / S4 \ |
| | \ / |
| | ---+--- | T15
| | |T5 +--------+---------+
| | | /T16+-----+------+ |
| | | / -+-----+--+ | |
| | | / / S7 \ |T12| |
| | | / +->\ /<-+ V V
| | | / / -+----- -------
| | | / /T11 |T10 / S8 \
| | V / / V +----+ \ /
| | ---+-+- ----+-- | -------
| | / S5 \T9 / S6 \<+ ^
| +-----\ /--->\ / T14 |
| ------- --+---+---------+T17
+---------------------------+The transition table below matches the diagram 🍓 Each row is a starting state. After you take a transition marked in a cell, you land in the state at the top of that column. For example, from S1 you take T1 and arrive at S2 🧚 The - cells are undefined transitions 🙅♀️
+----+---+---+---+---+----+---+
|S1 |S2 |S4 |S5 |S6 |S7 |S8 |
---+----+---+---+---+---+----+---+
S1| - |T1 | - | - | - | - | - |
---+----+---+---+---+---+----+---+
S2|T2 |- |T4 | - | - | - | - |
---+----+---+---+---+---+----+---+
S4|T7 |- |- |T5 | - | - | - |
---+----+---+---+---+---+----+---+
S5|T8 |- |- | - |T9 |T11 |T15|
---+----+---+---+---+---+----+---+
S6|T13 |- |- | - |T14|- |T17|
---+----+---+---+---+---+----+---+
S7|T18 |- |- | - |T10|T12 |T16|
---+----+---+---+---+---+----+---+
S8| - |- |- | - | - | - | - |
---+----+---+---+---+---+----+---+8.1.4. Standard Connection State Diagram for a Target 🌈
Now the target's version, which is giving a similar energy 💅 Symbolic names for states:
S1: FREES3: XPT_UPS4: IN_LOGINS5: LOGGED_INS6: IN_LOGOUTS7: LOGOUT_REQUESTEDS8: CLEANUP_WAIT
States S5, S6, and S7 make up the Full Feature Phase of the connection, same as before 🫶
Here's the diagram 🌸
-------<-------------+
+--------->/ S1 \<----+ |
T13| +->\ /<-+ \ |
| / ---+--- \ \ |
| / | T6 \ | |
| T8 | |T3 | | |
| | | / |T7 |
| | | / | |
| | | / | |
| | V / / |
| | ------- / / |
| | / S3 \ / |
| | \ / / | T18
| | ---+--- / |
| | |T4 / |
| | V / |
| | ------- / |
| | / S4 \ |
| | \ / |
| | ---+--- T15 |
| | |T5 +--------+---------+
| | | /T16+-----+------+ |
| | | / -+-----+---+ | |
| | | / / S7 \ |T12| |
| | | / +->\ /<-+ V V
| | | / / -+----- -------
| | | / /T11 |T10 / S8 \
| | V / / V \ /
| | ---+-+- ------- -------
| | / S5 \T9 / S6 \ ^
| +-----\ /--->\ / |
| ------- --+---+---------+T17
+---------------------------+This transition table follows the same rules as the initiator diagram 🦋
+----+---+---+---+---+----+---+
|S1 |S3 |S4 |S5 |S6 |S7 |S8 |
---+----+---+---+---+---+----+---+
S1| - |T3 | - | - | - | - | - |
---+----+---+---+---+---+----+---+
S3|T6 |- |T4 | - | - | - | - |
---+----+---+---+---+---+----+---+
S4|T7 |- |- |T5 | - | - | - |
---+----+---+---+---+---+----+---+
S5|T8 |- |- | - |T9 |T11 |T15|
---+----+---+---+---+---+----+---+
S6|T13 |- |- | - |- |- |T17|
---+----+---+---+---+---+----+---+
S7|T18 |- |- | - |T10|T12 |T16|
---+----+---+---+---+---+----+---+
S8| - |- |- | - | - | - | - |
---+----+---+---+---+---+----+---+8.2. Connection Cleanup State Diagram for Initiators and Targets 🧹
Okay, cleanup time 🧼 Symbolic names for states:
R1: CLEANUP_WAIT (same as S8)R2: IN_CLEANUPR3: FREE (same as S1)
So, whenever a connection state machine in cleanup (let's call it CSM-C) enters the CLEANUP_WAIT state (S8), it must go through the state transitions in the connection cleanup state diagram. It can do that using either:
- a) a separate Full Feature Phase connection (let's call it CSM-E, for explicit) in the LOGGED_IN state in the same session, or
- b) a new transport connection (let's call it CSM-I, for implicit) in the FREE state that gets added to the same session.
In the CSM-E case, an explicit logout for the CID that matches CSM-C (as either a connection or session logout) needs to be performed to finish the cleanup 💅 In the CSM-I case, an implicit logout for the CID that matches CSM-C needs to be performed through connection reinstatement (Section 6.3.4) for that CID 🙈 Either way, the protocol exchanges on CSM-E or CSM-I decide the state transitions for CSM-C. So this cleanup state diagram only applies to the instance of the connection in cleanup (i.e., CSM-C) 👑
For an implicit logout, CSM-C reaches FREE (R3) at the moment CSM-I reaches LOGGED_IN ✨ For an explicit logout, CSM-C reaches FREE (R3) when CSM-E gets a successful Logout Response and is still in the LOGGED_IN state 🎀
An initiator must start an explicit or implicit connection logout for a connection in the CLEANUP_WAIT state, if the initiator plans to keep using the associated iSCSI session. Don't skip this one, bestie 💀
Here's the cleanup diagram, which applies to both initiators and targets. (M1, M2, M3, and M4 are defined in Section 8.2.2.) 🦋
---------
/ R1 \
+---\ /<-+
/ ----+---- \
/ | \ M3
M1 | |M2 |
| | /
| | /
| | /
| V /
| ---------/
| / R2 \
| \ /
| ---------
| |
| |M4
| |
| |
| |
| V
| --------
| / R3 \
+----->\ /
--------The table below follows the diagram and the same conventions as the earlier sections 🍓
+----+----+----+
|R1 |R2 |R3 |
-----+----+----+----+
R1 | - |M2 |M1 |
-----+----+----+----+
R2 |M3 | - |M4 |
-----+----+----+----+
R3 | - | - | - |
-----+----+----+----+8.2.1. State Descriptions for Initiators and Targets 🌷
Let's go through what each cleanup state means for each side 💖
R1: CLEANUP_WAIT (same as S8)
- initiator: Waiting for the internal event that starts the cleanup processing for CSM-C.
- target: Waiting for the cleanup process to start for CSM-C.
R2: IN_CLEANUP
- initiator: Waiting for the connection cleanup process to conclude for CSM-C.
- target: Waiting for the connection cleanup process to conclude for CSM-C.
R3: FREE (same as S1)
- initiator: End state for CSM-C 🎉
- target: End state for CSM-C 🎉
8.2.2. State Transition Descriptions for Initiators and Targets ✨
okay so these are the reasons a connection is allowed to hop between states 🦋 Each one is split up by initiator vs target, and yes, the labels are very specific, bestie 💅
M1: one or more of the following events got received:
- initiator:
- an internal event that indicates connection state timeout ⏰
- an internal event of receiving a successful Logout Response on a different connection for a "close the session" Logout
- target:
- an internal event that indicates connection state timeout
- an internal event of sending a Logout Response (success) on a different connection for a "close the session" Logout Request
M2: an implicit/explicit logout process was initiated by the initiator. 🚪
- In CSM-I usage:
- initiator: an internal event requesting the connection (or session) reinstatement was received, so a connection (or session) reinstatement Login gets sent, and CSM-I transitions to IN_LOGIN.
- target: a connection/session reinstatement Login was received while in state XPT_UP.
- In CSM-E usage:
- initiator: an internal event was received that indicates an explicit logout was sent for this CID in state LOGGED_IN.
- target: an explicit logout was received for this CID in state LOGGED_IN.
M3: logout failure was detected. 💀
- In CSM-I usage:
- initiator: CSM-I failed to reach LOGGED_IN and arrived into FREE instead.
- target: CSM-I failed to reach LOGGED_IN and arrived into FREE instead.
- In CSM-E usage:
- initiator: either CSM-E moved out of LOGGED_IN, or Logout timed out and/or aborted, or a Logout Response (failure) was received.
- target: either CSM-E moved out of LOGGED_IN, Logout timed out and/or aborted, or an internal event that indicates that a failed Logout processing was received. A Logout Response (failure) was sent in the last case.
M4: a successful implicit/explicit logout was performed. 🎉
- In CSM-I usage:
- initiator: CSM-I reached state LOGGED_IN, or an internal event of receiving a Logout Response (success) on another connection for a "close the session" Logout Request was received.
- target: CSM-I reached state LOGGED_IN, or an internal event of sending a Logout Response (success) on a different connection for a "close the session" Logout Request was received.
- In CSM-E usage:
- initiator: CSM-E stayed in LOGGED_IN and received a Logout Response (success), or an internal event of receiving a Logout Response (success) on another connection for a "close the session" Logout Request was received.
- target: CSM-E stayed in LOGGED_IN and an internal event indicating a successful Logout processing was received, or an internal event of sending a Logout Response (success) on a different connection for a "close the session" Logout Request was received.
8.3. Session State Diagrams 🌈
8.3.1. Session State Diagram for an Initiator 🎀
Symbolic names for states:
- Q1: FREE
- Q3: LOGGED_IN
- Q4: FAILED
State Q3 is where the Full Feature Phase of the session lives, so this is the main vibe 💖
The state diagram is as follows. (N1, N3, N4, N5, and N6 are defined in Section 8.3.4.)
---------
/ Q1 \
+---------->\ /<-+
/ ----+---- |
/ | |N3
N6 | |N1 |
| | |
| N4 | |
| +------------+ | /
| | | | /
| | | | /
| | V V /
--+-+--- -------+-
/ Q4 \ N5 / Q3 \
\ /<------\ /
-------- ---------The state transition table is as follows:
+---+---+---+
|Q1 |Q3 |Q4 |
-----+---+---+---+
Q1 | - |N1 | - |
-----+---+---+---+
Q3 |N3 | - |N5 |
-----+---+---+---+
Q4 |N6 |N4 | - |
-----+---+---+---+8.3.2. Session State Diagram for a Target 🦋
Symbolic names for states:
- Q1: FREE
- Q2: ACTIVE
- Q3: LOGGED_IN
- Q4: FAILED
- Q5: IN_CONTINUE
State Q3 is the Full Feature Phase operation of the session, same as before 🫶
The state diagram is as follows:
---------
+------------------->/ Q1 \
/ +-------------->\ /<-+
| | ---+----- |
| | ^ | |N3
N6 | |N11 N9| V N1 |
| | +-------- |
| | / Q2 \ |
| | \ / |
| ---+----- +--+----- |
| / Q5 \ | |
| \ / N10 | |
| -+-+----+-----------+ | N2 /
| ^ | | | /
| N7| |N8 | | /
| | | | V /
--+---+-V V------+-
/ Q4 \ N5 / Q3 \
\ /<-------------\ /
--------- ---------The state transition table is as follows:
+----+----+----+----+----+
|Q1 |Q2 |Q3 |Q4 |Q5 |
-----+----+----+----+----+----+
Q1 | - |N1 | - | - | - |
-----+----+----+----+----+----+
Q2 |N9 | - |N2 | - | - |
-----+----+----+----+----+----+
Q3 |N3 | - | - |N5 | - |
-----+----+----+----+----+----+
Q4 |N6 | - | - | - |N7 |
-----+----+----+----+----+----+
Q5 |N11 | - |N10 |N8 | - |
-----+----+----+----+----+----+8.3.3. State Descriptions for Initiators and Targets 🌸
Q1: FREE
- initiator: the state on instantiation or after cleanup.
- target: the state on instantiation or after cleanup.
Q2: ACTIVE
- initiator: illegal.
- target: the first iSCSI connection in the session transitioned to IN_LOGIN, waiting for it to complete the login process.
Q3: LOGGED_IN
- initiator: waiting for all session events.
- target: waiting for all session events.
Q4: FAILED
- initiator: waiting for session recovery or session continuation.
- target: waiting for session recovery or session continuation.
Q5: IN_CONTINUE
- initiator: illegal.
- target: waiting for a session continuation attempt to reach a conclusion.
8.3.4. State Transition Descriptions for Initiators and Targets ⭐
N1:
- initiator: at least one transport connection reached the LOGGED_IN state.
- target: the first iSCSI connection in the session had reached the IN_LOGIN state.
N2:
- initiator: illegal.
- target: at least one iSCSI connection reached the LOGGED_IN state.
N3:
- initiator: graceful closing of the session via session closure (Section 6.3.6).
- target: graceful closing of the session via session closure (Section 6.3.6), or a successful session reinstatement cleanly closed the session.
N4:
- initiator: a session continuation attempt succeeded.
- target: illegal.
N5:
- initiator: session failure (Section 6.3.6) occurred.
- target: session failure (Section 6.3.6) occurred.
N6:
- initiator: session state timeout occurred, or a session reinstatement cleared this session instance. This results in the freeing of all associated resources, and the session state is discarded.
- target: session state timeout occurred, or a session reinstatement cleared this session instance. This results in the freeing of all associated resources, and the session state is discarded.
N7:
- initiator: illegal.
- target: a session continuation attempt was initiated.
N8:
- initiator: illegal.
- target: the last session continuation attempt failed.
N9:
- initiator: illegal.
- target: login attempt on the leading connection failed.
N10:
- initiator: illegal.
- target: a session continuation attempt succeeded.
N11:
- initiator: illegal.
- target: a successful session reinstatement cleanly closed the session.
9. Security Considerations 🔐
Historically, native storage systems never really had to think about security, because their environments carried minimal risk 🙃 Storage devices were either plugged straight into hosts or sat on a Storage Area Network (SAN) that was totally separate from the communications network. Once storage protocols like SCSI started running over IP networks, security suddenly became a must-think-about situation 😭 iSCSI implementations must provide means of protection against active attacks (e.g., pretending to be another identity; message insertion, deletion, modification, and replaying) and passive attacks (e.g., eavesdropping, gaining advantage by analyzing the data sent over the line). Like, this is serious, bestie 🚨
Although technically possible, iSCSI SHOULD NOT be configured without security, specifically in-band authentication; see Section 9.2. iSCSI configured without security should be confined to closed environments that have very limited and well-controlled security risks. [RFC3723] specifies the mechanisms that must be used in order to mitigate risks fully described in that document. 💀
The following section describes the security mechanisms provided by an iSCSI implementation. 🛡️
9.1. iSCSI Security Mechanisms ✨
Okay bestie, so the entities in iSCSI security are the initiator, the target, and the IP communication endpoints 🫶 Multiple initiators or targets sharing one endpoint is totally expected, so iSCSI gives us two separate security mechanisms 🔐. First up is in-band authentication between the initiator and target at the iSCSI connection level, which happens through an exchange of iSCSI Login PDUs. Second is packet protection (integrity, authentication, and confidentiality) from IPsec at the IP level. They complement each other, it's giving teamwork 💖 In-band auth gives end-to-end trust (at login time) between the iSCSI initiator and target, and IPsec gives a secure channel between the IP communication endpoints 🦋 iSCSI can be used to get at sensitive info that needs serious protection, so it's a big deal 👑
As the rest of this security considerations section explains, both iSCSI security mechanisms are mandatory to implement (MUST). Using in-band authentication is strongly recommended (SHOULD). IPsec, on the other hand, is optional (MAY), because the security risks it covers may only be present over some of the networks an iSCSI connection or session uses 🌸 For example, if an iSCSI session spans data centers, IPsec VPN gateways at the data center boundaries protecting the WAN link between them may be appropriate, combined with in-band iSCSI authentication 🧚
More details on typical iSCSI scenarios and how initiators, targets, and communication endpoints relate can be found in [RFC3723] 📚
9.2. In-Band Initiator-Target Authentication 🔑
During login, the target MAY authenticate the initiator, and the initiator MAY authenticate the target 💅 The authentication happens on every new iSCSI connection through an exchange of iSCSI Login PDUs, using a negotiated authentication method.
The authentication method can't assume IPsec is protecting it, because IPsec is optional to use 🙈 An attacker should gain as little advantage as possible from inspecting the authentication phase PDUs. So a method using cleartext (or equivalent) passwords MUST NOT be used 😭 On the other hand, identity protection isn't strictly required.
The authentication mechanism protects against an unauthorized login to storage resources using a false identity (spoofing) 🛡️ Once the authentication phase is done, if IPsec isn't underneath, all PDUs go out and come in in the clear 💀 So the authentication mechanism alone (without IPsec) should only be used when there's no risk of eavesdropping or of message insertion, deletion, modification, and replaying.
Section 12 defines several authentication methods and the exact steps that must be followed in each one, including the iSCSI-text-keys and their allowed values in each step 📋 Whenever an iSCSI initiator gets a response whose keys, or their values, don't match the step definition, it MUST abort the connection 🚫
Whenever an iSCSI target gets a request or response whose keys, or their values, don't match the step definition, it MUST answer with a Login reject with the "Initiator Error" or "Missing Parameter" status. These statuses aren't meant for cryptographically incorrect values like the CHAP response, which MUST get the "Authentication Failure" status instead 🙅♀️ This rule matters a lot in CHAP with target authentication (see Section 12.1.3). Without it, the initiator could pull off a reflection attack by leaving out its response key (CHAP_R), reusing the same CHAP challenge as the target, and bouncing the target's response back at it 😱 In CHAP this is blocked, because the target must answer the missing CHAP_R key with a Login reject with the "Missing Parameter" status 🙌
For some authentication methods, a key specifies the identity of the iSCSI initiator or target for authentication purposes 🪪 The value for that key MAY be different from the iSCSI name, and SHOULD be configurable (CHAP_N: see Section 12.1.3; SRP_U: see Section 12.1.2). Because of this, iSCSI implementations SHOULD manage authentication so that impersonation across iSCSI names through these authentication identities isn't possible 🕵️♀️ Specifically, implementations SHOULD allow configuring an authentication identity for a Name if it's different, plus the authentication credentials for that identity. During login, implementations SHOULD verify the Name-to-identity relationship on top of authenticating the identity through the negotiated authentication method ✅
When an iSCSI session has multiple TCP connections, whether concurrent or sequential, the authentication method and identities should not vary among the connections 🧩 So all connections in an iSCSI session SHOULD use the same authentication method, iSCSI name, and authentication identity (for methods that use an authentication identity). Implementations SHOULD check this and cause an authentication failure on any new connection that uses a different authentication method, iSCSI name, or authentication identity than the ones already in the session 🚨 Also, implementations SHOULD NOT support both authenticated and unauthenticated TCP connections in the same iSCSI session, whether they're added concurrently or sequentially 🙅♀️
9.2.1. CHAP Considerations 🎀
Compliant iSCSI initiators and targets MUST implement the CHAP authentication method [RFC1994] (according to Section 12.1.3, including the target authentication option) 💖
When CHAP runs over a non-encrypted channel, it's vulnerable to an off-line dictionary attack 😬 Implementations MUST support using up to 128-bit random CHAP secrets, including the means to generate such secrets and to accept them from an external generation source. Implementations MUST NOT provide secret generation (or expansion) means other than random generation 🎲
An administrative entity in an environment where CHAP is used with a secret that has less than 96 random bits MUST enforce IPsec encryption (according to the implementation requirements in Section 9.3.2) to protect the connection 🔒 Also, in this case, IKE authentication with group pre-shared cryptographic keys SHOULD NOT be used, unless it isn't essential to protect group members against off-line dictionary attacks by other members 🙈
CHAP secrets MUST be an integral number of bytes (octets). A compliant implementation SHOULD NOT continue with the login step where it would send a CHAP response (CHAP_R; see Section 12.1.3) unless it can verify that the CHAP secret is at least 96 bits, or that IPsec encryption is protecting the connection 🔐
Any CHAP secret used for initiator authentication MUST NOT be configured for authenticating any target, and any CHAP secret used for target authentication MUST NOT be configured for authenticating any initiator 🙅♀️ If the CHAP response received by one end of an iSCSI connection is the same as the CHAP response the receiving endpoint would have generated for the same CHAP challenge, the response MUST be treated as an authentication failure and cause the connection to close (this makes sure the same CHAP secret isn't used for authentication in both directions) 🛑 Also, if an iSCSI implementation can function as both initiator and target, different CHAP secrets and identities MUST be configured for these two roles 👯♀️
Here's an example of the attacks these requirements prevent, and it's lowkey wild 😭
- a) "Rogue" wants to impersonate "Storage" to Alice, and knows that a single secret is used for both directions of Storage-Alice authentication.
- b) Rogue convinces Alice to open two connections to itself, and identifies itself as Storage on both connections.
- c) Rogue issues a CHAP challenge on Connection 1, waits for Alice to respond, and then reflects Alice's challenge back to her as the initial challenge on Connection 2.
- d) If Alice doesn't check for the reflection across connections, Alice's response on Connection 2 lets Rogue impersonate Storage on Connection 1, even though Rogue doesn't know the Alice-Storage CHAP secret 💀
Originators MUST NOT reuse the CHAP challenge sent by the responder for the other direction of a bidirectional authentication. Responders MUST check for this condition and close the iSCSI TCP connection if it happens 🚪
The same CHAP secret SHOULD NOT be configured for authenticating multiple initiators or multiple targets, because it lets any one of them impersonate any other, and if one gets compromised, the attacker can impersonate any of them 😱 It's recommended that iSCSI implementations check for identical CHAP secrets being used by different peers when that check is feasible, and take appropriate measures to warn users and/or administrators when it's detected 📣
When an iSCSI initiator or target authenticates itself to counterparts in multiple administrative domains, it SHOULD use a different CHAP secret for each administrative domain, so security compromises don't spread across domains 🌈
Within a single administrative domain:
- A single CHAP secret MAY be used for authentication of an initiator to multiple targets.
- A single CHAP secret MAY be used for an authentication of a target to multiple initiators when the initiators use an external server (e.g., RADIUS [RFC2865]) to verify the target's CHAP responses and don't know the target's CHAP secret 🧚
If an external response verification server (e.g., RADIUS) isn't used, using one CHAP secret to authenticate a target to multiple initiators requires that all of those initiators know that target's secret. Any of these initiators can impersonate the target to any other one of them, and compromising one of them lets an attacker impersonate the target to all of them 😭 Targets SHOULD use separate CHAP secrets for authentication to each initiator when these risks are a concern. In that situation, it may be useful to configure a separate logical iSCSI target, with its own iSCSI Node Name, for each initiator or group of initiators that should be kept separate 🍓
The requirements above strengthen the security properties of CHAP authentication for iSCSI compared to the basic CHAP authentication mechanism [RFC1994]. It's super important to stick to these requirements, especially the ones for strong (large, randomly generated) CHAP secrets 🚨 iSCSI implementations and deployments that don't use strong CHAP secrets are likely to be highly vulnerable to off-line dictionary attacks on CHAP secrets 💔
Replacing CHAP with a better authentication mechanism is anticipated in a future version of iSCSI 🦋 The FC-SP-2 standard [FC-SP-2] has specified the Extensible Authentication Protocol - Generalized Pre-Shared Key (EAP-GPSK) authentication mechanism [RFC5433] as an alternative to (and possible future replacement for) Fibre Channel's similar use of strengthened CHAP ✨ Another possible replacement for CHAP is a secure password mechanism, e.g., an updated version of iSCSI's current SRP authentication mechanism 💜
9.2.2. SRP Considerations ✨
okay bestie, SRP time 🔐 The strength of the SRP authentication method (the one specified in [RFC2945]) depends on the group you use, meaning the prime modulus N and the generator g 💅 As [RFC2945] explains, N is required to be a Sophie Germain prime (of the form N = 2q + 1, where q is also prime), and the generator g is a primitive root of GF(N). In iSCSI authentication, the prime modulus N MUST be at least 768 bits 🔥
The list of allowed SRP groups is provided in [RFC3723] 🌸
9.2.3. Kerberos Considerations 👑
okay so iSCSI uses raw Kerberos V5 [RFC4120] to authenticate a client (iSCSI initiator) principal to a service (iSCSI target) principal 🦋 Note that iSCSI does not use the Generic Security Service Application Program Interface (GSS-API) [RFC2743] or the Kerberos V5 GSS-API security mechanism [RFC4121]. This means that iSCSI implementations supporting the KRB5 AuthMethod (Section 12.1) are directly involved in the Kerberos protocol, which is very main character energy ✨ When Kerberos V5 is used for authentication, the following actions MUST be performed as specified in [RFC4120]:
- The target MUST validate
KRB_AP_REQto ensure that the initiator can be trusted. - When mutual authentication is selected, the initiator MUST validate
KRB_AP_REPto determine the outcome of mutual authentication.
Since Kerberos V5 is capable of providing mutual authentication, implementations SHOULD support mutual authentication by default for login authentication 🫶
Note, however, that Kerberos authentication only assures that the server (iSCSI target) can be trusted by the Kerberos client (initiator) and vice versa 😭 So an initiator should employ appropriately secured service discovery techniques (e.g., iSNS; see Section 4.2.7) to make sure it is talking to the intended target principal 🧚
iSCSI does not use Kerberos v5 for either integrity or confidentiality protection of the iSCSI protocol. iSCSI uses IPsec for those purposes as specified in Section 9.3 💜
9.3. IPsec 🔐
iSCSI uses the IPsec mechanism for packet protection (cryptographic integrity, authentication, and confidentiality) at the IP level between the iSCSI communicating endpoints. The following sections describe the IPsec protocols that must be implemented for data authentication and integrity; confidentiality; and cryptographic key management ✨
An iSCSI initiator or target may provide the required IPsec support fully integrated or in conjunction with an IPsec front-end device. In the latter case, the compliance requirements with regard to IPsec support apply to the "combined device". Only the "combined device" is to be considered an iSCSI device 🎀
Detailed considerations and recommendations for using IPsec for iSCSI are provided in [RFC3723] as updated by [RFC7146]. The IPsec requirements are reproduced here for convenience and are intended to match those in [RFC7146]. In the event of a discrepancy, the requirements in [RFC7146] apply 💅
9.3.1. Data Authentication and Integrity 🛡️
Data authentication and integrity are provided by a cryptographic keyed Message Authentication Code in every sent packet. This code protects against message insertion, deletion, and modification. Protection against message replay is realized by using a sequence counter 🌈
An iSCSI-compliant initiator or target MUST provide data authentication and integrity by implementing IPsec v2 [RFC2401] with ESPv2 [RFC2406] in tunnel mode. It SHOULD provide data authentication and integrity by implementing IPsec v3 [RFC4301] with ESPv3 [RFC4303] in tunnel mode, and it MAY provide data authentication and integrity by implementing either IPsec v2 or v3 with the appropriate version of ESP in transport mode. The IPsec implementation MUST fulfill the following iSCSI-specific requirements:
- HMAC-SHA1 MUST be implemented in the specific form of
HMAC-SHA-1-96[RFC2404]. - AES CBC MAC with XCBC extensions using 128-bit keys SHOULD be implemented [RFC3566].
- Implementations that support IKEv2 [RFC5996] SHOULD also implement AES Galois Message Authentication Code (GMAC) [RFC4543] using 128-bit keys.
The ESP anti-replay service MUST also be implemented 🙈
At the high speeds at which iSCSI is expected to operate, a single IPsec SA could rapidly exhaust the ESP 32-bit sequence number space. This requires frequent rekeying of the SA, because rollover of the ESP sequence number within a single SA is prohibited for both ESPv2 [RFC2406] and ESPv3 [RFC4303] 😩 To avoid this potentially undesirable frequent rekeying, implementations that are capable of operating at speeds of 1 gigabit/second or higher MUST implement extended (64-bit) sequence numbers for ESPv2 (and ESPv3, if supported), and SHOULD use extended sequence numbers for all iSCSI traffic. Extended sequence number negotiation as part of security association establishment is specified in [RFC4304] for IKEv1 and [RFC5996] for IKEv2 🔥
9.3.2. Confidentiality 🔒
Confidentiality is provided by encrypting the data in every packet. When confidentiality is used, it MUST be accompanied by data authentication and integrity to provide comprehensive protection against eavesdropping and against message insertion, deletion, modification, and replaying 💖
An iSCSI-compliant initiator or target MUST provide confidentiality by implementing IPsec v2 [RFC2401] with ESPv2 [RFC2406] in tunnel mode. It SHOULD provide confidentiality by implementing IPsec v3 [RFC4301] with ESPv3 [RFC4303] in tunnel mode, and it MAY provide confidentiality by implementing either IPsec v2 or v3 with the appropriate version of ESP in transport mode. This is subject to the following iSCSI-specific requirements that apply to IPsec v2 and IPsec v3:
- 3DES in CBC mode MAY be implemented [RFC2451].
- AES in CBC mode with 128-bit keys MUST be implemented [RFC3602]; other key sizes MAY be supported.
- AES in Counter mode MAY be implemented [RFC3686].
- Implementations that support IKEv2 [RFC5996] SHOULD also implement AES Galois/Counter Mode (GCM) with 128-bit keys [RFC4106]; other key sizes MAY be supported.
Due to its inherent weakness, DES in CBC mode MUST NOT be used 🚫 The NULL encryption algorithm MUST also be implemented 🫶
9.3.3. Policy, Security Associations, and Cryptographic Key Management 🗝️
A compliant iSCSI implementation MUST meet the cryptographic key management requirements of the IPsec protocol suite. Authentication, security association negotiation, and cryptographic key management MUST be provided by implementing IKE [RFC2409] using the IPsec DOI [RFC2407], and they SHOULD be provided by implementing IKEv2 [RFC5996], with the following iSCSI-specific requirements:
- a) Peer authentication using a pre-shared cryptographic key MUST be supported. Certificate-based peer authentication using digital signatures MAY be supported. For IKEv1 ([RFC2409]), peer authentication using the public key encryption methods outlined in Sections 5.2 and 5.3 of [RFC2409] SHOULD NOT be used.
- b) When digital signatures are used to achieve authentication, an IKE negotiator SHOULD use IKE Certificate Request Payload(s) to specify the certificate authority. IKE negotiators SHOULD check certificate validity via the pertinent Certificate Revocation List (CRL) or via the use of the Online Certificate Status Protocol (OCSP) [RFC6960] before accepting a PKI certificate for use in IKE authentication procedures. OCSP support within the IKEv2 protocol is specified in [RFC4806]. These checks may not be needed in environments where a small number of certificates are statically configured as trust anchors.
- c) Conformant iSCSI implementations of IKEv1 MUST support Main Mode and SHOULD support Aggressive Mode. Main Mode with a pre-shared key authentication method SHOULD NOT be used when either the initiator or the target uses dynamically assigned addresses. While in many cases pre-shared keys offer good security, situations in which dynamically assigned addresses are used force the use of a group pre-shared key, which creates vulnerability to a man-in-the-middle attack 😱
- d) In the IKEv1 Phase 2 Quick Mode, in exchanges for creating the Phase 2 SA, the Identification Payload MUST be present.
- e) The following identification type requirements apply to IKEv1:
ID_IPV4_ADDR,ID_IPV6_ADDR(if the protocol stack supports IPv6), andID_FQDNIdentification Types MUST be supported;ID_USER_FQDNSHOULD be supported. The IP Subnet, IP Address Range,ID_DER_ASN1_DN, andID_DER_ASN1_GNIdentification Types SHOULD NOT be used. TheID_KEY_IDIdentification Type MUST NOT be used. - f) If IKEv2 is supported, the following identification requirements apply:
ID_IPV4_ADDR,ID_IPV6_ADDR(if the protocol stack supports IPv6), andID_FQDNIdentification Types MUST be supported;ID_RFC822_ADDRSHOULD be supported. TheID_DER_ASN1_DNandID_DER_ASN1_GNIdentification Types SHOULD NOT be used. TheID_KEY_IDIdentification Type MUST NOT be used.
The reasons for the "MUST NOT" and "SHOULD NOT" for identification type requirements in preceding bullets e) and f) are:
- IP Subnet and IP Address Range are too broad to usefully identify an iSCSI endpoint 🙃
- The DN and GN types are X.500 identities. It is usually better to use an identity from subjectAltName in a PKI certificate 📜
ID_KEY_IDis not interoperable as specified 💀
Manual cryptographic keying MUST NOT be used, because it does not provide the necessary rekeying support 🚫
When Diffie-Hellman (DH) groups are used, a DH group of at least 2048 bits SHOULD be offered as a part of all proposals to create IPsec security associations to protect iSCSI traffic, with both IKEv1 and IKEv2 🔐
When IPsec is used, the receipt of an IKEv1 Phase 2 delete message or an IKEv2 INFORMATIONAL exchange that deletes the SA SHOULD NOT be interpreted as a reason for tearing down the iSCSI TCP connection. If additional traffic is sent on it, a new IKE SA will be created to protect it 🦋
The method used by the initiator to determine whether the target should be connected using IPsec is regarded as an issue of IPsec policy administration, and thus it is not defined in the iSCSI standard 🌷
The method used by an initiator that supports both IPsec v2 and v3 to determine which versions of IPsec are supported by the target is also regarded as an issue of IPsec policy administration, and thus it is not defined in the iSCSI standard. If both IPsec v2 and v3 are supported by both the initiator and target, the use of IPsec v3 is recommended ✨
If an iSCSI target is discovered via a SendTargets request in a Discovery session not using IPsec, the initiator should assume that it does not need IPsec to establish a session to that target. If an iSCSI target is discovered using a Discovery session that does use IPsec, the initiator SHOULD use IPsec when establishing a session to that target 🌈
9.4. Security Considerations for the X#NodeArchitecture Key 🔐
okay bestie, this part is all about the X#NodeArchitecture key 🎀 The security stuff here is specific to the X#NodeArchitecture discussed in Section 13.26, so it's a whole vibe of its own.
This extension key basically announces the nitty-gritty implementation details of the node that sends it 👀 In some environments, those details are sensitive. Like, if a certain software or firmware version is known to have security weaknesses, shouting that version out through this key is NOT giving safe 🙈 Here are the countermeasures for this security concern, bestie 💅:
- a) sending less detailed information in the key values,
- b) not sending the extension key, or
- c) using IPsec ([RFC4303]) to provide confidentiality for the iSCSI connection on which the key is sent.
To cover the first two countermeasures, all implementations of this extension key MUST provide an administrative mechanism to disable sending the key 🛑 On top of that, all implementations SHOULD provide an administrative mechanism to configure a verbosity level of the key value, so you can control how much info gets sent ✨
For example, a lower verbosity level might enable transmission of node architecture component names only, but no version numbers 🧚 The choice of which countermeasure is most appropriate depends on the environment. However, sending less detailed information in the key values may be an acceptable countermeasure in many environments, since it's a compromise between sending too much information and the other more complete countermeasures of not sending the key at all or using IPsec 🫶
Also, it's not just about what gets transmitted! Any logging method(s) used for the key values MUST keep the information secure from intruders 🕵️♀️ For all implementations, the requirements to address this security concern are as follows:
- a) Display of the log MUST only be possible with administrative rights to the node.
- b) Options to disable logging to disk and to keep logs for a fixed duration SHOULD be provided.
Finally, it's important to note that different nodes may have different levels of risk, and these differences may affect the implementation 🌈 The components of risk include assets, threats, and vulnerabilities. Consider the following example iSCSI nodes, which demonstrate differences in assets and vulnerabilities of the nodes, and, as a result, differences in implementation:
- a) One iSCSI target based on a special-purpose operating system: Since the iSCSI target controls access to the data storage containing company assets, the asset level is seen as very high. Also, because of the special-purpose operating system, in which vulnerabilities are less well known, the vulnerability level is viewed as low.
- b) Multiple iSCSI initiators in a blade farm, each running a general-purpose operating system: The asset level of each node is viewed as low, since blades are replaceable and low cost. However, the vulnerability level is viewed as high, since there may be many well-known vulnerabilities to that general-purpose operating system. For this target, an appropriate implementation might be the logging of received key values but no transmission of the key. For this initiator, an appropriate implementation might be transmission of the key but no logging of received key values. 💜
9.5. SCSI Access Control Considerations 🗝️
okay so iSCSI is a SCSI transport protocol, which means it doesn't apply any access controls on SCSI-level operations like SCSI task management functions (e.g., LU reset; see Section 11.5.1) 🙃 SCSI-level access controls (e.g., ACCESS CONTROL OUT; see [SPC3]) have to be appropriately deployed in practice to address SCSI-level security considerations. That's on top of the security via iSCSI connection and packet protection mechanisms we already talked about in the earlier sections 💖
10. Notes to Implementers 🛠️
this section is all about some of the performance and reliability considerations of the iSCSI protocol 🍓 This protocol was designed to allow efficient silicon and software implementations. The iSCSI task tag mechanism was designed to enable Direct Data Placement (DDP -- a DMA form) at the iSCSI level or lower ⚡
The guiding assumption made throughout the design of this protocol is that targets are resource constrained relative to initiators 🥺
Implementers are also advised to consider the implementation consequences of the iSCSI-to-SCSI mapping model as outlined in Section 4.4.3 📝
10.1. Multiple Network Adapters 🦋
The iSCSI protocol allows multiple connections, and they don't all need to go over the same network adapter 🌸 If multiple network connections are to be utilized with hardware support, the iSCSI protocol command-data-status allegiance to one TCP connection ensures that there is no need to replicate information across network adapters or otherwise require them to cooperate. Honestly, that's so clean ✨
However, some task management commands may require some loose form of cooperation or replication at least on the target 👀
10.1.1. Conservative Reuse of ISIDs 🧁
Historically, the SCSI model (and implementations and applications based on that model) has assumed that SCSI ports are static, physical entities. Recent extensions to the SCSI model have taken advantage of persistent worldwide unique names for these ports. In iSCSI, however, the SCSI initiator ports are the endpoints of dynamically created sessions, so the presumptions of "static and physical" do not apply 🫠 In any case, the "model" sections (particularly, Section 4.4.1) provide for persistent, reusable names for the iSCSI-type SCSI initiator ports even though there does not need to be any physical entity bound to these names.
To both minimize the disruption of legacy applications and better facilitate the SCSI features that rely on persistent names for SCSI ports, iSCSI implementations SHOULD attempt to provide a stable presentation of SCSI initiator ports (both to the upper OS layers and the targets to which they connect) 💅 This can be achieved in an initiator implementation by conservatively reusing ISIDs. In other words, the same ISID should be used in the login process to multiple target portal groups (of the same iSCSI target or different iSCSI targets).
The ISID RULE (Section 4.4.3) only prohibits reuse to the same target portal group. It does not "preclude" reuse to other target portal groups. The principle of conservative reuse "encourages" reuse to other target portal groups 🎀 When a SCSI target device sees the same (InitiatorName, ISID) pair in different sessions to different target portal groups, it can identify the underlying SCSI initiator port on each session as the same SCSI port. In effect, it can recognize multiple paths from the same source. Main character energy 👑
10.1.2. iSCSI Name, ISID, and TPGT Use 🪪
The designers of the iSCSI protocol are aware that legacy SCSI transports rely on initiator identity to assign access to storage resources 📦 Although newer techniques that simplify access control are available, support for configuration and authentication schemes that are based on initiator identity is deemed important in order to support legacy systems and administration software. iSCSI thus supports the notion that it should be possible to assign access to storage resources based on "initiator device" identity.
When there are multiple hardware or software components coordinated as a single iSCSI node, there must be some (logical) entity that represents the iSCSI node that makes the iSCSI Node Name available to all components involved in session creation and login. Similarly, this entity that represents the iSCSI node must be able to coordinate session identifier resources (the ISID for initiators) to enforce both the ISID RULE and the TSIH RULE (see Section 4.4.3) 🔑
For targets, because of the closed environment, implementation of this entity should be straightforward. However, vendors of iSCSI hardware (e.g., NICs or HBAs) intended for targets SHOULD provide mechanisms for configuration of the iSCSI Node Name across the portal groups instantiated by multiple instances of these components within a target 🌈
However, complex targets making use of multiple Target Portal Group Tags may reconfigure them to achieve various quality goals. The initiators have two mechanisms at their disposal to discover and/or check reconfiguring targets: the Discovery session type and a key returned by the target during login to confirm the TPGT. An initiator should attempt to "rediscover" the target configuration whenever a session is terminated unexpectedly 🕵️♀️
For initiators, in the long term, it is expected that operating system vendors will take on the role of this entity and provide standard APIs that can inform components of their iSCSI Node Name and can configure and/or coordinate ISID allocation, use, and reuse 🖥️
Recognizing that such initiator APIs are not available today, other implementations of the role of this entity are possible. For example, a human may instantiate the (common) node name as part of the installation process of each iSCSI component involved in session creation and login. This may be done by pointing the component to either a vendor-specific location for this datum or a system-wide location. The structure of the ISID namespace (see Section 11.12.5 and [RFC3721]) facilitates implementation of the ISID coordination by allowing each component vendor to independently (of other vendor's components) coordinate allocation, use, and reuse of its own partition of the ISID namespace in a vendor-specific manner. Partitioning of the ISID namespace within initiator portal groups managed by that vendor allows each such initiator portal group to act independently of all other portal groups when selecting an ISID for a login; this facilitates enforcement of the ISID RULE (see Section 4.4.3) at the initiator 🧚
A vendor of iSCSI hardware (e.g., NICs or HBAs) intended for use in initiators MUST implement a mechanism for configuring the iSCSI Node Name. Vendors and administrators must ensure that iSCSI Node Names are worldwide unique. It is therefore important that when one chooses to reuse the iSCSI Node Name of a disabled unit, one does not reassign that name to the original unit unless its worldwide uniqueness can be ascertained again 🚨
In addition, a vendor of iSCSI hardware must implement a mechanism to configure and/or coordinate ISIDs for all sessions managed by multiple instances of that hardware within a given iSCSI node. Such configuration might be either permanently preassigned at the factory (in a necessarily globally unique way), statically assigned (e.g., partitioned across all the NICs at initialization in a locally unique way), or dynamically assigned (e.g., on-line allocator, also in a locally unique way). In the latter two cases, the configuration may be via public APIs (perhaps driven by an independent vendor's software, such as the OS vendor) or private APIs driven by the vendor's own software 🫶
The process of name assignment and coordination has to be as encompassing and automated as possible, as years of legacy usage have shown that it is highly error-prone 😭 It should be mentioned that today SCSI has alternative schemes of access control that can be used by all transports, and their security is not dependent on strict naming coordination. 💜
10.2. Autosense and Auto Contingent Allegiance (ACA) 💅
Okay bestie, so Autosense is the vibe where sense data gets sent back to the initiator automatically whenever a command doesn't finish successfully 🫶. iSCSI initiators and targets MUST support and use Autosense, no exceptions, periodt 💖.
ACA is all about keeping commands in line even when things go sideways 🦋. There can be a ton of commands in flight between an initiator and a target at once, and SCSI initiator functionality in some operating systems leans on ACA to keep ordered command execution during error recovery. So iSCSI initiator implementations for those operating systems need to support ACA, fr fr. To make error recovery work for those OSes and their initiators, iSCSI targets SHOULD support ACA ✨.
10.3. iSCSI Timeouts ⏰
Lowkey, iSCSI recovery actions depend on iSCSI timeouts getting noticed and handled before SCSI timeouts do 😭. Picking the right timeouts for things like command acknowledgments, status acknowledgments, and so on is super dependent on your infrastructure (hardware, links, the TCP/IP stack, the iSCSI driver, all of it) 🧚.
As a little guide, the implementer may use an average NOP-Out/NOP-In turnaround delay multiplied by a "safety factor" (e.g., 4) as a good estimate for the basic delay of the iSCSI stack for a given connection. The safety factor should account for network load variability. For connection teardown, the implementer may want to also consider TCP common practice for the given infrastructure 🌸.
Text negotiations MAY also be subject to time limits or limits in the number of exchanges. Those limits SHOULD be generous enough to avoid affecting interoperability (e.g., allowing each key to be negotiated on a separate exchange). Give them room to breathe, no cap 🫶.
The relationship between iSCSI timeouts and SCSI timeouts is also a whole thing 👀. SCSI timeouts should be longer than iSCSI timeouts plus the time required for iSCSI recovery whenever iSCSI recovery is planned. Alternatively, an implementer may choose to interlock iSCSI timeouts and recovery with SCSI timeouts, so that SCSI recovery only becomes active where iSCSI isn't planned to recover, or failed to recover. Iconic energy 👑.
The implementer may also want to think about how various iSCSI exception events (like a digest failure) interact with later timeouts 🙈. When iSCSI error recovery is active, a digest failure is likely to result in discovering a missing command or data PDU. In those cases, an implementer may want to lower the timeout values so recovery procedures can kick off faster ⚡.
10.4. Command Retry and Cleaning Old Command Instances 🧹
Okay so the goal here is to stop old, retried command instances from sneaking into a valid command window after a command sequence number wraparound 🙅♀️. The protocol requires (see Section 4.2.2.1) that on every connection where a retry has been issued, a non-immediate command be issued and acknowledged within an interval of 2**31 - 1 commands from the CmdSN of the retried command. There are several ways an implementation can make that happen 🎀.
The simplest technique is to send a (non-retry) non-immediate SCSI command (or a NOP if no SCSI command is available for a while) after every command retry on the connection where the retry was attempted. Because errors are deemed rare events, this technique is probably the most effective, since it doesn't involve extra checks at the initiator when issuing commands. Main character energy, literally 💅.
10.5. Sync and Steering Layer, and Performance 🚀
Sync and Steering is optional, but if an initiator or target doesn't have it working against a peer that demands sync and steering, performance can take a hit from packet reordering and loss 😬. Providing a sync and steering mechanism is recommended for all high-speed implementations 🔥.
10.6. Considerations for State-Dependent Devices and Long-Lasting SCSI Operations 📼
Sequential access devices run on the idea that the device's position depends on the last command it processed 🎞️. So command processing order, and knowing whether the previous command was processed, are everything when it comes to keeping data intact. Inadvertent retries of SCSI commands when it's not known whether the previous one was processed are a real data integrity risk, bestie 😱.
Picture this: a sequential access device gets a SCSI SPACE command to backspace one filemark, and it gets reissued because no status came back for the first one. If the first SPACE command was actually processed, the reissued SPACE command, if processed, will change the position again. Then a later write lands in the wrong spot, and whatever data was there gets overwritten 💀.
For a medium changer device, imagine an EXCHANGE MEDIUM command where the SOURCE ADDRESS and DESTINATION ADDRESS are the same (so it performs a swap), and it's reissued because no status was received. If the first EXCHANGE MEDIUM command was actually processed, the reissued one, if processed, performs the swap again. The net effect is that no swap happened at all, which puts data integrity at risk 🥲.
All commands that change the state of the device (e.g., SPACE commands for sequential access devices and EXCHANGE MEDIUM commands for medium changer devices) MUST be issued as non-immediate commands for deterministic and ordered delivery to iSCSI targets. Non-negotiable 🙅♀️.
For a lot of those state-changing commands, the execution model also assumes the command is executed exactly once. Devices implementing READ POSITION and LOCATE give you a way to do SCSI-level command recovery, and new tape-class devices should support those commands. Without them, a SCSI-level retry is difficult, and error recovery at the iSCSI level is advisable 🛠️.
Devices running on long-latency delivery subsystems and doing long-lasting SCSI operations may need mechanisms that let them replace connections while commands are still running (e.g., during an extended copy operation) 🌈.
10.6.1. Determining the Proper ErrorRecoveryLevel 🧠
Choosing and using a specific ErrorRecoveryLevel should be based on the deployment scenarios of a given iSCSI implementation 🍓. Generally, these factors need a look before you pick the right level of recovery:
- a) Application resilience to I/O failures.
- b) Required level of availability in the face of transport connection failures.
- c) Probability of transport-layer "checksum escape" (message error undetected by TCP checksum -- see [RFC3385] for related discussion). This in turn decides the iSCSI digest failure frequency, and thus the criticality of iSCSI-level error recovery. The details of estimating this probability are outside the scope of this document.
Looking at those factors for SCSI tape devices as an example, implementations SHOULD use ErrorRecoveryLevel=1 when transport connection failure isn't a concern and SCSI-level recovery is unavailable, and ErrorRecoveryLevel=2 when there's a high likelihood of connection failure during a backup/retrieval 💜.
For extended copy operations, implementations SHOULD use ErrorRecoveryLevel=2 whenever there is a relatively high likelihood of connection failure 🫶.
10.7. Multi-Task Abort Implementation Considerations 🚨
Multi-task abort operations usually get issued in emergencies, like clearing a device lock-up or an HA failover/failback 🆘. In those moments you want to rip through error handling fast, instead of the target sitting around waiting on multiple third-party initiators that might not even be functional anymore. That's especially true if the emergency was triggered by one of those initiators failing 😭. So both iSCSI target and initiator implementations SHOULD support FastAbort multi-task abort semantics (Section 4.2.3.4) 🦋.
Heads up: in both standard semantics (Section 4.2.3.3) and FastAbort semantics (Section 4.2.3.4), there may be outstanding data transfers even after the TMF completion is reported on the issuing session. For iSCSI/iSER [RFC7145], these would be tagged data transfers for STags not owned by any active tasks. Whether or not real buffers support these data transfers is implementation dependent. However, the data transfers logically MUST be silently discarded by the target iSCSI layer in all cases 🙈.
A target MAY, on an implementation-defined internal timeout, also choose to drop the connections on which it did not receive the expected Data-Out sequences (Section 4.2.3.3) or NOP-Out acknowledgments (Section 4.2.3.4). That way it can reclaim the associated buffer, STag, and TTT resources as appropriate 🧺.
11. iSCSI PDU Formats 📦
All multi-byte integers specified in formats defined in this document are to be represented in network byte order (i.e., big-endian). For any field that appears in this document, the most significant byte is the lowest numbered byte, and the most significant bit (within byte or field) is the lowest numbered bit, unless specified otherwise. Bit-order math, but make it cute 🎀.
Any compliant sender MUST set all bits not defined, and all reserved fields, to 0, unless specified otherwise. Any compliant receiver MUST ignore any bit not defined and all reserved fields, unless specified otherwise. Receipt of reserved code values in defined fields MUST be reported as a protocol error 🚫.
Reserved fields are marked by the word "reserved", some abbreviation of "reserved", or by "." for individual bits when no other form of marking is technically feasible ✨.
11.1. iSCSI PDU Length and Padding 🧸
iSCSI PDUs are padded to the closest integer number of 4-byte words. The padding bytes SHOULD be sent as 0. Tiny but mighty 🌷.
11.2. PDU Template, Header, and Opcodes ✨
okay bestie, every iSCSI PDU is built from one or more header segments and, if it needs one, a data segment 🎀 After the whole header segment group, a header digest MAY pop up, and the data segment MAY also get a data digest tacked on at the end 🫶
The Basic Header Segment (BHS) is always first, and it's a fixed 48 bytes, no drama 💅 It MAY be followed by Additional Header Segments (AHS), a Header-Digest, a Data Segment, and/or a Data-Digest. Mix and match 🦋
Here's the overall layout:
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0/ Basic Header Segment (BHS) /
+/ /
+---------------+---------------+---------------+---------------+
48/ Additional Header Segment 1 (AHS) (optional) /
+/ /
+---------------+---------------+---------------+---------------+
/ Additional Header Segment 2 (AHS) (optional) /
+/ /
+---------------+---------------+---------------+---------------+
+---------------+---------------+---------------+---------------+
/ Additional Header Segment n (AHS) (optional) /
+/ /
+---------------+---------------+---------------+---------------+
k/ Header-Digest (optional) /
+/ /
+---------------+---------------+---------------+---------------+
l/ Data Segment (optional) /
+/ /
+---------------+---------------+---------------+---------------+
m/ Data-Digest (optional) /
+/ /
+---------------+---------------+---------------+---------------+Everything (segments and digests) gets padded out to the nearest whole 4-byte word 🍓 So every segment and digest starts on a 4-byte word boundary, and the padding is anywhere from 0 to 3 bytes. The padding bytes SHOULD be sent as 0 🌸
iSCSI Response PDUs do not have AH Segments. 🙈
11.2.1. Basic Header Segment (BHS) 💜
The BHS is 48 bytes long 🧚 The Opcode and DataSegmentLength fields show up in every iSCSI PDU. When they're used, the Initiator Task Tag and Logical Unit Number always sit in the same spot in the header, which is honestly so convenient 😭
Here's the BHS format:
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0|.|I| Opcode |F| Opcode-specific fields |
+---------------+---------------+---------------+---------------+
4|TotalAHSLength | DataSegmentLength |
+---------------+---------------+---------------+---------------+
8| LUN or Opcode-specific fields |
+ +
12| |
+---------------+---------------+---------------+---------------+
16| Initiator Task Tag |
+---------------+---------------+---------------+---------------+
20/ Opcode-specific fields /
+/ /
+---------------+---------------+---------------+---------------+
4811.2.1.1. I (Immediate) Bit ⚡
For Request PDUs, the I bit set to 1 is an immediate delivery marker. Main character energy, it says "deliver me now" 🔥
11.2.1.2. Opcode 🎯
The Opcode tells you what kind of iSCSI PDU the header is wrapping.
Opcodes come in two flavours: initiator Opcodes and target Opcodes. Initiator Opcodes ride in PDUs the initiator sends (Request PDUs). Target Opcodes ride in PDUs the target sends (Response PDUs).
Initiators MUST NOT use target Opcodes, and targets MUST NOT use initiator Opcodes. Don't be that friend who reads the other person's diary 🙅♀️
Here are the initiator Opcodes defined in this specification:
0x00 NOP-Out
0x01 SCSI Command (encapsulates a SCSI Command Descriptor
Block)
0x02 SCSI Task Management Function Request
0x03 Login Request
0x04 Text Request
0x05 SCSI Data-Out (for write operations)
0x06 Logout Request
0x10 SNACK Request
0x1c-0x1e Vendor-specific codesAnd the target Opcodes are:
0x20 NOP-In
0x21 SCSI Response - contains SCSI status and possibly sense
information or other response information
0x22 SCSI Task Management Function Response
0x23 Login Response
0x24 Text Response
0x25 SCSI Data-In (for read operations)
0x26 Logout Response
0x31 Ready To Transfer (R2T) - sent by target when it is ready
to receive data
0x32 Asynchronous Message - sent by target to indicate certain
special conditions
0x3c-0x3e Vendor-specific codes
0x3f RejectEvery other Opcode is unassigned, so hands off 🚫
11.2.1.3. F (Final) Bit 🏁
When this is set to 1, it means "this is the final (or only) PDU of a sequence." Done and dusted ✨
11.2.1.4. Opcode-Specific Fields 🧩
These fields mean different things depending on the Opcode type, so always check which Opcode you're dealing with first 🙈
11.2.1.5. TotalAHSLength 📏
This is the total length of all AHS header segments, counted in 4-byte words and including padding (if there is any).
TotalAHSLength is only used in PDUs that have an AHS, and it MUST be 0 in all other PDUs. No freeloading 💀
11.2.1.6. DataSegmentLength 📦
This is the data segment payload length in bytes, not counting padding.
DataSegmentLength MUST be 0 whenever the PDU has no data segment. Empty means zero, periodt 💖
11.2.1.7. LUN 🎀
Some Opcodes work on a specific LU, and the Logical Unit Number (LUN) field is how you say which one 💅 If the Opcode doesn't relate to an LU, this field is either ignored or may be used in an Opcode-specific way.
The LUN field is 64 bits and should be formatted in accordance with [SAM2]. For example, LUN[0] from [SAM2] is BHS byte 8, and it keeps going like that up to LUN[7] from [SAM2], which is BHS byte 15 🌈
11.2.1.8. Initiator Task Tag 🏷️
The initiator gives each iSCSI task it issues a task tag. While a task exists, this tag MUST uniquely identify the task session-wide. SCSI can also use the Initiator Task Tag as part of the SCSI task identifier, when the timespan where an iSCSI Initiator Task Tag has to be unique covers the timespan where a SCSI task tag has to be unique. Still, the iSCSI Initiator Task Tag must exist and be unique even for untagged SCSI commands. Unique tags only, no copycats 👯♀️
An ITT value of 0xffffffff is reserved, and it MUST NOT be assigned for a task by the initiator. The only place it may be seen on the wire is in a target-initiated NOP-In PDU (Section 11.19), and in the initiator response to that PDU if it's needed 🧚
Reserved means reserved. 0xffffffff is off-limits for task tags, so don't even think about it 🙅♀️
11.2.2. Additional Header Segment (AHS) 🧁
The general format of an AHS looks like this:
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0| AHSLength | AHSType | AHS-Specific |
+---------------+---------------+---------------+---------------+
4/ AHS-Specific /
+/ /
+---------------+---------------+---------------+---------------+
x11.2.2.1. AHSType 🔖
The AHSType field is coded like this:
bit 0-1 - Reserved
bit 2-7 - AHS code
0 - Reserved
1 - Extended CDB
2 - Bidirectional Read Expected Data Transfer Length
3 - 63 Reserved11.2.2.2. AHSLength 📐
This field holds the effective length of the AHS in bytes. It leaves out AHSType, AHSLength, and any padding. The AHS gets padded to the smallest whole number of 4-byte words, which means anywhere from 0 up to 3 padding bytes 🍰
11.2.2.3. Extended CDB AHS 🧳
The Extended CDB AHS looks like this:
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0| AHSLength (CDBLength - 15) | 0x01 | Reserved |
+---------------+---------------+---------------+---------------+
4/ ExtendedCDB...+padding /
+/ /
+---------------+---------------+---------------+---------------+
xThis type of AHS MUST NOT be used if the CDBLength is less than 17. Not for small CDBs, sorry 🙅♀️
The length includes the reserved byte 3, so count it in 🧮
11.2.2.4. Bidirectional Read Expected Data Transfer Length AHS 🔁
Here's the format of the Bidirectional Read Expected Data Transfer Length AHS:
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0| AHSLength (0x0005) | 0x02 | Reserved |
+---------------+---------------+---------------+---------------+
4| Bidirectional Read Expected Data Transfer Length |
+---------------+---------------+---------------+---------------+
811.2.3. Header Digest and Data Digest 🛡️
Optional header and data digests protect the integrity of the header and the data, respectively. If they're there, the digests sit after the header and the PDU-specific data. They cover the header and PDU data respectively, and each one includes the padding bytes (if any) 🫶
Whether digests exist and what type they are gets negotiated during the Login Phase, so that's where the deal gets made 🤝
Separating the header digest from the data digest is handy in iSCSI routing apps. When a message gets forwarded, usually only the header changes, so only the header digest should be recalculated. Efficiency queen behavior 👑
Digests are not included in data or header length fields. They're their own thing 🌸
A zero-length Data Segment also implies a zero-length Data-Digest. No data, no data digest, simple 💜
11.2.4. Data Segment 📦
The (optional) Data Segment carries PDU-associated data. Its payload effective length is given in the BHS field -- DataSegmentLength. The Data Segment also gets padded out to a whole number of 4-byte words 🍓
11.3. SCSI Command 💖
okay so the SCSI Command PDU has its own layout, and it's giving structured 🎀
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0|.|I| 0x01 |F|R|W|. .|ATTR | Reserved |
+---------------+---------------+---------------+---------------+
4|TotalAHSLength | DataSegmentLength |
+---------------+---------------+---------------+---------------+
8| Logical Unit Number (LUN) |
+ +
12| |
+---------------+---------------+---------------+---------------+
16| Initiator Task Tag |
+---------------+---------------+---------------+---------------+
20| Expected Data Transfer Length |
+---------------+---------------+---------------+---------------+
24| CmdSN |
+---------------+---------------+---------------+---------------+
28| ExpStatSN |
+---------------+---------------+---------------+---------------+
32/ SCSI Command Descriptor Block (CDB) /
+/ /
+---------------+---------------+---------------+---------------+
48/ AHS (optional) /
+---------------+---------------+---------------+---------------+
x/ Header-Digest (optional) /
+---------------+---------------+---------------+---------------+
y/ (DataSegment, Command Data) (optional) /
+/ /
+---------------+---------------+---------------+---------------+
z/ Data-Digest (optional) /
+---------------+---------------+---------------+---------------+11.3.1. Flags and Task Attributes (Byte 1) 🚩
the flags for this PDU are sooo specific, let's go:
bit 0(F) is set to 1 when no unsolicited SCSI Data-Out PDUs follow this PDU. when F = 1 for a write and the Expected Data Transfer Length is larger than the DataSegmentLength, the target can solicit extra data through R2T 🫶bit 1(R) is set to 1 when the command is expected to input data 📥bit 2(W) is set to 1 when the command is expected to output data 📤bit 3-4is Reserved 🤫bit 5-7holds Task Attributes ✨
Task Attributes (ATTR) have one of these integer values (see [SAM2] for the deets):
0- Untagged1- Simple2- Ordered3- Head of queue4- ACA5-7- Reserved
At least one of the W and F bits MUST be set to 1. that's the main rule, no debate 💅
Either or both of R and W MAY be 1 when the Expected Data Transfer Length and/or the Bidirectional Read Expected Data Transfer Length are 0. but they MUST NOT both be 0 when those lengths are not 0. so basically, if some data transfer is expected, the direction gets flagged by the R and/or W bit 🦋
11.3.2. CmdSN - Command Sequence Number 🌸
the CmdSN is what makes ordered delivery work across multiple connections in a single session. it's the main character of ordering 👑
11.3.3. ExpStatSN 🧚
command responses up to ExpStatSN - 1 (modulo 2**32) have been received, which means the status is acknowledged on the connection. ack-ack 💜
11.3.4. Expected Data Transfer Length 📏
for unidirectional operations, this field has the number of bytes of data involved in the SCSI operation. for a unidirectional write (W flag set to 1 and R flag set to 0), the initiator uses it to say how many bytes it expects to send for this operation. for a unidirectional read (W flag set to 0 and R flag set to 1), the initiator uses it to say how many bytes it expects the target to send back. it lines up with the SAM-2 byte count 🎯
for bidirectional operations (both R and W flags set to 1), this field holds the number of data bytes involved in the write transfer. for bidirectional operations, an additional header segment MUST be present in the header sequence, and it has to show the Bidirectional Read Expected Data Transfer Length. both of these fields correspond to the SAM-2 byte count, which is so iconic of them 🔥
if the Expected Data Transfer Length for a write and the length of the immediate data after the command (if there is any) are the same, then no more data PDUs are coming. in that case the F bit MUST be set to 1 🛑
if the Expected Data Transfer Length is higher than the FirstBurstLength (the negotiated max amount of unsolicited data the target will accept), the initiator MUST send the maximum amount of unsolicited data OR ONLY the immediate data, if any. no extra drama 🙅♀️
when a data transfer finishes, the target tells the initiator, through residual counts, how many bytes it actually processed (sent and/or received) 📊
11.3.5. CDB - SCSI Command Descriptor Block 📦
the CDB field has 16 bytes to fit the commonly used CDBs. whenever the CDB is larger than 16 bytes, an Extended CDB AHS MUST be used to hold the CDB spillover. big CDBs are not invited to the 16-byte party without their own AHS 🎀
11.3.6. Data Segment - Command Data 🍓
some SCSI commands need extra parameter data to come along with the command. that data can go past the iSCSI header in a data segment. or user data (like from a write operation) can go in the data segment too. both of those are called immediate data. these data follow the solicited vs. unsolicited rules in Section 4.2.5.2, so go check that out 🧠
11.4. SCSI Response 💌
the SCSI Response PDU has its own layout, slay 👑
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0|.|.| 0x21 |1|. .|o|u|O|U|.| Response | Status |
+---------------+---------------+---------------+---------------+
4|TotalAHSLength | DataSegmentLength |
+---------------+---------------+---------------+---------------+
8| Reserved |
+ +
12| |
+---------------+---------------+---------------+---------------+
16| Initiator Task Tag |
+---------------+---------------+---------------+---------------+
20| SNACK Tag or Reserved |
+---------------+---------------+---------------+---------------+
24| StatSN |
+---------------+---------------+---------------+---------------+
28| ExpCmdSN |
+---------------+---------------+---------------+---------------+
32| MaxCmdSN |
+---------------+---------------+---------------+---------------+
36| ExpDataSN or Reserved |
+---------------+---------------+---------------+---------------+
40| Bidirectional Read Residual Count or Reserved |
+---------------+---------------+---------------+---------------+
44| Residual Count or Reserved |
+---------------+---------------+---------------+---------------+
48| Header-Digest (optional) |
+---------------+---------------+---------------+---------------+
/ Data Segment (optional) /
+/ /
+---------------+---------------+---------------+---------------+
| Data-Digest (optional) |
+---------------+---------------+---------------+---------------+11.4.1. Flags (Byte 1) 🏳️🌈
bit 1-2is Reserved 🫥bit 3(o) is set for Bidirectional Read Residual Overflow. in this case, the Bidirectional Read Residual Count shows how many bytes were NOT sent to the initiator, because the initiator's Bidirectional Read Expected Data Transfer Length wasn't big enough 😤bit 4(u) is set for Bidirectional Read Residual Underflow. in this case, the Bidirectional Read Residual Count shows how many bytes weren't sent to the initiator out of the number that was expected 🥀bit 5(O) is set for Residual Overflow. the Residual Count shows how many bytes weren't transferred because the initiator's Expected Data Transfer Length was too small. for a bidirectional operation, the Residual Count holds the residual for the write operation 💅bit 6(U) is set for Residual Underflow. the Residual Count shows how many bytes weren't transferred out of the number that was expected. for a bidirectional operation, the Residual Count holds the residual for the write operation 🫠bit 7(0) is Reserved 🤐
Bits O and U and bits o and u are mutually exclusive, which means having both o and u, or both O and U, set to 1 is a protocol error. that is a hard no 🚫
For a response other than "Command Completed at Target", bits 3-6 MUST be 0. so only that one response type gets to use them 🎯
11.4.2. Status 🚦
the Status field reports the SCSI status of the command (as specified in [SAM2]). it is only valid if the response code is Command Completed at Target, so don't read it otherwise 👀
some of the status codes defined in [SAM2] are:
0x00GOOD ✅0x02CHECK CONDITION ⚠️0x08BUSY ⏳0x18RESERVATION CONFLICT 💀0x28TASK SET FULL 📚0x30ACA ACTIVE 🔒0x40TASK ABORTED 🙈
see [SAM2] for the full list and definitions. go be a completionist 🧚
if a SCSI device error gets detected while data from the initiator is still expected (the command PDU didn't have all the data and the target hasn't received a data PDU with the Final bit set), the target MUST wait until it gets a data PDU with the F bit set in the last expected sequence before it sends the Response PDU. it has to wait for the full story before it talks 🫶
11.4.3. Response ✨
Okay bestie, this field holds the iSCSI service response 🎀, which is basically the target's verdict on how the command went. 💅
The iSCSI service response codes defined in this specification are:
0x00- Command Completed at Target0x01- Target Failure0x80-0xff- Vendor specific
Every other response code is reserved, so hands off those 🙅♀️.
The Response field is how a service response gets reported 📣. Turning that code into a SCSI service response code value, if you need to, is outside the scope of this document 🧚. Symbolically though, a response value of 0x00 maps to the SCSI service response of TASK COMPLETE or LINKED COMMAND COMPLETE (see [SAM2] and [SPC3]) 💖. Every other Response value maps to SERVICE DELIVERY OR TARGET FAILURE 🥀.
If a SCSI Response PDU never shows up before the session gets terminated, the SCSI service response is SERVICE DELIVERY OR TARGET FAILURE 😭.
A non-zero response field means the command failed to execute 💀. In that case the Status and Flag fields are undefined, and they MUST be ignored on reception 🚫. Don't even look at them!
11.4.4. SNACK Tag 🌸
This field carries a copy of the SNACK Tag from the last SNACK Tag the target accepted on the same connection, for the command this response is for 🫶. If that doesn't apply, it's reserved and should be set to 0 🍓.
After you send an R-Data SNACK, the initiator must discard any SCSI status unless it's inside a SCSI Response PDU carrying the same SNACK Tag as the last R-Data SNACK issued for that SCSI command on the current connection 🙈. Super specific, very iconic.
For a deeper dive on R-Data SNACK, check Section 11.16.3 🦋.
11.4.5. Residual Count 🍰
11.4.5.1. Field Semantics
The Residual Count field MUST be valid whenever the U bit or the O bit is set 🔥. If neither bit is set, the Residual Count field MUST be ignored on reception and SHOULD be set to 0 when sending 💜. Targets may set the residual count, and initiators may use it when the response code is Command Completed at Target, even if the status returned isn't GOOD 👑.
If the O bit is set, the Residual Count tells you how many bytes weren't transferred because the initiator's Expected Data Transfer Length wasn't big enough 🦋. If the U bit is set, it tells you how many bytes weren't transferred out of the number of bytes that were expected to move 🌈.
11.4.5.2. Residuals Concepts Overview
"SCSI-Presented Data Transfer Length (SPDTL)" is the term this document uses (see Section 2.2 for the definition) to describe the total data length the target SCSI layer tries to move through the local iSCSI layer for a task ✨. "Expected Data Transfer Length (EDTL)" is the iSCSI term for how much data the iSCSI layer expects to transfer for a task 🧚. EDTL gets specified in the SCSI Command PDU 💌.
When SPDTL = EDTL for a task, the target iSCSI layer finishes the task with no residuals 💅. Whenever SPDTL differs from EDTL for a task, that task is said to have a residual 🥹.
If SPDTL > EDTL for a task, iSCSI Overflow MUST be signaled in the SCSI Response PDU, as specified in Section 11.4.5.1 🚨. The Residual Count MUST be set to the numerical value of (SPDTL - EDTL) 🍭.
If SPDTL < EDTL for a task, iSCSI Underflow MUST be signaled in the SCSI Response PDU, as specified in Section 11.4.5.1 🌷. The Residual Count MUST be set to the numerical value of (EDTL - SPDTL) 🫧.
Quick note: Overflow and Underflow are independent of Data-In and Data-Out 🦄. Either scenario can logically happen in either direction of data transfer, so don't mix them up 🙃.
11.4.5.3. SCSI REPORT LUNS Command and Residual Overflow
This section digs into residual overflow issues using the SCSI REPORT LUNS command as the example 🔍. Heads up though, several SCSI commands (INQUIRY, for example) have ALLOCATION LENGTH fields that follow the same underlying rules, and the rest of this section applies to all of them 💖.
The SCSI REPORT LUNS command asks a target SCSI layer to return a LU inventory (a LUN list) to the initiator SCSI layer (see Clause 6.21 of [SPC3]) 📋. The initiator SCSI layer might not know how big that LUN list is when it sends the command, so to avoid getting more LUN list data than it's ready for, the REPORT LUNS CDB has an ALLOCATION LENGTH field that sets the maximum amount of data to transfer 🧺. If the initiator underestimated how many LUs the target has, the complete inventory might not fit in that ALLOCATION LENGTH 😬. In that case, Clause 4.3.4.6 of [SPC3] says the target SCSI layer "shall terminate transfers to the Data-In Buffer" once the number of bytes specified by the ALLOCATION LENGTH field has been transferred 🛑.
So for a REPORT LUNS command, the SCSI layer at the target hands iSCSI at most ALLOCATION LENGTH bytes of LU inventory data to send to the initiator 🎀. If the iSCSI EDTL is at least as big as the ALLOCATION LENGTH, the SCSI truncation makes sure the EDTL can fit all the data that's going to be sent 🙌. If all of the LU inventory data handed to the iSCSI layer (the data left after any SCSI truncation) gets transferred to the initiator, there's no iSCSI Residual Overflow, and the iSCSI (O) bit MUST NOT be set in the SCSI Response or the final SCSI Data-Out PDU 🚫. This behavior is implied by Section 11.4.5.1 along with the REPORT LUNS command spec in [SPC3], so it's not a surprise 🧠. However, if the iSCSI EDTL is bigger than the ALLOCATION LENGTH in this scenario, the iSCSI Underflow MUST be signaled in the SCSI Response PDU 📣. An iSCSI Underflow MUST also be signaled when the iSCSI EDTL equals the ALLOCATION LENGTH but the LU inventory data handed to the iSCSI layer is smaller than the ALLOCATION LENGTH 🌸.
The LUN LIST LENGTH field, which is the first field in the LU inventory, isn't affected by truncating the inventory to fit in ALLOCATION LENGTH 🫶. That's the clever part! It lets a SCSI initiator spot an incomplete inventory by noticing that LUN LIST LENGTH is bigger than the ALLOCATION LENGTH it sent in the REPORT LUNS CDB 🕵️♀️. A common move in that situation is to reissue the REPORT LUNS command with a bigger ALLOCATION LENGTH 🚀.
11.4.6. Bidirectional Read Residual Count 🦋
The Bidirectional Read Residual Count field MUST be valid whenever the u bit or the o bit is set 💜. If neither bit is set, the Bidirectional Read Residual Count field is reserved 🌷. Targets may set the Bidirectional Read Residual Count, and initiators may use it when the response code is Command Completed at Target 💅. If the o bit is set, the field tells you how many bytes weren't transferred to the initiator because the initiator's Bidirectional Read Expected Data Transfer Length wasn't big enough 🍓. If the u bit is set, it tells you how many bytes weren't transferred to the initiator out of the number of bytes that were expected to be transferred ✨.
11.4.7. Data Segment - Sense and Response Data Segment 🧸
iSCSI targets MUST support and enable Autosense 🔐. If Status is CHECK CONDITION (0x02), then the data segment MUST contain sense data for the failed command 🚨.
For some iSCSI responses, the response data segment MAY contain some response-related information. For example, for a target failure it may hold a vendor-specific detailed description of the failure 🧚.
If the DataSegmentLength isn't 0, the data segment is laid out like this 👇:
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0|SenseLength | Sense Data |
+---------------+---------------+---------------+---------------+
x/ Sense Data /
+---------------+---------------+---------------+---------------+
y/ Response Data /
/ /
+---------------+---------------+---------------+---------------+11.4.7.1. SenseLength
This field tells you how long the Sense Data is 📏.
11.4.7.2. Sense Data
The Sense Data holds detailed info about a CHECK CONDITION 🕵️♀️. [SPC3] defines the format and content of the Sense Data 📚.
Certain iSCSI conditions cause the command to be terminated at the target (response code Command Completed at Target) with a SCSI CHECK CONDITION Status, as laid out in this next table 👀:
+--------------------------+-----------+---------------------------+
| iSCSI Condition |Sense | Additional Sense Code and |
| |Key | Qualifier |
+--------------------------+-----------+---------------------------+
| Unexpected unsolicited |Aborted | ASC = 0x0c ASCQ = 0x0c |
| data |Command-0B | Write Error |
+--------------------------+-----------+---------------------------+
| Incorrect amount of data |Aborted | ASC = 0x0c ASCQ = 0x0d |
| |Command-0B | Write Error |
+--------------------------+-----------+---------------------------+
| Protocol Service CRC |Aborted | ASC = 0x47 ASCQ = 0x05 |
| error |Command-0B | CRC Error Detected |
+--------------------------+-----------+---------------------------+
| SNACK rejected |Aborted | ASC = 0x11 ASCQ = 0x13 |
| |Command-0B | Read Error |
+--------------------------+-----------+---------------------------+The target reports the "Incorrect amount of data" condition if, during data output, the total data length to output is greater than FirstBurstLength, and the initiator sent unsolicited non-immediate data but the total amount of unsolicited data is different from FirstBurstLength 🙀. The target reports the same error when the amount of data sent as a reply to an R2T doesn't match the amount requested 😤.
11.4.8. ExpDataSN 🍭
This field tells you how many Data-In (read) PDUs the target has sent for the command 📬.
This field MUST be 0 if the response code isn't Command Completed at Target, or if the target sent no Data-In PDUs for the command 💖.
11.4.9. StatSN - Status Sequence Number 📊
okay so the StatSN is a sequence number that the target iSCSI layer makes per connection 💖 It's how the initiator says "yep, got your status" 🫶 The StatSN goes up by 1 for every response/status sent on a connection, except for responses sent as a result of a retry or SNACK. If the target is resending something because the initiator asked for a retransmission, the StatSN MUST be the same as the first time that PDU was sent, unless the connection has since been restarted. no cap, don't touch that number 🙈
11.4.10. ExpCmdSN - Next Expected CmdSN from This Initiator 🦋
ExpCmdSN is the sequence number the target sends back so the initiator knows its command got received ✨ The initiator uses it to update a local variable with the same name. An ExpCmdSN equal to MaxCmdSN + 1 means the target cannot accept new commands rn 💀
11.4.11. MaxCmdSN - Maximum CmdSN from This Initiator 🌸
MaxCmdSN is the sequence number the target returns to tell the initiator the maximum CmdSN it's allowed to send 👑 The initiator uses it to update a local variable with the same name. If MaxCmdSN is equal to ExpCmdSN - 1, that's the target saying it can't receive any more commands, so it's giving full stop 🛑 When the MaxCmdSN changes at the target while it has no pending PDUs to tell the initiator about that, the target MUST generate a NOP-In to carry the new MaxCmdSN. the vibe is "don't leave her on read" 💅
11.5. Task Management Function Request 🎀
Here's the layout of the Task Management Function Request PDU, bestie 🧚 Don't worry, it's just a bunch of boxes with numbers 💜
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0|.|I| 0x02 |1| Function | Reserved |
+---------------+---------------+---------------+---------------+
4|TotalAHSLength | DataSegmentLength |
+---------------+---------------+---------------+---------------+
8| Logical Unit Number (LUN) or Reserved |
+ +
12| |
+---------------+---------------+---------------+---------------+
16| Initiator Task Tag |
+---------------+---------------+---------------+---------------+
20| Referenced Task Tag or 0xffffffff |
+---------------+---------------+---------------+---------------+
24| CmdSN |
+---------------+---------------+---------------+---------------+
28| ExpStatSN |
+---------------+---------------+---------------+---------------+
32| RefCmdSN or Reserved |
+---------------+---------------+---------------+---------------+
36| ExpDataSN or Reserved |
+---------------+---------------+---------------+---------------+
40/ Reserved /
+/ /
+---------------+---------------+---------------+---------------+
48| Header-Digest (optional) |
+---------------+---------------+---------------+---------------+11.5.1. Function 💅
These task management functions give an initiator a way to explicitly control the execution of one or more tasks (SCSI and iSCSI tasks) ✨ Here are the function codes, all lined up for you 👑 For a more detailed description of SCSI task management, see [SAM2].
1 ABORT TASK - aborts the task identified by the Referenced Task
Tag field.
2 ABORT TASK SET - aborts all tasks issued via this session on
the LU.
3 CLEAR ACA - clears the Auto Contingent Allegiance condition.
4 CLEAR TASK SET - aborts all tasks in the appropriate task set
as defined by the TST field in the Control mode page
(see [SPC3]).
5 LOGICAL UNIT RESET
6 TARGET WARM RESET
7 TARGET COLD RESET
8 TASK REASSIGN - reassigns connection allegiance for the task
identified by the Initiator Task Tag field to this connection,
thus resuming the iSCSI exchanges for the task.Values 9-12 are assigned in [RFC7144]. All other possible values for the Function field are unassigned 🌈
For all these functions, the Task Management Function Response MUST be returned as detailed in Section 11.6. All these functions apply to the referenced tasks, whether they're proper SCSI tasks or tagged iSCSI operations 🦋 Task management requests must act on all the commands from the same session having a CmdSN lower than the task management CmdSN. LOGICAL UNIT RESET, TARGET WARM RESET, and TARGET COLD RESET may affect commands from other sessions or commands from the same session, regardless of their CmdSN value 🙈
If the task management request is marked for immediate delivery, it must be considered immediately for execution. The operations involved (all or part of them) may be postponed so the target can receive all relevant tasks ⭐ According to [SAM2], for all the tasks covered by the task management response (i.e., with a CmdSN lower than the task management command CmdSN), except for the task management response to a TASK REASSIGN, additional responses MUST NOT be delivered to the SCSI layer after the task management response. The iSCSI initiator MAY deliver to the SCSI layer all responses received before the task management response. (It's up to the implementation whether SCSI responses received before the task management response, but after the task management request was issued, get delivered to the SCSI layer by the iSCSI layer in the initiator.) The iSCSI target MUST ensure that no responses for the tasks covered by a task management function are delivered to the iSCSI initiator after the task management response, except for a task covered by a TASK REASSIGN 🫶
For ABORT TASK SET and CLEAR TASK SET, the issuing initiator MUST continue to respond to all valid Target Transfer Tags (received via R2T, Text Response, NOP-In, or SCSI Data-In PDUs) related to the affected task set, even after issuing the task management request 💖
The issuing initiator SHOULD, however, terminate (i.e., by setting the F bit to 1) these response sequences as quickly as possible 🏃♀️ The target for its part MUST wait for responses on all affected Target Transfer Tags before acting on either of these two task management requests. If all or part of the response sequence is not received (due to digest errors) for a valid TTT, the target MAY treat it as a case of a within-command error recovery class (see Section 7.1.4.1) if it is supporting ErrorRecoveryLevel >= 1. Alternatively, it may drop the connection to complete the requested task set function 😭
If an ABORT TASK is issued for a task created by an immediate command, then the RefCmdSN MUST be that of the task management request itself (i.e., the CmdSN and RefCmdSN are equal). Otherwise, the RefCmdSN MUST be set to the CmdSN of the task to be aborted (lower than the CmdSN) 🍓
If the connection is still active (i.e., it is not undergoing an implicit or explicit logout), an ABORT TASK MUST be issued on the same connection to which the task to be aborted is allegiant at the time the task management request is issued. If the connection is implicitly or explicitly logged out (i.e., no other request will be issued on the failing connection and no other response will be received on the failing connection), then an ABORT TASK function request may be issued on another connection. This task management request will then establish a new allegiance for the command to be aborted as well as abort it. (That means the task to be aborted won't have to be retried or reassigned, and its status, if it was sent but not acknowledged, will be resent followed by the task management response.) 🧚
At the target, an ABORT TASK function MUST NOT be executed on a task management request. Such a request MUST result in a task management response of "Function rejected" 🙅♀️
For the LOGICAL UNIT RESET function, the target MUST behave as dictated by the Logical Unit Reset function in [SAM2] 🔥
The implementation of the TARGET WARM RESET function and the TARGET COLD RESET function is OPTIONAL. When implemented, they should act as described below. The TARGET WARM RESET is also subject to SCSI access controls on the requesting initiator as defined in [SPC3]. When authorization fails at the target, the appropriate response as described in Section 11.6.1 MUST be returned by the target. The TARGET COLD RESET function is not subject to SCSI access controls, but its execution privileges may be managed by iSCSI mechanisms such as login authentication 🔐
When executing the TARGET WARM RESET and TARGET COLD RESET functions, the target cancels all pending operations on all LUs known by the issuing initiator. Both functions are equivalent to the TARGET RESET function specified by [SAM2]. They can affect many other initiators logged in with the servicing SCSI target port 💀
Additionally, the target MUST treat the TARGET COLD RESET function as a power-on event, thus terminating all of its TCP connections to all initiators (all sessions are terminated). For this reason, the service response (defined by [SAM2]) for this SCSI task management function may not be reliably delivered to the issuing initiator port 🥺
For the TASK REASSIGN function, the target should reassign the connection allegiance to this new connection (and thus resume iSCSI exchanges for the task). TASK REASSIGN MUST ONLY be received by the target after the connection on which the command was previously executing has been successfully logged out. The task management response MUST be issued before the reassignment becomes effective 🦋
For additional usage semantics, see Section 7.2 📚
At the target, a TASK REASSIGN function request MUST NOT be executed to reassign the connection allegiance of a Task Management Function Request, an active text negotiation task, or a Logout task. Such a request MUST result in a task management response of "Function rejected" 🚫
TASK REASSIGN MUST be issued as an immediate command ⚡
11.5.2. TotalAHSLength and DataSegmentLength 🍭
For this PDU, TotalAHSLength and DataSegmentLength MUST be 0 💖
11.5.3. LUN 🌷
This field is required for functions that address a specific LU (ABORT TASK, CLEAR TASK SET, ABORT TASK SET, CLEAR ACA, LOGICAL UNIT RESET). It's reserved in all others 🎀
11.5.4. Referenced Task Tag 🏷️
This is the Initiator Task Tag of the task to be aborted for the ABORT TASK function, or the task to be reassigned for the TASK REASSIGN function. For all the other functions, this field MUST be set to the reserved value 0xffffffff 🫧
11.5.5. RefCmdSN 🧾
If an ABORT TASK is issued for a task created by an immediate command, then the RefCmdSN MUST be that of the task management request itself (i.e., the CmdSN and RefCmdSN are equal) 💫
For an ABORT TASK of a task created by a non-immediate command, the RefCmdSN MUST be set to the CmdSN of the task identified by the Referenced Task Tag field. Targets must use this field as described in Section 11.6.1 when the task identified by the Referenced Task Tag field is not with the target 🌸
Otherwise, this field is reserved 🥰
11.5.6. ExpDataSN ✨
okay so ExpDataSN is basically the recovery bookmark 🔖 The iSCSI target and initiator both keep a data acknowledgment reference number, which is the first input DataSN number the initiator hasn't acknowledged yet 💖 When a brand new command goes out, this number gets set to 0 🌸
If the function is TASK REASSIGN, which sets up a new connection allegiance for a read or bidirectional command that was already issued, then ExpDataSN either carries an updated data acknowledgment reference number or the value 0. A 0 just means the reference number didn't change 🫶 The initiator MUST discard any data PDUs from the previous execution that it did not acknowledge 😭, and the target MUST transmit all Data-In PDUs (if any) starting with the data acknowledgment reference number. The number of retransmitted PDUs might or might not match the original transmission, depending on whether MaxRecvDataSegmentLength changed during the reassignment 🦋 Also, the target MAY send no more Data-In PDUs if all the data has already been acknowledged 💅
Here's the validity check. The value of ExpDataSN MUST be 0 or higher than the DataSN of the last acknowledged Data-In PDU, but not larger than DataSN + 1 of the last Data-IN PDU sent by the target. Anything else MUST be ignored by the target 🙈
For other functions, this field is reserved 🎀
11.6. Task Management Function Response 🧚
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0|.|.| 0x22 |1| Reserved | Response | Reserved |
+---------------+---------------+---------------+---------------+
4|TotalAHSLength | DataSegmentLength |
+---------------------------------------------------------------+
8/ Reserved /
/ /
+---------------+---------------+---------------+---------------+
16| Initiator Task Tag |
+---------------+---------------+---------------+---------------+
20| Reserved |
+---------------+---------------+---------------+---------------+
24| StatSN |
+---------------+---------------+---------------+---------------+
28| ExpCmdSN |
+---------------+---------------+---------------+---------------+
32| MaxCmdSN |
+---------------+---------------+---------------+---------------+
36/ Reserved /
+/ /
+---------------+---------------+---------------+---------------+
48| Header-Digest (optional) |
+---------------+---------------+---------------+---------------+Okay, this is the response PDU layout, and it's giving very structured 🍓 For the functions ABORT TASK, ABORT TASK SET, CLEAR ACA, CLEAR TASK SET, LOGICAL UNIT RESET, TARGET COLD RESET, TARGET WARM RESET, and TASK REASSIGN, the target performs the requested task management function and then sends a task management response back to the initiator ✨ For TASK REASSIGN, the new connection allegiance MUST ONLY become effective at the target after the target issues the task management response 👑
11.6.1. Response 💜
The target gives back a response, and it can be any of these values:
0 - Function complete
1 - Task does not exist
2 - LUN does not exist
3 - Task still allegiant
4 - Task allegiance reassignment not supported
5 - Task management function not supported
6 - Function authorization failed
255 - Function rejectedOn top of those, the value 7 is defined by [RFC7144] 🌈
For a discussion on how response codes 3 and 4 get used, check out Section 7.2.2 🦋
For the TARGET COLD RESET and TARGET WARM RESET functions, the target cancels all pending operations across all LUs known to the issuing initiator 🔥 For the TARGET COLD RESET function, the target MUST then close all of its TCP connections to all initiators, which terminates all sessions 💀
Mapping the response code into a SCSI service response code value is outside the scope of this document, if it's needed at all 🙈 Symbolically though, Response values 0 and 1 map to the SCSI service response of FUNCTION COMPLETE. Response value 2 maps to INCORRECT LOGICAL UNIT NUMBER. Every other Response value maps to FUNCTION REJECTED. And if a Task Management Function Response PDU doesn't arrive before the session gets terminated, the SCSI service response is SERVICE DELIVERY OR TARGET FAILURE 😭
The response to ABORT TASK SET and CLEAR TASK SET MUST only be issued by the target after all of the affected commands have been received by the target, the matching task management functions have been executed by the SCSI target, and the delivery of all responses up to the task management function completion has been confirmed (acknowledged through the ExpStatSN) by the initiator on all connections of this session 🫶 For the exact timeline, go look at Sections 4.2.3.3 and 4.2.3.4 📖
For the ABORT TASK function, here's how it goes:
- a) if the Referenced Task Tag identifies a valid task leading to a successful termination, then targets must return the "Function complete" response ✅
- b) if the Referenced Task Tag doesn't identify an existing task, but the CmdSN indicated by the RefCmdSN field in the Task Management Function Request is within the valid CmdSN window and less than the CmdSN of the Task Management Function Request itself, then targets must consider the CmdSN as received and return the "Function complete" response 🌸
- c) if the Referenced Task Tag doesn't identify an existing task and the CmdSN indicated by the RefCmdSN field in the Task Management Function Request is outside the valid CmdSN window, then targets must return the "Task does not exist" response 🙈
For response semantics on function types that can potentially impact multiple active tasks on the target, see Section 4.2.3 🧚
11.6.2. TotalAHSLength and DataSegmentLength 🎀
For this PDU, TotalAHSLength and DataSegmentLength MUST be 0 💖
11.7. SCSI Data-Out and SCSI Data-In 💖
okay so this is where the actual data moves 🚚✨ first up is the SCSI Data-Out PDU, which carries write data from the initiator to the target. here's its layout:
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0|.|.| 0x05 |F| Reserved |
+---------------+---------------+---------------+---------------+
4|TotalAHSLength | DataSegmentLength |
+---------------+---------------+---------------+---------------+
8| LUN or Reserved |
+ +
12| |
+---------------+---------------+---------------+---------------+
16| Initiator Task Tag |
+---------------+---------------+---------------+---------------+
20| Target Transfer Tag or 0xffffffff |
+---------------+---------------+---------------+---------------+
24| Reserved |
+---------------+---------------+---------------+---------------+
28| ExpStatSN |
+---------------+---------------+---------------+---------------+
32| Reserved |
+---------------+---------------+---------------+---------------+
36| DataSN |
+---------------+---------------+---------------+---------------+
40| Buffer Offset |
+---------------+---------------+---------------+---------------+
44| Reserved |
+---------------+---------------+---------------+---------------+
48| Header-Digest (optional) |
+---------------+---------------+---------------+---------------+
/ DataSegment /
+/ /
+---------------+---------------+---------------+---------------+
| Data-Digest (optional) |
+---------------+---------------+---------------+---------------+now the SCSI Data-In PDU, which is the read side 📖💅 here it is:
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0|.|.| 0x25 |F|A|0 0 0|O|U|S| Reserved |Status or Rsvd |
+---------------+---------------+---------------+---------------+
4|TotalAHSLength | DataSegmentLength |
+---------------+---------------+---------------+---------------+
8| LUN or Reserved |
+ +
12| |
+---------------+---------------+---------------+---------------+
16| Initiator Task Tag |
+---------------+---------------+---------------+---------------+
20| Target Transfer Tag or 0xffffffff |
+---------------+---------------+---------------+---------------+
24| StatSN or Reserved |
+---------------+---------------+---------------+---------------+
28| ExpCmdSN |
+---------------+---------------+---------------+---------------+
32| MaxCmdSN |
+---------------+---------------+---------------+---------------+
36| DataSN |
+---------------+---------------+---------------+---------------+
40| Buffer Offset |
+---------------+---------------+---------------+---------------+
44| Residual Count |
+---------------+---------------+---------------+---------------+
48| Header-Digest (optional) |
+---------------+---------------+---------------+---------------+
/ DataSegment /
+/ /
+---------------+---------------+---------------+---------------+
| Data-Digest (optional) |
+---------------+---------------+---------------+---------------+the status can ride along with the very last Data-In PDU 🎀 but only if the command didn't end in an exception. so we're talking "good status" here: GOOD, CONDITION MET, or INTERMEDIATE-CONDITION MET. whether status (and a residual count) is in there gets flagged by the S bit ngl that's the main signal 🚩 targets MAY send even non-exception status in separate responses if they want, BUT initiators MUST support non-exception status in Data-In PDUs. no excuses, bestie 💅
11.7.1. F (Final) Bit 🦋
the F bit is giving "I'm the last one" energy 💜 for outgoing data, it's 1 on the last PDU of unsolicited data, or the last PDU of a sequence that answers an R2T.
for incoming data, F is 1 on the last input (read) data PDU of a sequence. input can be chopped into several sequences, and each one gets its own F bit ✨ splitting the stream into sequences doesn't change how DataSN gets counted on Data-In PDUs, which is honestly so iconic. F can also work as a "change direction" indication for bidirectional operations that need that switch 🔄
now the size rules, they're kinda important 🙈 DataSegmentLength MUST NOT exceed MaxRecvDataSegmentLength for the direction it's sent in, and the total DataSegmentLength across all PDUs in one sequence MUST NOT exceed MaxBurstLength (or FirstBurstLength for unsolicited data). the number of PDUs in a sequence (or overall) can be higher than the MaxBurstLength-to-MaxRecvDataSegmentLength ratio would suggest, since PDUs might be capped in length by the sender's capabilities 🧚 but using a DataSegmentLength of 0 can blow up the PDU count past what's reasonable, so it should therefore be avoided 🫶
for bidirectional operations, F is 1 for both the end of the input sequences AND the end of the output sequences. double vibes 👑
11.7.2. A (Acknowledge) Bit 🌸
for sessions with ErrorRecoveryLevel=1 or higher, the target sets A to 1 to ask the initiator for a positive acknowledgment of the data it received 🙌 the target should use the A bit moderately, not spam it 💅 so it MAY only set A to 1 once every MaxBurstLength bytes, or on the last Data-In PDU that wraps up the entire requested read data transfer for the task (from the target's point of view), and it MUST NOT do it more often than that 😭 the target MUST NOT set A to 1 for sessions with ErrorRecoveryLevel=0, and the initiator MUST ignore an A bit of 1 in those sessions. the rules are strict bc they're strict 🙈
when the initiator gets a Data-In PDU with A set to 1 on a session where ErrorRecoveryLevel is greater than 0, and there are no holes in the read data up to that PDU, the initiator MUST issue a SNACK of type DataACK 🎯 the exception is when it can acknowledge the task's status right away through ExpStatSN on other outbound PDUs, as long as the status for the task has also arrived. in that case, sending a SNACK of type DataACK in response to the A bit is OPTIONAL, but if you do send it, it must not go out after the status acknowledgment through ExpStatSN. if the initiator has spotted holes in the read data before that Data-In PDU, it MUST postpone the DataACK SNACK until those holes are filled 🕳️ and it also MUST NOT acknowledge the task's status before those holes are filled. 🚫 finally, a status acknowledgment for a task that generated the Data-In PDUs counts as an implicit acknowledgment of those Data-In PDUs, but only if the target asked for that kind of acknowledgment in the first place 💜
11.7.3. Flags (Byte 1) 🍓
this one's about the flags byte. the last SCSI data packet a target sends an initiator for a SCSI command that completed successfully (with a status of GOOD, CONDITION MET, INTERMEDIATE, or INTERMEDIATE-CONDITION MET) MAY optionally also carry the Status for that data transfer 🎁 in that case, Sense Data can't be sent together with the Command Status. if the command errors out, then the response and sense data MUST be sent in a SCSI Response PDU (so they MUST NOT be sent in a SCSI data packet) 🚨 for bidirectional commands, the status MUST be sent in a SCSI Response PDU too.
here's how the bits in byte 1 break down:
bit 2-4 - Reserved.
bit 5-6 - used the same as in a SCSI Response. These
bits are only valid when S is set to 1. For
details, see Section 11.4.1.
bit 7 S (status) - set to indicate that the Command Status field
contains status. If this bit is set to 1, the
F bit MUST also be set to 1.so bits 2 to 4 are reserved 🙈 bits 5 and 6 work the same way they do in a SCSI Response, but they only mean anything when S is 1 (go peek at Section 11.4.1 for the full details 👀). and S is the big one: it says the Command Status field has status in it. if S is 1, then F MUST also be 1, no skipping 💅
the StatSN, Status, and Residual Count fields only have real content when S is set to 1 ✨ and the values for those fields are defined in Section 11.4, so go check there bestie 🧚
11.7.4. Target Transfer Tag and LUN 💎
on outgoing data, the Target Transfer Tag gets handed to the target if the transfer is honoring an R2T 🫶 in that case, the Target Transfer Tag field is a replica (a copy!) of the Target Transfer Tag that came with the R2T.
on incoming data, the Target Transfer Tag and LUN MUST be provided by the target if A is set to 1 🎯 otherwise, they're reserved. the initiator copies the Target Transfer Tag and LUN into the SNACK of type DataACK it sends back after getting a SCSI Data-In PDU with A set to 1, so they travel together 🚀
the Target Transfer Tag values aren't specified by this protocol, EXCEPT that 0xffffffff is reserved and means "no Target Transfer Tag was supplied" 🙅♀️ if a Target Transfer Tag is provided, then the LUN field MUST hold a valid value and be consistent with whatever was specified with the command. if not, the LUN field is reserved. bestie please don't mix those up 😭
11.7.5. DataSN 🔢
for input (read) or bidirectional Data-In PDUs, DataSN is the input PDU number within the data transfer for the command identified by the Initiator Task Tag 📖 so it's basically a counter for the reads.
R2T and Data-In PDUs, in the context of bidirectional commands, share the same numbering sequence (see Section 4.2.2.4) 🧩 they're on the same team numbering-wise.
for output (write) data PDUs, DataSN is the Data-Out PDU number within the current output sequence ✍️ and that current output sequence is identified one of two ways: by the Initiator Task Tag (for unsolicited data), or as a data sequence generated for one R2T (for data solicited through R2T). either way you can track it ✨
11.7.6. Buffer Offset 🧚
okay so the Buffer Offset field tells you where this PDU's payload data sits inside the whole data transfer 💅 it's giving "here's my spot in the big picture." the buffer offset plus the length should not exceed the expected transfer length for the command 🎀
the order of data PDUs inside a sequence is decided by DataPDUInOrder 📦 when it's set to Yes, the PDUs have to show up in increasing buffer offset order, and overlaps are totally forbidden 🙅♀️
the ordering between sequences is decided by DataSequenceInOrder 🌸 when that's Yes, the sequences have to go in increasing buffer offset order, and again, no overlays allowed. main character energy for orderly data 👑
11.7.7. DataSegmentLength 🦋
this is the data payload length of a SCSI Data-In or SCSI Data-Out PDU 🍓 sending 0-length data segments should be avoided, but initiators and targets MUST be able to properly receive 0-length data segments 🫶 so you have to be ready for them even if you'd rather not send them 😭
the data segments of Data-In and Data-Out PDUs SHOULD be filled out to the integer number of 4-byte words (real payload), unless the F bit is set to 1 ✨
11.8. Ready To Transfer (R2T) 💜
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0|.|.| 0x31 |1| Reserved |
+---------------+---------------+---------------+---------------+
4|TotalAHSLength | DataSegmentLength |
+---------------+---------------+---------------+---------------+
8| LUN |
+ +
12| |
+---------------+---------------+---------------+---------------+
16| Initiator Task Tag |
+---------------+---------------+---------------+---------------+
20| Target Transfer Tag |
+---------------+---------------+---------------+---------------+
24| StatSN |
+---------------+---------------+---------------+---------------+
28| ExpCmdSN |
+---------------+---------------+---------------+---------------+
32| MaxCmdSN |
+---------------+---------------+---------------+---------------+
36| R2TSN |
+---------------+---------------+---------------+---------------+
40| Buffer Offset |
+---------------+---------------+---------------+---------------+
44| Desired Data Transfer Length |
+---------------------------------------------------------------+
48| Header-Digest (optional) |
+---------------+---------------+---------------+---------------+okay this is the R2T era 🎀 when an initiator has submitted a SCSI command with data that goes from the initiator to the target (write), the target gets to say which blocks it's ready to receive 🙌 it can even ask for the data in whatever order is convenient for it at that exact moment. that info gets passed from target to initiator in the Ready To Transfer (R2T) PDU 💅
so for write operations to happen without an explicit initial R2T, the initiator and target MUST have negotiated the key InitialR2T to No during login 🔑
an R2T MAY be answered with one or more SCSI Data-Out PDUs that have a matching Target Transfer Tag 🫧 if an R2T gets answered with a single Data-Out PDU, the buffer offset in that data PDU MUST be the same as the one the R2T specified, and the data length of the data PDU MUST be the same as the Desired Data Transfer Length from the R2T 🎯 if the R2T is answered with a sequence of data PDUs instead, the buffer offset and length MUST be within the range the R2T specified, and the last PDU MUST have the F bit set to 1 🏁
bestie alert: if the last PDU (the one with the F bit) shows up before the Desired Data Transfer Length has been transferred, a target MAY choose to reject that PDU with the "Protocol Error" reason code 🚨
DataPDUInOrder runs the show for Data-Out PDU ordering 🌈 if it's set to Yes, the buffer offsets and lengths for consecutive PDUs MUST form a continuous non-overlapping range, and the PDUs MUST be sent in increasing offset order ✨
the target can send several R2T PDUs, so it can have a bunch of pending data transfers going at once 🧚 the number of outstanding R2T PDUs is capped by the negotiated key MaxOutstandingR2T 🍓 and within a task, outstanding R2Ts MUST be fulfilled by the initiator in the order they were received. first in, first out, no drama 💜
R2T PDUs MAY also be used to recover Data-Out PDUs 🛟 this kind of R2T (the Recovery-R2T) gets generated by a target when it notices it lost one or more Data-Out PDUs because of:
- Digest error
- Sequence error
- Sequence reception timeout
a Recovery-R2T carries the next unused R2TSN, but it asks for part of or the entire data burst that an earlier R2T (one with a lower R2TSN) had already asked for 🔁
DataSequenceInOrder handles the buffer offset ordering across consecutive R2Ts 🦋 if it's Yes, then consecutive R2Ts MUST refer to continuous non-overlapping ranges, except for Recovery-R2Ts 🫶
11.8.1. TotalAHSLength and DataSegmentLength 🌸
for this PDU, TotalAHSLength and DataSegmentLength MUST be 0 🙈
11.8.2. R2TSN 🍓
R2TSN is the R2T PDU input PDU number within the command identified by the Initiator Task Tag 🔢
for bidirectional commands, R2T and Data-In PDUs share the input PDU numbering sequence (see Section 4.2.2.4) 🤝
11.8.3. StatSN ⭐
the StatSN field will contain the next StatSN 💅 and the StatSN for this connection is not advanced after this PDU is sent 🛑
11.8.4. Desired Data Transfer Length and Buffer Offset 🎀
the target specifies how many bytes it wants the initiator to send because of this R2T PDU 📦 the target may request the data in several chunks, not necessarily in the original order of the data 🧩 so it also specifies a buffer offset, which is the point where the data transfer should begin, measured relative to the beginning of the total data transfer 📍
the Desired Data Transfer Length MUST NOT be 0 and MUST NOT exceed MaxBurstLength 🚫
11.8.5. Target Transfer Tag 🏷️
the target gives its own tag to each R2T request it sends to the initiator 🏷️ the target can use this tag to easily identify the data it receives 🔍 the Target Transfer Tag and LUN get copied into the outgoing data PDUs and are only used by the target 💜 there's no protocol rule about the Target Transfer Tag, except that the value 0xffffffff is reserved and MUST NOT be sent by a target in an R2T 🙅♀️
11.9. Asynchronous Message 📣
an Asynchronous Message may be sent from the target to the initiator without corresponding to a particular command 📨 the target specifies the reason for the event and the sense data 🧠
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0|.|.| 0x32 |1| Reserved |
+---------------+---------------+---------------+---------------+
4|TotalAHSLength | DataSegmentLength |
+---------------+---------------+---------------+---------------+
8| LUN or Reserved |
+ +
12| |
+---------------+---------------+---------------+---------------+
16| 0xffffffff |
+---------------+---------------+---------------+---------------+
20| Reserved |
+---------------+---------------+---------------+---------------+
24| StatSN |
+---------------+---------------+---------------+---------------+
28| ExpCmdSN |
+---------------+---------------+---------------+---------------+
32| MaxCmdSN |
+---------------+---------------+---------------+---------------+
36| AsyncEvent | AsyncVCode | Parameter1 or Reserved |
+---------------+---------------+---------------+---------------+
40| Parameter2 or Reserved | Parameter3 or Reserved |
+---------------+---------------+---------------+---------------+
44| Reserved |
+---------------+---------------+---------------+---------------+
48| Header-Digest (optional) |
+---------------+---------------+---------------+---------------+
/ DataSegment - Sense Data and iSCSI Event Data /
+/ /
+---------------+---------------+---------------+---------------+
| Data-Digest (optional) |
+---------------+---------------+---------------+---------------+some Asynchronous Messages are strictly related to iSCSI, while others are related to SCSI [SAM2] 🧃
the StatSN counts this PDU as an acknowledgeable event (the StatSN is advanced), which allows for initiator and target state synchronization 🫶✨
11.9.1. AsyncEvent 💌
okay so this is the menu of codes for iSCSI Asynchronous Messages (aka events) 💅 the AsyncEvent field tells you what kind of news the target is dropping ✨
0(SCSI Async Event) 🔔- a SCSI asynchronous event gets reported in the sense data, and the Sense Data that comes with the report (in the data segment) is what identifies the condition
- sending a SCSI event ("asynchronous event reporting" in SCSI terminology) depends on the target supporting SCSI asynchronous event reporting (see [SAM2]), which shows up in the standard INQUIRY data (see [SPC3])
- its use may be enabled by parameters in the SCSI Control mode page (see [SPC3])
1(Logout Request) 🚪- the target requests Logout
- this Async Message MUST be sent on the same connection as the one requesting to be logged out
- the initiator MUST honor this request by issuing a Logout as early as possible, but no later than
Parameter3seconds - the initiator MUST send a Logout with a reason code of "close the connection" OR "close the session" to close all the connections
- once this message is received, the initiator SHOULD NOT issue new iSCSI commands on the connection to be logged out
- the target MAY reject any new I/O requests that it receives after this message, with the reason code "Waiting for Logout"
- if the initiator does not log out in
Parameter3seconds, the target should send an Async PDU with iSCSI event code "Dropped the connection" if possible, or simply terminate the transport connection Parameter1andParameter2are reserved
2(Connection Drop Notification) 📉- the target indicates that it will drop the connection
- the
Parameter1field indicates the CID of the connection that is going to be dropped - the
Parameter2field (Time2Wait) indicates, in seconds, the minimum time to wait before attempting to reconnect or reassign - the
Parameter3field (Time2Retain) indicates the maximum time allowed to reassign commands after the initial wait (inParameter2) - if the initiator does not attempt to reconnect and/or reassign the outstanding commands within the time specified by
Parameter3, or ifParameter3is 0, the target will terminate all outstanding commands on this connection - in this case, no other responses should be expected from the target for the outstanding commands on this connection
- a value of 0 for
Parameter2indicates that reconnect can be attempted immediately
3(Session Drop Notification) 🌧️- the target indicates that it will drop all the connections of this session
- the
Parameter1field is reserved - the
Parameter2field (Time2Wait) indicates, in seconds, the minimum time to wait before attempting to reconnect - the
Parameter3field (Time2Retain) indicates the maximum time allowed to reassign commands after the initial wait (inParameter2) - if the initiator does not attempt to reconnect and/or reassign the outstanding commands within the time specified by
Parameter3, or ifParameter3is 0, the session is terminated - in this case, the target will terminate all outstanding commands in this session; no other responses should be expected from the target for the outstanding commands in this session
- a value of 0 for
Parameter2indicates that reconnect can be attempted immediately
4(Negotiation Request) 🗣️- the target requests parameter negotiation on this connection
- the initiator MUST honor this request by issuing a Text Request (that can be empty) on the same connection as early as possible, but no later than
Parameter3seconds, unless a Text Request is already pending on the connection, or by issuing a Logout Request - if the initiator does not issue a Text Request, the target may reissue the Asynchronous Message requesting parameter negotiation
5(Task Termination) 🧹- all active tasks for a LU with a matching LUN field in the Async Message PDU are being terminated
- the receiving initiator iSCSI layer MUST respond to this message by taking the following steps, in order:
- Stop Data-Out transfers on that connection for all active TTTs for the affected LUN quoted in the Async Message PDU.
- Acknowledge the StatSN of the Async Message PDU via a NOP-Out PDU with
ITT=0xffffffff(i.e., non-ping flavor), while copying the LUN field from the Async Message to NOP-Out.
- this value of
AsyncEvent, however, MUST NOT be used on an iSCSI session unless the newTaskReportingtext key defined in Section 13.23 was negotiated toFastAborton the session
248-255(Vendor-unique) 🎨- vendor-specific iSCSI event
- the
AsyncVCodedetails the vendor code, and data MAY accompany the report
All other event codes are unassigned. 🙅♀️
11.9.2. AsyncVCode 🏷️
AsyncVCode is a vendor-specific detail code that is only valid if the AsyncEvent field indicates a vendor-specific event. Otherwise, it is reserved. 💖
11.9.3. LUN 🎯
the LUN field MUST be valid if AsyncEvent is 0. Otherwise, this field is reserved. 🙌
11.9.4. Sense Data and iSCSI Event Data 🫧
for a SCSI event, this data accompanies the report in the data segment and identifies the condition ✨
for an iSCSI event, additional vendor-unique data MAY accompany the Async event. Initiators MAY ignore the data when not understood, while processing the rest of the PDU 🌸
if the DataSegmentLength is not 0, the format of the DataSegment is as follows:
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0|SenseLength | Sense Data |
+---------------+---------------+---------------+---------------+
x/ Sense Data /
+---------------+---------------+---------------+---------------+
y/ iSCSI Event Data /
/ /
+---------------+---------------+---------------+---------------+
z|11.9.4.1. SenseLength 📏
this is the length of Sense Data. When the Sense Data field is empty (e.g., the event is not a SCSI event), SenseLength is 0. 🫶
11.10. Text Request 💬
the Text Request is provided to allow for the exchange of information and for future extensions. It lets the initiator tell a target about its capabilities or request some special operations. 🦋
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0|.|I| 0x04 |F|C| Reserved |
+---------------+---------------+---------------+---------------+
4|TotalAHSLength | DataSegmentLength |
+---------------+---------------+---------------+---------------+
8| LUN or Reserved |
+ +
12| |
+---------------+---------------+---------------+---------------+
16| Initiator Task Tag |
+---------------+---------------+---------------+---------------+
20| Target Transfer Tag or 0xffffffff |
+---------------+---------------+---------------+---------------+
24| CmdSN |
+---------------+---------------+---------------+---------------+
28| ExpStatSN |
+---------------+---------------+---------------+---------------+
32/ Reserved /
+/ /
+---------------+---------------+---------------+---------------+
48| Header-Digest (optional) |
+---------------+---------------+---------------+---------------+
/ DataSegment (Text) /
+/ /
+---------------+---------------+---------------+---------------+
| Data-Digest (optional) |
+---------------+---------------+---------------+---------------+an initiator MUST NOT have more than one outstanding Text Request on a connection at any given time 🚫
on a connection failure, an initiator must either explicitly abort any active allegiant text negotiation task or cause such a task to be implicitly terminated by the target 🛑
11.10.1. F (Final) Bit 🏁
when set to 1, this bit indicates that this is the last or only Text Request in a sequence of Text Requests. Otherwise, it indicates that more Text Requests will follow ✨
11.10.2. C (Continue) Bit ➡️
when set to 1, this bit indicates that the text (set of key=value pairs) in this Text Request is not complete (it will be continued on subsequent Text Requests). Otherwise, it indicates that this Text Request ends a set of key=value pairs. A Text Request with the C bit set to 1 MUST have the F bit set to 0 🎀
11.10.3. Initiator Task Tag 🏷️
this is the initiator-assigned identifier for this Text Request. If the command is sent as part of a sequence of Text Requests and responses, the Initiator Task Tag MUST be the same for all the requests within the sequence (similar to linked SCSI commands). The I bit for all requests in a sequence also MUST be the same 🫶🌈
11.10.4. Target Transfer Tag ✨
Okay bestie, when the Target Transfer Tag is the reserved value 0xffffffff, it's telling the target "this is a brand new request" 🎀. The target then resets any internal state tied to that Initiator Task Tag, so the current negotiation state gets wiped and it's a fresh start 💅.
The target puts a Target Transfer Tag in a Text Response (anything except 0xffffffff) whenever it has more data to send or more operations to perform for that Initiator Task Tag 🦋. It MUST do this whenever it sets the F bit to 0 in the response, no exceptions 😭. Then the initiator copies that tag into its next Text Request, which basically means "keep going on this one!" 🫶 The initiator MUST ignore the Target Transfer Tag in the Text Response when the F bit is set to 1, because that's the end of the line 🙈.
This is how the two sides pass a huge amount of text back and forth over a sequence of text-command/text-response exchanges, or work through long extended negotiation sequences 🧚.
If the Target Transfer Tag is not 0xffffffff, the LUN field MUST be sent by the target in the Text Response 🍓.
A target MAY reset its internal negotiation state if an exchange gets stalled by the initiator for a long time or if it's running out of resources 💀.
Here's how a long Text Response gets handled 👑:
I->T Text SendTargets=All (F = 1, TTT = 0xffffffff)
T->I Text <part 1> (F = 0, TTT = 0x12345678)
I->T Text <empty> (F = 1, TTT = 0x12345678)
T->I Text <part 2> (F = 0, TTT = 0x12345678)
I->T Text <empty> (F = 1, TTT = 0x12345678)
...
T->I Text <part n> (F = 1, TTT = 0xffffffff)11.10.5. Text 🌈
The data lengths of a Text Request MUST NOT exceed the iSCSI target MaxRecvDataSegmentLength. That's a value negotiated per connection and per direction, so it's not one-size-fits-all 🌸. The text format is specified in Section 6.2.
Sections 12 and 13 list some basic Text key=value pairs. Some of them are for Login Requests and Responses, and some are for Text Requests and Responses ✨.
A key=value pair can span Text Request or Text Response boundaries. It can start in one PDU and keep going in the next one. So the end of a PDU doesn't automatically mean the end of a key=value pair, which is lowkey a plot twist 😭.
The target responds by sending its response back to the initiator. The response text format is pretty similar to the request text format. The Text Response MAY refer to key=value pairs from an earlier Text Request, and the text in the request may refer to earlier responses 🦋.
Section 6.2 has all the rules for Text Requests and Responses, so go check it out 💅.
Text operations are usually for parameter setting and negotiations, but they can also be used to run some long-lasting operations 🧚. Text operations that take a long time should be placed in their own Text Request 🎀.
11.11. Text Response 💖
The Text Response PDU carries the target's responses to the initiator's Text Request. The format of the Text field matches the Text Request, so it's giving consistency 🫶.
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0|.|.| 0x24 |F|C| Reserved |
+---------------+---------------+---------------+---------------+
4|TotalAHSLength | DataSegmentLength |
+---------------+---------------+---------------+---------------+
8| LUN or Reserved |
+ +
12| |
+---------------+---------------+---------------+---------------+
16| Initiator Task Tag |
+---------------+---------------+---------------+---------------+
20| Target Transfer Tag or 0xffffffff |
+---------------+---------------+---------------+---------------+
24| StatSN |
+---------------+---------------+---------------+---------------+
28| ExpCmdSN |
+---------------+---------------+---------------+---------------+
32| MaxCmdSN |
+---------------+---------------+---------------+---------------+
36/ Reserved /
+/ /
+---------------+---------------+---------------+---------------+
48| Header-Digest (optional) |
+---------------+---------------+---------------+---------------+
/ DataSegment (Text) /
+/ /
+---------------+---------------+---------------+---------------+
| Data-Digest (optional) |
+---------------+---------------+---------------+---------------+11.11.1. F (Final) Bit 🔥
When it's set to 1 in response to a Text Request that also has the Final bit set to 1, the F bit tells you the target has finished the whole operation 👑. If it's set to 0 in response to a Text Request with the Final Bit set to 1, that means the target still has more work to do and is inviting a follow-on Text Request 🌸. A Text Response with the F bit set to 1 in response to a Text Request with the F bit set to 0 is a protocol error, and that's a whole no 💀.
A Text Response with the F bit set to 1 MUST NOT contain key=value pairs that may require additional answers from the initiator 🙈.
A Text Response with the F bit set to 1 MUST have a Target Transfer Tag field set to the reserved value 0xffffffff 💅.
A Text Response with the F bit set to 0 MUST have a Target Transfer Tag field set to a value other than the reserved value 0xffffffff 🦋.
11.11.2. C (Continue) Bit 🧚
When it's set to 1, the C bit says the text (the set of key=value pairs) in this Text Response isn't complete yet, and it'll be continued in later Text Responses 🎀. Otherwise, it means this Text Response ends a set of key=value pairs ✨. A Text Response with the C bit set to 1 MUST have the F bit set to 0 💖.
11.11.3. Initiator Task Tag 🫶
The Initiator Task Tag matches the tag used in the initial Text Request. Simple, but it's the glue that keeps everything together 💜.
11.11.4. Target Transfer Tag 🌈
When a target has more work to do (for example, it can't send all the remaining text data in one Text Response, or it has to keep the negotiation going) and it has enough resources to proceed, it MUST set the Target Transfer Tag to a value other than the reserved value 0xffffffff. Otherwise, the Target Transfer Tag MUST be set to 0xffffffff 🦋.
When the Target Transfer Tag is not 0xffffffff, the LUN field may be significant 🍓.
The initiator MUST copy the Target Transfer Tag and LUN in its next request to say it wants the rest of the data 🫶.
When the target gets a Text Request with the Target Transfer Tag set to the reserved value 0xffffffff, it resets its internal information (its state) tied to the given Initiator Task Tag, which restarts the negotiation 🔥.
When a target can't finish the operation in a single Text Response and also doesn't have enough resources to keep going, it rejects the Text Request with the appropriate Reject code 💀.
A target may reset its internal state tied to an Initiator Task Tag (the current negotiation state, as expressed through the Target Transfer Tag) if the initiator fails to continue the exchange for some time. The target may reject later Text Requests that have the Target Transfer Tag set to the "stale" value 🙈.
11.11.5. StatSN 🌸
The target StatSN variable is advanced by each Text Response that gets sent 💅.
11.11.6. Text Response Data ✨
The data lengths of a Text Response MUST NOT exceed the iSCSI initiator MaxRecvDataSegmentLength. That's negotiated per connection and per direction, same as before 🎀.
The text in the Text Response Data follows the same rules as the text in the Text Request Data (see Section 11.11.2) 🧚.
Even though the initiator is the one asking and controls how the request-response starts and stops, the target can offer its own key=value pairs as part of a sequence, not just in response to the initiator 👑.
11.12. Login Request 💜
After a TCP connection gets set up between an initiator and a target, the initiator MUST start a Login Phase to get further access to the target's resources 🔥.
The Login Phase (see Section 6.3) is a sequence of Login Requests and Login Responses that carry the same Initiator Task Tag 🫶.
Login Requests are always considered immediate 🦋.
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0|.|1| 0x03 |T|C|.|.|CSG|NSG| Version-max | Version-min |
+---------------+---------------+---------------+---------------+
4|TotalAHSLength | DataSegmentLength |
+---------------+---------------+---------------+---------------+
8| ISID |
+ +---------------+---------------+
12| | TSIH |
+---------------+---------------+---------------+---------------+
16| Initiator Task Tag |
+---------------+---------------+---------------+---------------+
20| CID | Reserved |
+---------------+---------------+---------------+---------------+
24| CmdSN |
+---------------+---------------+---------------+---------------+
28| ExpStatSN or Reserved |
+---------------+---------------+---------------+---------------+
32| Reserved |
+---------------+---------------+---------------+---------------+
36| Reserved |
+---------------+---------------+---------------+---------------+
40/ Reserved /
+/ /
+---------------+---------------+---------------+---------------+
48/ DataSegment - Login Parameters in Text Request Format /
+/ /
+---------------+---------------+---------------+---------------+11.12.1. T (Transit) Bit 🌸
When it's set to 1, the T bit says the initiator is ready to move on to the next stage 🧚.
If the T bit is set to 1 and the NSG is set to FullFeaturePhase, then that also means the initiator is ready for the Login Final-Response (see Section 6.3) ✨.
11.12.2. C (Continue) Bit 💖
Okay so when this bit is set to 1, it's basically saying "not done yet, bestie" 🥹 The text (that set of key=value pairs) in this Login Request isn't complete, and the rest will show up in later Login Requests. If it's 0, then this Login Request wraps up the set of key=value pairs ✨ Lowkey the important part: a Login Request with the C bit set to 1 MUST have the T bit set to 0 🙅♀️
11.12.3. CSG and NSG 🧚
CSG (Current Stage) and NSG (Next Stage) are how Login requests and responses say which part of the session they're in (SecurityNegotiation, LoginOperationalNegotiation, or FullFeaturePhase), plus which stage they want to move to next (see Section 6.3). The Next Stage value only counts when the T bit is 1. Otherwise it's reserved 💅
The stage codes are:
0 - SecurityNegotiation
1 - LoginOperationalNegotiation
3 - FullFeaturePhaseAll other codes are reserved 🌸
11.12.4. Version 🎀
The version number for this document is 0x00, so both Version-min and Version-max MUST be set to 0x00 💜
11.12.4.1. Version-max 🦋
Version-max is the maximum version number supported 🌈
All Login Requests within the Login Phase MUST carry the same Version-max ✨
The target MUST use the value presented with the first Login Request 👑
11.12.4.2. Version-min 🌷
All Login Requests within the Login Phase MUST carry the same Version-min. The target MUST use the value presented with the first Login Request 🫶
11.12.5. ISID 🍓
This one is the initiator's contribution to the session identifier, and it's built like this (see Section 10.1.1 for details) 🧩
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
8| T | A | B | C |
+---------------+---------------+---------------+---------------+
12| D |
+---------------+---------------+The T field tells you how to read A, B, C, and D ✨
T
00b OUI-Format
A and B: 22-bit OUI
(the I/G and U/L bits are omitted)
C and D: 24-bit Qualifier
01b EN: Format (IANA Enterprise Number)
A: Reserved
B and C: EN (IANA Enterprise Number)
D: Qualifier
10b "Random"
A: Reserved
B and C: Random
D: Qualifier
11b A, B, C, and D: ReservedWhen T is 00b or 01b, A and B (for 00b) or B and C (for 01b) identify the vendor or organization whose hardware or software made this ISID 🏷️ A vendor or organization with one or more OUIs, or one or more Enterprise Numbers, MUST use at least one of these numbers and pick the right T value when its components generate ISIDs 💖 An OUI or EN MUST be set in the matching fields in network byte order (byte big-endian) 🔥
If T is 10b, then B and C are a random 24-bit unsigned integer in network byte order (byte big-endian). Check [RFC3721] to see how this affects the "conservative reuse" principle 🎲
The Qualifier field is a 16-bit or 24-bit unsigned integer that gives you a range of possible ISID values inside the chosen namespace. It can be any value that fits the iSCSI constraints (see Sections 4.4.3 and 10.1.1) 🌟
The T field value of 11b is reserved 🙈
If the ISID comes from something a vendor assigned to a hardware adapter or interface as a preset default, it MUST be configurable to a value that matches the SCSI port behavior the system wants. (See Sections 10.1.1 and 10.1.2.) The resulting ISID MUST also stay persistent across power cycles, reboots, card swaps, etc. 🛠️
Bestie, this is a big one: the ISID has to survive power cycles, reboots, and card swaps. No cap, don't skip it 💀
11.12.6. TSIH 👑
The TSIH must be set in the first Login Request. The reserved value 0 MUST be used on the first connection for a new session. Otherwise, the TSIH the target sent at the end of the successful login for the session's first connection MUST be used. The TSIH tells the target which existing session this new connection belongs to 🧚
All Login Requests within a Login Phase MUST carry the same TSIH 💜
The target MUST check the value presented with the first Login Request and act as specified in Section 6.3.1 🔍
11.12.7. Connection ID (CID) 🦋
The CID gives this connection its own unique ID inside the session 🪪
All Login Requests within the Login Phase MUST carry the same CID ✨
The target MUST use the value presented with the first Login Request 💅
A Login Request with a non-zero TSIH and a CID that matches an existing connection implies a logout of that connection, followed by a login (see Section 6.3.4). For details on the implicit Logout Request, see Section 11.14 🌸
11.12.8. CmdSN 🌈
The CmdSN is either the starting command sequence number of a session (for the first Login Request of a session, the "leading" login), or the command sequence number in the command stream if the login is for a new connection in an existing session 📈
Examples, because we love a visual:
- Login on a leading connection: If the leading login carries CmdSN 123, every other Login Request in the same Login Phase also carries CmdSN 123, and the first non-immediate command in the Full Feature Phase also carries CmdSN 123 🎀
- Login on other than a leading connection: If the current CmdSN when the first login on the connection is issued is 500, then that PDU carries CmdSN=500. Later Login Requests needed to finish this Login Phase may carry a CmdSN higher than 500 if non-immediate requests issued on other connections in the same session move the CmdSN forward 🚀
If the Login Request is a leading Login Request, the target MUST use the value presented in the CmdSN as the target value for the ExpCmdSN 👑
11.12.9. ExpStatSN 🫧
For the first Login Request on a connection, this is the ExpStatSN for the old connection. It's only valid if the Login Request restarts a connection (see Section 6.3.4) 🔁
For later Login Requests, it's used to acknowledge the Login Responses with their increasing StatSN values 🫶
11.12.10. Login Parameters 🍭
The initiator MUST provide some basic parameters so the target can figure out whether the initiator is allowed to use its resources, plus the starting text parameters for the security exchange 🔐
All the rules in Section 11.10.5 for Text Requests also apply to Login Requests. Keys and their explanations are in Section 12 (security negotiation keys) and Section 13 (operational parameter negotiation keys). All keys in Section 13, except for the X extension formats, MUST be supported by iSCSI initiators and targets. Keys in Section 12 only need support when the function they refer to is mandatory to implement 🧁
11.13. Login Response 💌
The Login Response shows how far along the Login Phase is, and/or that it's ending 🏁
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0|.|.| 0x23 |T|C|.|.|CSG|NSG| Version-max |Version-active |
+---------------+---------------+---------------+---------------+
4|TotalAHSLength | DataSegmentLength |
+---------------+---------------+---------------+---------------+
8| ISID |
+ +---------------+---------------+
12| | TSIH |
+---------------+---------------+---------------+---------------+
16| Initiator Task Tag |
+---------------+---------------+---------------+---------------+
20| Reserved |
+---------------+---------------+---------------+---------------+
24| StatSN |
+---------------+---------------+---------------+---------------+
28| ExpCmdSN |
+---------------+---------------+---------------+---------------+
32| MaxCmdSN |
+---------------+---------------+---------------+---------------+
36| Status-Class | Status-Detail | Reserved |
+---------------+---------------+---------------+---------------+
40/ Reserved /
+/ /
+---------------+---------------+---------------+---------------+
48/ DataSegment - Login Parameters in Text Request Format /
+/ /
+---------------+---------------+---------------+---------------+11.13.1. Version-max 🦋
This is the highest version number the target supports 🌟
All Login Responses within the Login Phase MUST carry the same Version-max 💖
The initiator MUST use the value presented as a response to the first Login Request ✨
11.13.2. Version-active 🌷
Version-active is the highest version supported by both the target and the initiator. If the target doesn't support a version within the range the initiator asked for, the target rejects the login, and this field shows the lowest version the target supports 🙅♀️
All Login Responses within the Login Phase MUST carry the same Version-active 🫶
The initiator MUST use the value presented as a response to the first Login Request 👑
11.13.3. TSIH 🧚
The TSIH is the target-assigned session-identifying handle. Its internal format and content aren't defined by this protocol, except that the value 0 is reserved 🔒 Except for the Login Final-Response in a new session, this field should be set to the TSIH the initiator provided in the Login Request. For a new session, the target MUST generate a non-zero TSIH and ONLY return it in the Login Final-Response (see Section 6.3) 🎀
11.13.4. StatSN 🍓
For the first Login Response (the response to the first Login Request), this is the starting status sequence number for the connection. The next response of any kind, including the next Login Response in the same Login Phase if there is one, will carry this number + 1. This field is only valid if the Status-Class is 0 🌈
11.13.5. Status-Class and Status-Detail 💅✨
okay bestie, the Status in a Login Response tells you how the Login Phase went 🫶 It has two parts:
Status-ClassStatus-Detail
A Status-Class of 0 means success 🎀
Anything non-zero is an exception 🙈 When that happens, Status-Class alone is enough for a simple initiator to handle it, so it doesn't need to look at Status-Detail. Status-Detail is there for the more sophisticated initiators who want finer-grained handling, plus better info for logs 🧚
The Status-Classes are:
0Success: the iSCSI target successfully received, understood, and accepted the request. The numbering fields (StatSN,ExpCmdSN,MaxCmdSN) are only valid ifStatus-Classis0.1Redirection: the initiator has to take further action to finish the request, usually because the target moved to a different address. All of the redirection responses MUST return one or more text key parameters of the typeTargetAddress, which tells the initiator the target's new address. A redirection MAY be issued by a target before or after completing a security negotiation, if one is required. A redirection SHOULD be accepted by an initiator even without the target completing a security negotiation (if one is required), and it MUST be accepted by the initiator after the security negotiation is complete (if one is required). 🦋2Initiator Error (not a format error): the initiator most likely caused the error. This MAY be due to a request for a resource the initiator doesn't have permission for. The request should not be tried again. 🙅♀️3Target Error: the target sees no errors in the initiator's Login Request but is currently incapable of fulfilling it. The initiator may retry the same Login Request later. 🌸
The table below shows all of the currently allocated status codes. The codes are in hexadecimal. The first byte is the Status-Class, and the second byte is the status detail. 🍓
-----------------------------------------------------------------
Status | Code | Description
|(hex) |
-----------------------------------------------------------------
Success | 0000 | Login is proceeding OK (*1).
-----------------------------------------------------------------
Target moved | 0101 | The requested iSCSI Target Name (ITN)
temporarily | | has temporarily moved
| | to the address provided.
-----------------------------------------------------------------
Target moved | 0102 | The requested ITN has permanently moved
permanently | | to the address provided.
-----------------------------------------------------------------
Initiator | 0200 | Miscellaneous iSCSI initiator
error | | errors.
-----------------------------------------------------------------
Authentication| 0201 | The initiator could not be
failure | | successfully authenticated or target
| | authentication is not supported.
-----------------------------------------------------------------
Authorization | 0202 | The initiator is not allowed access
failure | | to the given target.
-----------------------------------------------------------------
Not found | 0203 | The requested ITN does not
| | exist at this address.
-----------------------------------------------------------------
Target removed| 0204 | The requested ITN has been removed, and
| | no forwarding address is provided.
-----------------------------------------------------------------
Unsupported | 0205 | The requested iSCSI version range is
version | | not supported by the target.
-----------------------------------------------------------------
Too many | 0206 | Too many connections on this SSID.
connections | |
-----------------------------------------------------------------
Missing | 0207 | Missing parameters (e.g., iSCSI
parameter | | Initiator Name and/or Target Name).
-----------------------------------------------------------------
Can't include | 0208 | Target does not support session
in session | | spanning to this connection (address).
-----------------------------------------------------------------
Session type | 0209 | Target does not support this type of
not supported | | session or not from this initiator.
-----------------------------------------------------------------
Session does | 020a | Attempt to add a connection
not exist | | to a non-existent session.
-----------------------------------------------------------------
Invalid during| 020b | Invalid request type during login.
login | |
-----------------------------------------------------------------
Target error | 0300 | Target hardware or software error.
-----------------------------------------------------------------
Service | 0301 | The iSCSI service or target is not
unavailable | | currently operational.
-----------------------------------------------------------------
Out of | 0302 | The target has insufficient session,
resources | | connection, or other resources.
-----------------------------------------------------------------(*1) If the response T bit is set to 1 in both the request and the
matching response, and the NSG is set to FullFeaturePhase in
both the request and the matching response, the Login Phase is
finished, and the initiator may proceed to issue SCSI commands.If the Status-Class is not 0, the initiator and target MUST close the TCP connection. 🔒
If the target wishes to reject the Login Request for more than one reason, it should return the primary reason for the rejection. 💭
11.13.6. T (Transit) Bit 🚦
The T bit is set to 1 as an indicator of the end of the stage. If the T bit is set to 1 and the NSG is set to FullFeaturePhase, then this is also the Login Final-Response (see Section 6.3). A T bit of 0 indicates a "partial" response, which means "more negotiation needed". 🫧
A Login Response with the T bit set to 1 MUST NOT contain key=value pairs that may require additional answers from the initiator within the same stage. 🙅♀️
If the Status-Class is 0, the T bit MUST NOT be set to 1 if the T bit in the request was set to 0. 💅
11.13.7. C (Continue) Bit 🎀
When set to 1, this bit indicates that the text (set of key=value pairs) in this Login Response is not complete. It will be continued on subsequent Login Responses. Otherwise, it indicates that this Login Response ends a set of key=value pairs. 🧩 A Login Response with the C bit set to 1 MUST have the T bit set to 0. 🌈
11.13.8. Login Parameters 🧚♀️
The target MUST provide some basic parameters so the initiator can figure out if it's connected to the correct port, plus the initial text parameters for the security exchange. 🔌
All the rules in Section 11.11.6 for Text Responses also hold for Login Responses. Keys and their explanations are listed in Section 12 (security negotiation keys) and in Section 13 (operational parameter negotiation keys). All keys listed in Section 13, except for the X extension formats, MUST be supported by iSCSI initiators and targets. Keys listed in Section 12 only need to be supported when the function they refer to is mandatory to implement. 👑✨
11.14. Logout Request ✨
okay so the Logout Request is basically how you politely close a connection without ghosting the other side 💅 It's a controlled exit, bestie 🦋
An initiator MAY use a Logout Request to remove a connection from a session or to close an entire session 🌸
After sending the Logout Request PDU, an initiator MUST NOT send any new iSCSI requests on the closing connection 🙈 And if the Logout Request is meant to close the session, new iSCSI requests MUST NOT be sent on any of the connections in that session. no sneaking in extra requests 💀
When the target gets a Logout Request with the reason code "close the connection" or "close the session", it MUST terminate all pending commands on that connection or session, respectively, whether they were acknowledged via the ExpCmdSN or not. ✨
When the target gets a Logout Request with the reason code "remove the connection for recovery", it MUST discard all requests that weren't yet acknowledged via the ExpCmdSN and were issued on the specified connection. It also has to suspend all data/status/R2T transfers on behalf of pending commands on that connection 🫶
Then the target sends the Logout Response and half-closes the TCP connection (sends FIN). After the initiator gets the Logout Response and tries to receive the FIN (if it still can), the initiator MUST completely close the logging-out connection. For the terminated commands, no additional responses should be expected. bye bye commands 🦋
A Logout for a CID can happen on a different transport connection when the TCP connection for that CID has already been terminated. In that case, the Logout only implies a logical "closing" of the iSCSI connection for the CID 🧚
All commands that weren't terminated or completed (with status) and acknowledged by the time the connection is fully closed can be reassigned to a new connection, but only if the target supports connection recovery 🌈
If an initiator wants to start recovery for a failing connection, it MUST use the Logout Request to "clean up" the target end of that connection and let recovery start. Or it can use a Login Request with a non-zero TSIH and the same CID on a new connection to get the same effect. In sessions with a single connection, the connection can be closed and then a new one reopened. A connection reinstatement login can also be used for recovery (see Section 6.3.4) ✨
A successful Logout Request with the reason code "close the connection" or "remove the connection for recovery" makes the target throw away unacknowledged commands that came in on the connection being logged out. These are commands that arrived on that connection but haven't been delivered to SCSI, because one or more commands with a smaller CmdSN haven't been received by iSCSI yet. See Section 4.2.2.1. The holes left in the command sequence numbers have to be handled by proper recovery (see Section 7), unless the session is also closed 🧩
The whole logout discussion in this section also applies to an implicit Logout that happens through a connection reinstatement or session reinstatement 👑 When a Login Request does an implicit Logout, it's handled as if it had the reason codes below:
Reason Code Type of Implicit Logout
-------------------------------------------------------------
0 session reinstatement
1 connection reinstatement when the operational
ErrorRecoveryLevel < 2
2 connection reinstatement when the operational
ErrorRecoveryLevel = 2Here's the PDU layout, slay 📐
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0|.|I| 0x06 |1| Reason Code | Reserved |
+---------------+---------------+---------------+---------------+
4|TotalAHSLength | DataSegmentLength |
+---------------------------------------------------------------+
8/ Reserved /
+/ /
+---------------+---------------+---------------+---------------+
16| Initiator Task Tag |
+---------------+---------------+---------------+---------------+
20| CID or Reserved | Reserved |
+---------------+---------------+---------------+---------------+
24| CmdSN |
+---------------+---------------+---------------+---------------+
28| ExpStatSN |
+---------------+---------------+---------------+---------------+
32/ Reserved /
+/ /
+---------------+---------------+---------------+---------------+
48| Header-Digest (optional) |
+---------------+---------------+---------------+---------------+11.14.1. Reason Code
The Reason Code field tells you why the Logout is happening 🎀
- 0 - close the session. All commands associated with the session (if any) are terminated.
- 1 - close the connection. All commands associated with the connection (if any) are terminated.
- 2 - remove the connection for recovery. The connection is closed, and all commands associated with it, if any, are to be prepared for a new allegiance.
All other values are reserved. 🙃
11.14.2. TotalAHSLength and DataSegmentLength
For this PDU, TotalAHSLength and DataSegmentLength MUST be 0. no extras allowed here 🍓
11.14.3. CID
This is the connection ID of the connection to be closed (including closing the TCP stream). This field is only valid if the reason code is not "close the session". 🦋
11.14.4. ExpStatSN
This is the last ExpStatSN value for the connection to be closed. 💜
11.14.5. Implicit Termination of Tasks
okay this part is giving dramatic 😭 A target implicitly terminates the active tasks because of the iSCSI protocol in these cases:
- a) When a connection is implicitly or explicitly logged out with the reason code "close the connection" and there are active tasks allegiant to that connection.
- b) When a connection fails and eventually the connection state times out (state transition M1 in Section 8.2.2) and there are active tasks allegiant to that connection.
- c) When a successful recovery Logout is performed while there are active tasks allegiant to that connection and those tasks eventually time out after the Time2Wait and Time2Retain periods without allegiance reassignment.
- d) When a connection is implicitly or explicitly logged out with the reason code "close the session" and there are active tasks in that session.
If the tasks terminated in any of those cases are SCSI tasks, they must be internally terminated as if with CHECK CONDITION status. This status only matters for handling the internal SCSI state and SCSI side effects around ordering, because it's never sent back to the initiator as a terminating status. However, extra actions might be needed at the SCSI level, depending on the SCSI context as defined by the SCSI standards (e.g., queued commands and ACA; UA for the next command on the I_T nexus in cases a), b), and c) above). After the tasks are terminated, the target MUST report a Unit Attention condition on the next command processed on any connection for each affected I_T_L nexus with the status of CHECK CONDITION, the ASC/ASCQ value of 47h/7Fh ("SOME COMMANDS CLEARED BY ISCSI PROTOCOL EVENT"), etc.; see [SPC3]. ⚠️
11.15. Logout Response
The Logout Response is how the target says whether the cleanup for the connection(s) is done 🌸
After Logout, the TCP connection referred to by the CID MUST be closed at both ends (or all connections must be closed if the logout reason was session close). 🔒
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0|.|.| 0x26 |1| Reserved | Response | Reserved |
+---------------+---------------+---------------+---------------+
4|TotalAHSLength | DataSegmentLength |
+---------------------------------------------------------------+
8/ Reserved /
+/ /
+---------------+---------------+---------------+---------------+
16| Initiator Task Tag |
+---------------+---------------+---------------+---------------+
20| Reserved |
+---------------+---------------+---------------+---------------+
24| StatSN |
+---------------+---------------+---------------+---------------+
28| ExpCmdSN |
+---------------+---------------+---------------+---------------+
32| MaxCmdSN |
+---------------+---------------+---------------+---------------+
36| Reserved |
+---------------------------------------------------------------+
40| Time2Wait | Time2Retain |
+---------------+---------------+---------------+---------------+
44| Reserved |
+---------------+---------------+---------------+---------------+
48| Header-Digest (optional) |
+---------------+---------------+---------------+---------------+11.15.1. Response
Here's what the Response field can be set to ✨
- 0 - connection or session closed successfully.
- 1 - CID not found.
- 2 - connection recovery is not supported (i.e., the Logout reason code was "remove the connection for recovery" and the target does not support it as indicated by the operational ErrorRecoveryLevel).
- 3 - cleanup failed for various reasons.
11.15.2. TotalAHSLength and DataSegmentLength
For this PDU, TotalAHSLength and DataSegmentLength MUST be 0. same energy as before, zero extras 🫶
11.15.3. Time2Wait
If the Logout response code is 0 and the operational ErrorRecoveryLevel is 2, this is the minimum amount of time, in seconds, to wait before attempting task reassignment. If the Logout response code is 0 and the operational ErrorRecoveryLevel is less than 2, this field is to be ignored. 🕰️
This field is invalid if the Logout response code is 1. ❌
If the Logout response code is 2 or 3, this field specifies the minimum time to wait before attempting a new implicit or explicit logout. ⏳
If Time2Wait is 0, the reassignment or a new Logout may be attempted immediately. 🚀
11.15.4. Time2Retain ✨
okay so Time2Retain is giving "how long the target will hang on to stuff" 💅 If the Logout response code is 0 and the operational ErrorRecoveryLevel is 2, this is the max number of seconds, counted after the initial wait (Time2Wait), that the target waits for allegiance reassignment for any active task. Once that's up, the task state gets tossed 🗑️ If the Logout response code is 0 and the operational ErrorRecoveryLevel is less than 2, this field is to be ignored 🙈
This field is invalid if the Logout response code is 1 ❌
If the Logout response code is 2 or 3, this field is the max number of seconds after Time2Wait that the target waits for a new implicit or explicit logout 🦋
If it's the last connection of a session, the whole session state gets discarded after Time2Retain 💀
If Time2Retain is 0, the target already dropped the connection (and possibly the session) state along with the task states. So no reassignment or Logout is needed here, bestie 🫶
11.16. SNACK Request 🎀
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0|.|.| 0x10 |1|.|.|.| Type | Reserved |
+---------------+---------------+---------------+---------------+
4|TotalAHSLength | DataSegmentLength |
+---------------+---------------+---------------+---------------+
8| LUN or Reserved |
+ +
12| |
+---------------+---------------+---------------+---------------+
16| Initiator Task Tag or 0xffffffff |
+---------------+---------------+---------------+---------------+
20| Target Transfer Tag or SNACK Tag or 0xffffffff |
+---------------+---------------+---------------+---------------+
24| Reserved |
+---------------+---------------+---------------+---------------+
28| ExpStatSN |
+---------------+---------------+---------------+---------------+
32/ Reserved /
+/ /
+---------------+---------------+---------------+---------------+
40| BegRun |
+---------------------------------------------------------------+
44| RunLength |
+---------------------------------------------------------------+
48| Header-Digest (optional) |
+---------------+---------------+---------------+---------------+If the implementation supports ErrorRecoveryLevel greater than zero, it MUST support all SNACK types 🔥
The SNACK is how the initiator asks the target to resend numbered responses, data, or R2T PDUs 📬 The SNACK Request names the numbered responses or data "runs" it wants back. A run starts at the first StatSN, DataSN, or R2TSN that needs resending, and its length is how many Status, Data, or R2T PDUs are being asked for, counting that first one too. 0 has a special meaning when it's used as a starting number and as a length:
- When used in RunLength, it means all PDUs starting with the initial.
- When used in both BegRun and RunLength, it means all unacknowledged PDUs.
The numbered response(s) or R2T(s) requested by a SNACK MUST be delivered as exact replicas of the ones the target sent originally, except for the fields ExpCmdSN, MaxCmdSN, and ExpDataSN, which MUST carry the current values. R2T(s) requested by SNACK MUST also carry the current value of the StatSN 💖
The numbered Data-In PDUs requested by a Data SNACK MUST be delivered as exact replicas of the ones the target sent originally, except for the fields ExpCmdSN and MaxCmdSN, which MUST carry the current values; and except for resegmentation (see Section 11.16.3) ✨
Any SNACK that requests a numbered response, data, or R2T that was not sent by the target, or that was already acknowledged by the initiator, MUST be rejected with a reason code of "Protocol Error" 🙅♀️
11.16.1. Type 🌈
This field encodes the SNACK function like this:
0 - Data/R2T SNACK: requesting retransmission of one or more
Data-In or R2T PDUs.
1 - Status SNACK: requesting retransmission of one or more
numbered responses.
2 - DataACK: positively acknowledges Data-In PDUs.
3 - R-Data SNACK: requesting retransmission of Data-In PDUs with
possible resegmentation and status tagging.
All other values are reserved.Data/R2T SNACK, Status SNACK, or R-Data SNACK for a command MUST precede status acknowledgment for the given command 🍓
11.16.2. Data Acknowledgment 🦋
If an initiator operates at ErrorRecoveryLevel 1 or higher, it MUST issue a SNACK of type DataACK after receiving a Data-In PDU with the A bit set to 1. BUT if the initiator has detected holes in the input sequence, it MUST postpone issuing the SNACK of type DataACK until the holes are filled 🕳️ An initiator MAY ignore the A bit if it deems that the bit is being set aggressively by the target (i.e., before the MaxBurstLength limit is reached) 🧚
The DataACK is used to free resources at the target, and NOT to request or imply data retransmission. Not the vibe 🙅♀️
An initiator MUST NOT request retransmission for any data it had already acknowledged 🚫
11.16.3. Resegmentation 🧩
If the initiator MaxRecvDataSegmentLength changed between the original transmission and the time the initiator requests retransmission, the initiator MUST issue a R-Data SNACK (see Section 11.16.1). With a R-Data SNACK, the initiator says it discards all the unacknowledged data and expects the target to resend it. It also expects resegmentation 🔄 In this case, the retransmitted Data-In PDUs MAY be different from the ones originally sent, so they can reflect changes in MaxRecvDataSegmentLength. Their DataSN starts with the BegRun of the last DataACK received by the target, if any was received. Otherwise, it starts with 0 and goes up by 1 for each resent Data-In PDU 🔢
A target that has received a R-Data SNACK MUST return a SCSI Response that contains a copy of the SNACK Tag field from the R-Data SNACK, in the SCSI Response SNACK Tag field, as its last or only Response. For example, if it has already sent a response with a different value in the SNACK Tag field, or it had the status included in the last Data-In PDU, it must send a new SCSI Response PDU. If a target sends more than one SCSI Response PDU because of this rule, all SCSI Response PDUs must carry the same StatSN (see Section 11.4.4). If an initiator tries to recover a lost SCSI Response (with a Status-SNACK; see Section 11.16.1) when more than one response has been sent, the target will send the SCSI Response with the latest content known to the target, including the last SNACK Tag for the command 🫠
For considerations in allegiance reassignment of a task to a connection with a different MaxRecvDataSegmentLength, refer to Section 7.2.2 🔍
11.16.4. Initiator Task Tag 🏷️
For a Status SNACK and DataACK, the Initiator Task Tag MUST be set to the reserved value 0xffffffff. In all other cases, the Initiator Task Tag field MUST be set to the Initiator Task Tag of the referenced command 💜
11.16.5. Target Transfer Tag or SNACK Tag 🎯
For a R-Data SNACK, this field MUST contain a value that is different from 0 or 0xffffffff and is unique for the task (identified by the Initiator Task Tag). This value MUST be copied by the iSCSI target in the last or only SCSI Response PDU it issues for the command 🎀
For DataACK, the Target Transfer Tag MUST contain a copy of the Target Transfer Tag and LUN provided with the SCSI Data-In PDU with the A bit set to 1 ✨
In all other cases, the Target Transfer Tag field MUST be set to the reserved value 0xffffffff 🙌
11.16.6. BegRun 🌸
This field indicates the DataSN, R2TSN, or StatSN of the first PDU whose retransmission is requested (Data/R2T and Status SNACK), or the next expected DataSN (DataACK SNACK) 🫶
A BegRun of 0, used together with a RunLength of 0, means "resend all unacknowledged Data-In, R2T or Response PDUs" 🧠
BegRun MUST be 0 for a R-Data SNACK 💅
11.16.7. RunLength 📏
This field indicates the number of PDUs whose retransmission is requested 📈
A RunLength of 0 signals that all Data-In, R2T, or Response PDUs carrying numbers equal to or greater than BegRun have to be resent 🔁
The RunLength MUST also be 0 for a DataACK SNACK, in addition to a R-Data SNACK 💀
11.17. Reject ✨
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0|.|.| 0x3f |1| Reserved | Reason | Reserved |
+---------------+---------------+---------------+---------------+
4|TotalAHSLength | DataSegmentLength |
+---------------+---------------+---------------+---------------+
8/ Reserved /
+/ /
+---------------+---------------+---------------+---------------+
16| 0xffffffff |
+---------------+---------------+---------------+---------------+
20| Reserved |
+---------------+---------------+---------------+---------------+
24| StatSN |
+---------------+---------------+---------------+---------------+
28| ExpCmdSN |
+---------------+---------------+---------------+---------------+
32| MaxCmdSN |
+---------------+---------------+---------------+---------------+
36| DataSN/R2TSN or Reserved |
+---------------+---------------+---------------+---------------+
40| Reserved |
+---------------+---------------+---------------+---------------+
44| Reserved |
+---------------+---------------+---------------+---------------+
48| Header-Digest (optional) |
+---------------+---------------+---------------+---------------+
xx/ Complete Header of Bad PDU /
+/ /
+---------------+---------------+---------------+---------------+
yy/Vendor-specific data (if any) /
/ /
+---------------+---------------+---------------+---------------+
zz| Data-Digest (optional) |
+---------------+---------------+---------------+---------------+Okay so Reject is the PDU you send when something has gone wrong 💀. It's used to indicate an iSCSI error condition (protocol stuff, unsupported option, etc.) 🫶
11.17.1. Reason
Here's the reason code table, bestie 💅:
+------+----------------------------------------+----------------+
| Code | Explanation |Can the original|
| (hex)| |PDU be resent? |
+------+----------------------------------------+----------------+
| 0x01 | Reserved | no |
| | | |
| 0x02 | Data (payload) digest error | yes (Note 1) |
| | | |
| 0x03 | SNACK Reject | yes |
| | | |
| 0x04 | Protocol Error (e.g., SNACK Request for| no |
| | a status that was already acknowledged)| |
| | | |
| 0x05 | Command not supported | no |
| | | |
| 0x06 | Immediate command reject - too many | yes |
| | immediate commands | |
| | | |
| 0x07 | Task in progress | no |
| | | |
| 0x08 | Invalid data ack | no |
| | | |
| 0x09 | Invalid PDU field | no (Note 2) |
| | | |
| 0x0a | Long op reject - Can't generate Target | yes |
| | Transfer Tag - out of resources | |
| | | |
| 0x0b | Deprecated; MUST NOT be used | N/A (Note 3) |
| | | |
| 0x0c | Waiting for Logout | no |
+------+----------------------------------------+----------------+Note 1 🔁: For iSCSI, Data-Out PDU retransmission only happens if the target asks for it with a recovery R2T. BUT if it's a data digest error on immediate data, the initiator can choose to resend the whole PDU, immediate data and all ✨.
Note 2 🙈: A target should use this reason code for all invalid values of PDU fields that are meant to describe a task, a response, or a data transfer. Some examples are invalid TTT/ITT, buffer offset, LUN qualifying a TTT, and an invalid sequence number in a SNACK.
Note 3 🚫: Reason code 0x0b ("Negotiation Reset") as defined in Section 10.17.1 of [RFC3720] is deprecated and MUST NOT be used by implementations. An implementation that receives reason code 0x0b MUST treat it as a negotiation failure that ends the Login Phase and the TCP connection, as specified in Section 7.12 💀.
All other values for Reason are unassigned 🌸.
In all the cases where a pre-instantiated SCSI task is terminated because of the reject, the target MUST issue a proper SCSI command response with CHECK CONDITION as described in Section 11.4.3 💥. In the cases where a status for the SCSI task was already sent before the reject, no additional status is required. If the error is detected while data from the initiator is still expected (i.e., the command PDU did not contain all the data and the target has not received a Data-Out PDU with the Final bit set to 1 for the unsolicited data, if any, and all outstanding R2Ts, if any), the target MUST wait until it receives the last expected Data-Out PDUs with the F bit set to 1 before sending the Response PDU 🫶.
For additional usage semantics of the Reject PDU, see Section 7.3 🦋.
11.17.2. DataSN/R2TSN
This field is only valid if the rejected PDU is a Data/R2T SNACK and the Reject reason code is "Protocol Error" (see Section 11.16). The DataSN/R2TSN is the next Data/R2T sequence number that the target would send for the task, if any 🎀.
11.17.3. StatSN, ExpCmdSN, and MaxCmdSN
These fields carry their usual values and are not related to the rejected command. The StatSN is advanced after a Reject ⭐.
11.17.4. Complete Header of Bad PDU
The target returns the header (not including the digest) of the PDU in error as the data of the response 🧚.
11.18. NOP-Out
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0|.|I| 0x00 |1| Reserved |
+---------------+---------------+---------------+---------------+
4|TotalAHSLength | DataSegmentLength |
+---------------+---------------+---------------+---------------+
8| LUN or Reserved |
+ +
12| |
+---------------+---------------+---------------+---------------+
16| Initiator Task Tag or 0xffffffff |
+---------------+---------------+---------------+---------------+
20| Target Transfer Tag or 0xffffffff |
+---------------+---------------+---------------+---------------+
24| CmdSN |
+---------------+---------------+---------------+---------------+
28| ExpStatSN |
+---------------+---------------+---------------+---------------+
32/ Reserved /
+/ /
+---------------+---------------+---------------+---------------+
48| Header-Digest (optional) |
+---------------+---------------+---------------+---------------+
/ DataSegment - Ping Data (optional) /
+/ /
+---------------+---------------+---------------+---------------+
| Data-Digest (optional) |
+---------------+---------------+---------------+---------------+NOP-Out may be used by an initiator as a "ping request" to verify that a connection/session is still active and all its components are operational 🏓. The NOP-In response is the "ping echo" 🔁.
A NOP-Out is also sent by an initiator in response to a NOP-In 💬.
A NOP-Out may also be used to confirm a changed ExpStatSN if another PDU will not be available for a long time ⏳.
Upon receipt of a NOP-In with the Target Transfer Tag set to a valid value (not the reserved value 0xffffffff), the initiator MUST respond with a NOP-Out. In this case, the NOP-Out Target Transfer Tag MUST contain a copy of the NOP-In Target Transfer Tag. The initiator SHOULD NOT send a NOP-Out in response to any other received NOP-In, in order to avoid lengthy sequences of NOP-In and NOP-Out PDUs sent in response to each other 🙃.
11.18.1. Initiator Task Tag
The NOP-Out MUST have the Initiator Task Tag set to a valid value only if a response in the form of a NOP-In is requested (i.e., the NOP-Out is used as a ping request). Otherwise, the Initiator Task Tag MUST be set to 0xffffffff 🎯.
When a target receives the NOP-Out with a valid Initiator Task Tag, it MUST respond with a NOP-In Response (see Section 4.6.3.6) 💖.
If the Initiator Task Tag contains 0xffffffff, the I bit MUST be set to 1, and the CmdSN is not advanced after this PDU is sent 🌈.
11.18.2. Target Transfer Tag
The Target Transfer Tag is a target-assigned identifier for the operation 🏷️.
The NOP-Out MUST only have the Target Transfer Tag set if it is issued in response to a NOP-In with a valid Target Transfer Tag. In this case, it copies the Target Transfer Tag from the NOP-In PDU. Otherwise, the Target Transfer Tag MUST be set to 0xffffffff 🪞.
When the Target Transfer Tag is set to a value other than 0xffffffff, the LUN field MUST also be copied from the NOP-In 🫶.
11.18.3. Ping Data
Ping data is reflected in the NOP-In Response. The length of the reflected data is limited to MaxRecvDataSegmentLength. The length of ping data is indicated by the DataSegmentLength. 0 is a valid value for the DataSegmentLength and indicates the absence of ping data 🌸.
11.19. NOP-In ✨
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0|.|.| 0x20 |1| Reserved |
+---------------+---------------+---------------+---------------+
4|TotalAHSLength | DataSegmentLength |
+---------------+---------------+---------------+---------------+
8| LUN or Reserved |
+ +
12| |
+---------------+---------------+---------------+---------------+
16| Initiator Task Tag or 0xffffffff |
+---------------+---------------+---------------+---------------+
20| Target Transfer Tag or 0xffffffff |
+---------------+---------------+---------------+---------------+
24| StatSN |
+---------------+---------------+---------------+---------------+
28| ExpCmdSN |
+---------------+---------------+---------------+---------------+
32| MaxCmdSN |
+---------------+---------------+---------------+---------------+
36/ Reserved /
+/ /
+---------------+---------------+---------------+---------------+
48| Header-Digest (optional) |
+---------------+---------------+---------------+---------------+
/ DataSegment - Return Ping Data /
+/ /
+---------------+---------------+---------------+---------------+
| Data-Digest (optional) |
+---------------+---------------+---------------+---------------+Okay so NOP-In is what a target sends back 🎀. It can be a response to a NOP-Out, a "ping" aimed at an initiator, or a way to carry a changed ExpCmdSN and/or MaxCmdSN when no other PDU is going to show up for a really long time (and the target gets to decide what "long" means 💅).
When a target gets a NOP-Out with a valid Initiator Task Tag (so, not the reserved 0xffffffff), it MUST reply with a NOP-In that has the same Initiator Task Tag the NOP-Out came with 🫶. It MUST also echo back up to the first MaxRecvDataSegmentLength bytes of the initiator-provided Ping Data. For this kind of reply, the Target Transfer Tag MUST be 0xffffffff. The target SHOULD NOT send a NOP-In in response to any other NOP-Out, so we don't end up with super long NOP-In and NOP-Out ping-pong sequences that just keep going 😭.
Otherwise, when a target sends a NOP-In that isn't a response to a NOP-Out from the initiator, the Initiator Task Tag MUST be 0xffffffff, and the data segment MUST NOT contain any data (DataSegmentLength MUST be 0) 🙈.
11.19.1. Target Transfer Tag
If the target is responding to a NOP-Out, this field is set to the reserved value 0xffffffff 🌸.
If the target is sending a NOP-In as a ping (meaning it wants to receive a matching NOP-Out back), this field is set to a valid value, so anything but the reserved 0xffffffff ✨.
If the target is starting a NOP-In without wanting a matching NOP-Out back, this field MUST hold the reserved value 0xffffffff 💜.
11.19.2. StatSN
The StatSN field will always contain the next StatSN. However, when the Initiator Task Tag is set to 0xffffffff, the StatSN for the connection is not advanced after this PDU is sent 🦋.
11.19.3. LUN
A LUN MUST be set to a correct value when the Target Transfer Tag is valid (not the reserved value 0xffffffff) 👑.
12. iSCSI Security Text Keys and Authentication Methods 🔐
Only the following keys are used during the SecurityNegotiation stage of the Login Phase 🧚:
SessionType
InitiatorName
TargetName
TargetAddress
InitiatorAlias
TargetAlias
TargetPortalGroupTag
AuthMethod and the keys used by the authentication methods
specified in Section 12.1, along with all of their associated
keys, as well as Vendor-Specific Authentication Methods.Other keys MUST NOT be used. Not even a little bit 🙅♀️.
SessionType, InitiatorName, TargetName, InitiatorAlias, TargetAlias, and TargetPortalGroupTag are described in Section 13, since they can be used in the OperationalNegotiation stage as well ✨.
All security keys have connection-wide applicability 🍓.
12.1. AuthMethod
Use: During Login - Security Negotiation
Senders: Initiator and target
Scope: connection
AuthMethod = <list-of-values>The main item of security negotiation is the authentication method (AuthMethod) 💖.
The authentication methods that can be used (the ones that appear in the list-of-values) are either vendor-unique methods or the ones in this table 📋:
+--------------------------------------------------------------+
| Name | Description |
+--------------------------------------------------------------+
| KRB5 | Kerberos V5 - defined in [RFC4120] |
+--------------------------------------------------------------+
| SRP | Secure Remote Password - |
| | defined in [RFC2945] |
+--------------------------------------------------------------+
| CHAP | Challenge Handshake Authentication Protocol - |
| | defined in [RFC1994] |
+--------------------------------------------------------------+
| None | No authentication |
+--------------------------------------------------------------+The AuthMethod selection is followed by an "authentication exchange" that's specific to whichever authentication method got picked 🔁.
Either the initiator or the target can propose the authentication method. However, the initiator MUST make the first step specific to the selected authentication method as soon as it is selected 🏃♀️. So if the target makes the proposal, the initiator sends the first key(s) of the exchange together with its authentication method selection 💅.
The authentication exchange authenticates the initiator to the target and, optionally, the target to the initiator. Authentication is OPTIONAL to use, but it MUST be supported by the target and the initiator 🫶.
The initiator and target MUST implement CHAP. All other authentication methods are OPTIONAL 💜.
Private or public extension algorithms MAY also be negotiated for authentication methods. Whenever a private or public extension algorithm is part of the default offer (the offer made in the absence of explicit administrative action), the implementer MUST ensure that CHAP is listed as an alternative in the default offer and "None" is not part of the default offer 🙈.
Extension authentication methods MUST be named using one of the following two formats:
1) Z-reversed.vendor.dns_name.do_something=
2) New public key with no name prefix constraintsAuthentication methods named using the Z- format are used as private extensions. New public keys must be registered with IANA using the IETF Review process ([RFC5226]). New public extensions for authentication methods MUST NOT use the Z# name prefix 🚫.
For all of the public or private extension authentication methods, the method-specific keys MUST conform to the format specified in Section 6.1 for standard-label 🎀.
To identify the vendor for private extension authentication methods, we suggest using the reversed DNS-name as a prefix to the proper digest names 🌈.
The part of digest-name that follows Z- MUST conform to the format for standard-label specified in Section 6.1 ✨.
Support for public or private extension authentication methods is OPTIONAL 🦋.
The following subsections define the specific exchanges for each of the standardized authentication methods. As mentioned earlier, the first step is always done by the initiator 👑.
12.1.1. Kerberos
For KRB5 (Kerberos V5) [RFC4120] [RFC1964], the initiator MUST use:
KRB_AP_REQ=<KRB_AP_REQ>where KRB_AP_REQ is the client message as defined in [RFC4120] 🧚.
The default principal name assumed by an iSCSI initiator or target (before any administrative configuration action) MUST be the iSCSI Initiator Name or iSCSI Target Name, respectively, prefixed by the string "iscsi/" 🍓.
If the initiator authentication fails, the target MUST respond with a Login reject with "Authentication Failure" status. Otherwise, if the initiator has selected the mutual authentication option (by setting MUTUAL-REQUIRED in the ap-options field of the KRB_AP_REQ), the target MUST reply with:
KRB_AP_REP=<KRB_AP_REP>where KRB_AP_REP is the server's response message as defined in [RFC4120] 💖.
If mutual authentication was selected and target authentication fails, the initiator MUST close the connection 😭.
KRB_AP_REQ and KRB_AP_REP are binary-values, and their binary length (not the length of the character string that represents them in encoded form) MUST NOT exceed 65536 bytes 🙅♀️. Hex or Base64 encoding may be used for KRB_AP_REQ and KRB_AP_REP; see Section 6.1 🌸.
12.1.2. Secure Remote Password (SRP)
For SRP [RFC2945], the initiator MUST use:
SRP_U=<U> TargetAuth=Yes /* or TargetAuth=No */The target MUST answer with a Login reject with the "Authorization Failure" status or reply with:
SRP_GROUP=<G1,G2...> SRP_s=<s>where G1,G2... are proposed groups, in order of preference 📋.
The initiator MUST either close the connection or continue with:
SRP_A=<A> SRP_GROUP=<G>where G is one of G1,G2... that were proposed by the target ✨.
The target MUST answer with a Login reject with the "Authentication Failure" status or reply with:
SRP_B=<B>The initiator MUST close the connection or continue with:
SRP_M=<M>If the initiator authentication fails, the target MUST answer with a Login reject with "Authentication Failure" status. Otherwise, if the initiator sent TargetAuth=Yes in the first message (requiring target authentication), the target MUST reply with:
SRP_HM=<H(A | M | K)>If the target authentication fails, the initiator MUST close the connection:
where U, s, A, B, M, and H(A | M | K) are defined in [RFC2945] (using the SHA1 hash function, such as SRP-SHA1)
and
G,Gn ("Gn" stands for G1,G2...) are identifiers of SRP groups specified in [RFC3723] 🔐.
G, Gn, and U are text strings; s, A, B, M, and H(A | M | K) are binary-values. The length of s, A, B, M and H(A | M | K) in binary form (not the length of the character string that represents them in encoded form) MUST NOT exceed 1024 bytes. Hex or Base64 encoding may be used for s, A, B, M and H(A | M | K); see Section 6.1 🦋.
See Appendix B for the related login example 🧁.
For the SRP_GROUP, all the groups specified in [RFC3723] up to 1536 bits (i.e., SRP-768, SRP-1024, SRP-1280, SRP-1536) must be supported by initiators and targets. To guarantee interoperability, targets MUST always offer "SRP-1536" as one of the proposed groups 🌈.
12.1.3. Challenge Handshake Authentication Protocol (CHAP) 🔐
okay so for CHAP [RFC1994], the initiator MUST start by sending its list of proposed algorithms, in order of preference:
CHAP_A=<A1,A2...>where A1,A2... are the proposed algorithms. 💅
The target MUST answer with a Login reject carrying the "Authentication Failure" status, or it replies with:
CHAP_A=<A> CHAP_I=<I> CHAP_C=<C>where A is one of the A1,A2... that the initiator proposed. ✨
Then the initiator MUST continue with:
CHAP_N=<N> CHAP_R=<R>or, if it needs target authentication too, with:
CHAP_N=<N> CHAP_R=<R> CHAP_I=<I> CHAP_C=<C>If the initiator fails authentication, the target MUST answer with a Login reject with "Authentication Failure" status. Otherwise, if the initiator asked for target authentication, the target MUST either answer with a Login reject with "Authentication Failure", or reply with:
CHAP_N=<N> CHAP_R=<R>And if the target authentication fails, the initiator MUST close the connection. 🚪
Quick decoder ring: N, (A,A1,A2), I, C, and R are the Name, Algorithm, Identifier, Challenge, and Response, exactly as defined in [RFC1994]. 🧠
N is a text string. A, A1, A2, and I are numbers. C and R are binary values, and their binary length (not the length of the character string that shows them in encoded form) MUST NOT exceed 1024 bytes. Hex or Base64 encoding may be used for C and R; see Section 6.1. 🎀
There's a related login example in Appendix B, so go peek at that. 👀
For the Algorithm, as [RFC1994] says, exactly one value is required to be implemented:
5 (CHAP with MD5)To keep things interoperable, initiators MUST always offer it as one of the proposed algorithms. 🫶
13. Login/Text Operational Text Keys 🌸
Some session-specific parameters MUST only be carried on the leading connection, and you can't change them after the leading connection's login (MaxConnections is the classic example, the maximum number of connections). This holds for a single connection session too, when it restarts. Keys in this bucket get the use: LO (Leading Only) tag. 👑
Keys that can only be used during login get use: IO (Initialize Only). Keys that work in both the Login Phase and the Full Feature Phase get use: ALL. Keys that only work in the Full Feature Phase use FFPO (Full Feature Phase Only). 🦋
Keys marked Any-Stage can also show up in the SecurityNegotiation stage. Every other key in this section is an operational key. 🌈
Keys that don't need an answer are marked Declarative. Key scope is either session-wide (SW) or connection-only (CO). 💜
Now, "result function" shows up a lot, so here's what it means: it's the check you run to confirm the responder picked a valid value. "Minimum" means the selected value can't be bigger than the offered value. "Maximum" means the selected value can't be smaller than the offered value. "AND" means the selected value has to be something a Boolean "and" could produce, using some arbitrary Boolean value (so if the offer is No, the answer has to be No). "OR" means the selected value has to be something a Boolean "or" could produce (so if the offer is Yes, the answer has to be Yes). 🤓
13.1. HeaderDigest and DataDigest 🔍
Use: IO
Senders: Initiator and target
Scope: CO
HeaderDigest = <list-of-values>
DataDigest = <list-of-values>The default for both HeaderDigest and DataDigest is None. ✨
Digests let you check end-to-end, non-cryptographic data integrity. That's on top of whatever the link layers already check, and it covers the whole communication path, including every element that might change the network-level PDUs, like routers, switches, and proxies. 🛣️
The table below lists the cyclic integrity checksums you can negotiate for digests. They MUST be implemented by every iSCSI initiator and target. These digest options only have error detection significance. 🔥
+---------------------------------------------+
| Name | Description | Generator |
+---------------------------------------------+
| CRC32C | 32-bit CRC |0x11edc6f41|
+---------------------------------------------+
| None | no digest |
+---------------------------------------------+The generator polynomial G(x) for this digest is written in hex. For example, "0x3b" stands for 0011 1011, which makes the polynomial x5 + x4 + x**3 + x + 1. 🧮
When the initiator and target agree on a digest, that digest MUST be used for every PDU in the Full Feature Phase. 💖
If there's padding in a segment that a CRC covers, the padding SHOULD be set to 0, and it's included in the CRC. 🧸
The CRC MUST be calculated in a way that gives the same results as this process:
- Treat the PDU bits as the coefficients of a polynomial M(x) of degree n - 1. Bit 7 of the lowest numbered byte is the most significant bit (
x**n - 1), then you go through bit 6 of the lowest numbered byte, all the way down to bit 0 of the highest numbered byte (x**0). 🔢 - Complement the most significant 32 bits. 🙃
- Multiply the polynomial by
x**32, then divide it by G(x). The division leaves a remainder R(x) of degree <= 31. ➗ - Form the coefficients of R(x) into a 32-bit sequence. 🧵
- Complement that bit sequence, and the result is the CRC. ✅
- Map the CRC bits into the digest word. The
x**31coefficient goes to bit 7 of the lowest numbered byte of the digest, and the mapping keeps going with the successive coefficients and bits, sox**24lands on bit 0 of the lowest numbered byte. Thenx**23goes to bit 7 of the next byte, and this continues untilx**0lands on bit 0 of the highest numbered byte of the digest. 🗺️ - Here's a fun check: if you compute the CRC over any segment (data or header) extended to include the CRC built with generator 0x11edc6f41, the final remainder (R(x)) will always be 0x1c2d19ed. That value is written in its polynomial form here, not mapped as a digest word. 🪄
For a discussion about picking a CRC, see [RFC3385]. For a detailed look at the iSCSI polynomial, see [Castagnoli93]. 📚
Private or public extension algorithms MAY also be negotiated for digests. Whenever a private or public digest extension algorithm is part of the default offer (the offer made when nobody has taken any explicit administrative action), the implementer MUST make sure that CRC32C is listed as an alternative in the default offer, and that "None" is NOT part of the default offer. 🙌
Naming matters! Extension digest algorithms MUST be named using one of the following two formats:
1) Y-reversed.vendor.dns_name.do_something=
2) New public key with no name prefix constraintsDigests named with the Y- format are for private purposes (unregistered). New public keys must be registered with IANA using the IETF Review process ([RFC5226]). New public extensions for digests MUST NOT use the Y# name prefix. 🚫
For private extension digests, to identify the vendor, we suggest using the reversed DNS name as a prefix for the digest names. 🏷️
The part of a digest name that follows Y- MUST conform to the format for standard-label specified in Section 6.1. 💅
Support for public or private extension digests is OPTIONAL. 🌟
13.2. MaxConnections 🔗
Use: LO
Senders: Initiator and target
Scope: SW
Irrelevant when: SessionType=DiscoveryMaxConnections=<numerical-value-from-1-to-65535>Default is 1. The result function is Minimum. 💖
The initiator and target negotiate the maximum number of connections each side will request or accept. 🤝
13.3. SendTargets 📣
Use: FFPO
Senders: Initiator
Scope: SWFor a complete description, see Appendix C. 📖
13.4. TargetName 🎯
Use: IO by initiator, FFPO by target -- only as response to a
SendTargets, Declarative, Any-Stage
Senders: Initiator and target
Scope: SWTargetName=<iSCSI-name-value>Examples:
TargetName=iqn.1993-11.com.disk-vendor:diskarrays.sn.45678
TargetName=eui.020000023B040506
TargetName=naa.62004567BA64678D0123456789ABCDEFIf the initiator isn't establishing a Discovery session, the initiator of the TCP connection MUST give this key to the remote endpoint in the first Login Request. The iSCSI Target Name is the worldwide unique name of the target. 🌍
The TargetName key can also be returned by the SendTargets Text Request, which is its only use when a target issues it. 🔁
The TargetName MUST NOT be redeclared within the Login Phase. 🙅♀️
13.5. InitiatorName 🪪
Use: IO, Declarative, Any-Stage
Senders: Initiator
Scope: SWInitiatorName=<iSCSI-name-value>Examples:
InitiatorName=iqn.1992-04.com.os-vendor.plan9:cdrom.12345
InitiatorName=iqn.2001-02.com.ssp.users:customer235.host90
InitiatorName=naa.52004567BA64678DThe initiator of the TCP connection MUST give this key to the remote endpoint at the first login of the Login Phase for every connection. The InitiatorName key is how the initiator introduces itself to the remote endpoint. 👋
The InitiatorName MUST NOT be redeclared within the Login Phase. 🚫
13.6. TargetAlias 🏷️
Use: ALL, Declarative, Any-Stage
Senders: Target
Scope: SWTargetAlias=<iSCSI-local-name-value>Examples:
TargetAlias=Bob-s Disk
TargetAlias=Database Server 1 Log Disk
TargetAlias=Web Server 3 Disk 20If a target has a human-readable name or description configured, that name SHOULD be sent to the initiator in a Login Response PDU when SessionType=Normal (see Section 13.21). This string isn't used as an identifier, and it isn't meant for authentication or authorization decisions. It's just for the initiator's UI, where it can show up in a list of the targets it's connected to. 🎀
13.7. InitiatorAlias 🦄
Use: ALL, Declarative, Any-Stage
Senders: Initiator
Scope: SWInitiatorAlias=<iSCSI-local-name-value>Examples:
InitiatorAlias=Web Server 4
InitiatorAlias=spyalley.nsa.gov
InitiatorAlias=Exchange ServerIf an initiator has a human-readable name or description configured, it SHOULD be sent to the target in a Login Request PDU. If it doesn't, the host name can be used instead. This string isn't used as an identifier, and it isn't meant for authentication or authorization decisions. It can be displayed in the target's UI, in a list of the initiators connected to it. 🧚
13.8. TargetAddress ✨
Use: ALL, Declarative, Any-Stage Senders: Target Scope: SW
TargetAddress=domainname[:port][,portal-group-tag]okay so the domainname can be a DNS host name, a dotted-decimal IPv4 address, or a bracketed IPv6 address, all as defined in [RFC3986] 💅
if the TCP port isn't specified, it's assumed to be the IANA-assigned default port for iSCSI (see Section 14) 🧚
if the TargetAddress comes back as the result of a redirect status in a Login Response, the comma and portal-group-tag MUST be omitted. 🚫
if the TargetAddress is returned inside a SendTargets response, the portal-group-tag MUST be included 🎀
here are some examples, bestie 🍓
TargetAddress=10.0.0.1:5003,1
TargetAddress=[1080:0:0:0:8:800:200C:417A],65
TargetAddress=[1080::8:800:200C:417A]:5003,1
TargetAddress=computingcenter.example.com,23the use of the portal-group-tag is described in Appendix C 🦋 and the formats for the port and portal-group-tag are the same as the ones in TargetPortalGroupTag, so it's all one vibe ✨
13.9. TargetPortalGroupTag 🌸
Use: IO by target, Declarative, Any-Stage Senders: Target Scope: SW
TargetPortalGroupTag=<16-bit-binary-value>example, periodt:
TargetPortalGroupTag=1the TargetPortalGroupTag key is a 16-bit binary-value that uniquely identifies a portal group inside an iSCSI target node 🔥 it carries the tag of the portal group that's servicing the Login Request. the iSCSI target sends this key back to the initiator in the Login Response PDU to the first Login Request PDU that has the C bit set to 0 when the initiator gives a TargetName 💜
[SAM2] says in its informative text that the TPGT value should be non-zero, and honestly that's incorrect 🙈 a zero value is allowed as a legal value for the TPGT. this discrepancy is now corrected in [SAM4], so we're good 👑
for the full usage expectations of this key, check out Section 6.3 🧚
13.10. InitialR2T 🌈
Use: LO Senders: Initiator and target Scope: SW Irrelevant when: SessionType=Discovery
InitialR2T=<boolean-value>examples, iykyk:
I->InitialR2T=No
T->InitialR2T=Nothe default is Yes and the result function is OR 💖
the InitialR2T key is used to turn off the default use of R2T for unidirectional operations and for the output part of bidirectional commands. this lets an initiator start sending data to a target as if it had received an initial R2T with this:
Buffer Offset=Immediate Data Length
Desired Data Transfer Length=(min(FirstBurstLength, Expected Data Transfer Length) - Received Immediate Data Length)so the default action is that R2T is required, unless BOTH the initiator and the target send this key-pair attribute saying InitialR2T=No 🙅♀️ only the first outgoing data burst (immediate data and/or separate PDUs) can be sent unsolicited, meaning without needing an explicit R2T ✨
13.11. ImmediateData 🍓
Use: LO Senders: Initiator and target Scope: SW Irrelevant when: SessionType=Discovery
ImmediateData=<boolean-value>the default is Yes and the result function is AND 🎀
the initiator and target negotiate support for immediate data. to turn it off, the initiator or the target has to say so. ImmediateData can be turned on if both the initiator and the target have ImmediateData=Yes 💅
if ImmediateData is Yes and InitialR2T is Yes (the default), then only immediate data is accepted in the first burst 🦋
if ImmediateData is No and InitialR2T is Yes, the initiator MUST NOT send unsolicited data, and the target MUST reject unsolicited data with the corresponding response code 🚫
if ImmediateData is No and InitialR2T is No, the initiator MUST NOT send unsolicited immediate data but MAY send one unsolicited burst of Data-OUT PDUs 🌸
if ImmediateData is Yes and InitialR2T is No, the initiator MAY send unsolicited immediate data and/or one unsolicited burst of Data-OUT PDUs 🧚
here's the cheat sheet for unsolicited data options, bestie 💜
+----------+-------------+------------------+-------------+
|InitialR2T|ImmediateData| Unsolicited |ImmediateData|
| | | Data-Out PDUs | |
+----------+-------------+------------------+-------------+
| No | No | Yes | No |
+----------+-------------+------------------+-------------+
| No | Yes | Yes | Yes |
+----------+-------------+------------------+-------------+
| Yes | No | No | No |
+----------+-------------+------------------+-------------+
| Yes | Yes | No | Yes |
+----------+-------------+------------------+-------------+13.12. MaxRecvDataSegmentLength 🫶
Use: ALL, Declarative Senders: Initiator and target Scope: CO
MaxRecvDataSegmentLength=<numerical-value-512-to-(2**24 - 1)>the default is 8192 bytes 🌈
the initiator or target uses this to declare the maximum data segment length, in bytes, that it can receive in an iSCSI PDU 📣
the transmitter (initiator or target) is required to send PDUs whose data segment does not exceed the MaxRecvDataSegmentLength of the receiver 💖
a target receiver is also limited by MaxBurstLength for solicited data and by FirstBurstLength for unsolicited data. an initiator MUST NOT send solicited PDUs that exceed MaxBurstLength, nor unsolicited PDUs that exceed FirstBurstLength (or FirstBurstLength-Immediate Data Length if immediate data was sent) 😭
13.13. MaxBurstLength 🔥
Use: LO Senders: Initiator and target Scope: SW Irrelevant when: SessionType=Discovery
MaxBurstLength=<numerical-value-512-to-(2**24 - 1)>the default is 262144 (256 KB), and the result function is Minimum 👑
the initiator and target negotiate the maximum SCSI data payload, in bytes, in a Data-In or a solicited Data-Out iSCSI sequence. a sequence is one or more consecutive Data-In or Data-Out PDUs that ends with a Data-In or Data-Out PDU whose F bit is set to 1 ✨
13.14. FirstBurstLength 🦋
Use: LO Senders: Initiator and target Scope: SW Irrelevant when: SessionType=Discovery Irrelevant when: ( InitialR2T=Yes and ImmediateData=No )
FirstBurstLength=<numerical-value-512-to-(2**24 - 1)>the default is 65536 (64 KB), and the result function is Minimum 💅
the initiator and target negotiate the maximum amount of unsolicited data, in bytes, that an iSCSI initiator may send to the target while a single SCSI command is running. this covers the immediate data (if any) and the sequence of unsolicited Data-Out PDUs (if any) that follow the command 🧚
FirstBurstLength MUST NOT exceed MaxBurstLength 🚫
13.15. DefaultTime2Wait 🌸
Use: LO Senders: Initiator and target Scope: SW
DefaultTime2Wait=<numerical-value-0-to-3600>the default is 2, and the result function is Maximum 🕰️
the initiator and target negotiate the minimum time, in seconds, to wait before attempting an explicit or implicit logout, or an active task reassignment, after an unexpected connection termination or a connection reset 💜
a value of 0 means logout or active task reassignment can be attempted right away 🍓
13.16. DefaultTime2Retain 🎀
Use: LO Senders: Initiator and target Scope: SW
DefaultTime2Retain=<numerical-value-0-to-3600>the default is 20, and the result function is Minimum 🌈
the initiator and target negotiate the maximum time, in seconds, after the initial wait (Time2Wait), during which an active task reassignment is still possible after an unexpected connection termination or a connection reset 🫶
this value is also the session state timeout if the connection in question is the last LOGGED_IN connection in the session 🧚
a value of 0 means the target discards the connection/task state immediately 💀
13.17. MaxOutstandingR2T 💖
Use: LO Senders: Initiator and target Scope: SW Irrelevant when: SessionType=Discovery
MaxOutstandingR2T=<numerical-value-from-1-to-65535>the default is 1, and the result function is Minimum 🔥
the initiator and target negotiate the maximum number of outstanding R2Ts per task, not counting any implied initial R2T that might be part of that task 👑 an R2T counts as outstanding until the last data PDU (with the F bit set to 1) is transferred, or until a sequence reception timeout (Section 7.1.4.1) is hit for that data sequence ⏳
13.18. DataPDUInOrder 🦋
Use: LO Senders: Initiator and target Scope: SW Irrelevant when: SessionType=Discovery
DataPDUInOrder=<boolean-value>the default is Yes and the result function is OR 💅
"No" means iSCSI is saying the data PDUs within sequences can come in any order 🌀 "Yes" means the data PDUs within sequences have to sit at continuously increasing addresses, and overlays are forbidden 🚫
13.19. DataSequenceInOrder 🌸
Use: LO Senders: Initiator and target Scope: SW Irrelevant when: SessionType=Discovery
DataSequenceInOrder=<boolean-value>the default is Yes and the result function is OR 🧚
a data sequence is a sequence of Data-In or Data-Out PDUs that ends with a Data-In or Data-Out PDU whose F bit is set to 1. a Data-Out sequence is sent either unsolicited or in response to an R2T. sequences cover an offset-range 🌈
if DataSequenceInOrder is No, data PDU sequences may be transferred in any order 🎲
if DataSequenceInOrder is Yes, data sequences MUST be transferred using continuously non-decreasing sequence offsets. that means the R2T buffer offset for writes, or the smallest SCSI Data-In buffer offset within a read data sequence 📏
if DataSequenceInOrder is Yes, a target may retry at most the last R2T, and an initiator may at most request retransmission for the last read data sequence. because of that, if ErrorRecoveryLevel is not 0 and DataSequenceInOrder is Yes, then MaxOutstandingR2T MUST be set to 1 💖
13.20. ErrorRecoveryLevel 🫶
Use: LO Senders: Initiator and target Scope: SW
ErrorRecoveryLevel=<numerical-value-0-to-2>the default is 0, and the result function is Minimum 🔥
the initiator and target negotiate the recovery level they support 🛟
recovery levels are combos of recovery capabilities. each level includes all the capabilities of the lower levels and adds some new ones on top 📈
when recovery mechanisms are described, certain recovery classes get specified. Section 7.1.5 maps the classes to the levels, so go check it out 🗺️
13.21. SessionType 👑
Use: LO, Declarative, Any-Stage Senders: Initiator Scope: SW
SessionType=<Discovery|Normal>the default is Normal 🌸
the initiator says what type of session it wants to create, and the target can either accept it or reject it ✨
a Discovery session tells the target that the ONLY purpose of this session is discovery 🔍 the only requests a target accepts in this kind of session are a Text Request with a SendTargets key and a Logout Request with reason "close the session" 🚪
the Discovery session implies MaxConnections = 1 and overrides both the default and any explicit setting 🙅♀️ as Section 7.4.1 states, ErrorRecoveryLevel MUST be 0 (zero) for Discovery sessions 💅
depending on the session type, a target may decide which resources to allocate, which security to enforce, and so on for the session 🛡️ if the SessionType key is going to be offered as "Discovery", it SHOULD be offered in the initial Login Request from the initiator 🦋
13.22. The Private Extension Key Format ✨
Okay bestie, this one is all about private extension keys 🎀. Here's the vibe:
Use: ALL Senders: Initiator and target Scope: specific key dependent
The format looks like this: X-reversed.vendor.dns_name.do_something=
These keys are for private extension stuff 🦋. If a key isn't registered with IANA, its name always starts with X-, because that's how you know it's private. New public keys are different. If they're registered with IANA through an IETF Review [RFC5226], they don't need the X# prefix anymore, so implementers can pick any intuitive unique name they like 💅.
For unregistered keys, we suggest putting the reversed DNS name in front of the key name so it's clear which vendor it belongs to 🌸. The part of the key name that comes after X- MUST conform to the format for key-name specified in Section 6.1.
Vendor-specific keys MUST ONLY be used in Normal sessions 🙈.
Support for public or private extension keys is OPTIONAL ✨.
13.23. TaskReporting 💜
Use: LO Senders: Initiator and target Scope: SW Irrelevant when: SessionType=Discovery
TaskReporting=<list-of-values>
Default is RFC3720.
This key is how you negotiate the task completion reporting semantics with the SCSI target 🧚. The table below shows the semantics that an iSCSI target MUST support for each negotiated key value. Whenever this key gets negotiated, the negotiation originator MUST offer at least the RFC3720 and ResponseFence values as options 🔥.
+--------------+------------------------------------------+
| Name | Description |
+--------------+------------------------------------------+
| RFC3720 | RFC 3720-compliant semantics. Response |
| | fencing is not guaranteed, and fast |
| | completion of multi-task aborting is not |
| | supported. |
+--------------+------------------------------------------+
| ResponseFence| Response Fence (Section 4.2.2.3.3) |
| | semantics MUST be supported in reporting |
| | task completions. |
+--------------+------------------------------------------+
| FastAbort | Updated fast multi-task abort semantics |
| | defined in Section 4.2.3.4 MUST be |
| | supported. Support for the Response |
| | Fence is implied -- i.e., semantics as |
| | described in Section 4.2.2.3.3 MUST be |
| | supported as well. |
+--------------+------------------------------------------+When TaskReporting is not negotiated to FastAbort, the standard multi-task abort semantics in Section 4.2.3.3 MUST be used. Don't skip this one, it's the fallback 🫶.
13.24. iSCSIProtocolLevel Negotiation 🌈
The iSCSIProtocolLevel associated with this document is "1" ⭐. As a responder or an originator in a negotiation of this key, an iSCSI implementation compliant to this document alone, without any future protocol extensions, MUST use this value as defined by [RFC7144] 👑.
13.25. Obsoleted Keys 💀
This document obsoletes the following keys defined in [RFC3720]: IFMarker, OFMarker, OFMarkInt, and IFMarkInt. Still, iSCSI implementations compliant to this document may receive these obsoleted keys in a text negotiation, but only in a responder role 👀.
When an IFMarker or OFMarker key is received, a compliant iSCSI implementation SHOULD respond with the constant "Reject" value. It MAY respond with a "No" value instead 🍓.
The implementation MUST NOT respond with a "NotUnderstood" value for either of these keys 🚫.
When an IFMarkInt or OFMarkInt key is received, a compliant iSCSI implementation MUST respond with the constant "Reject" value. The implementation MUST NOT respond with a "NotUnderstood" value for either of these keys 💅.
13.26. X#NodeArchitecture 🦋
13.26.1. Definition
Use: LO, Declarative Senders: Initiator and target Scope: SW
X#NodeArchitecture=<list-of-values>
Default is None.
Examples:
X#NodeArchitecture=ExampleOS/v1234,ExampleInc_SW_Initiator/1.05a
X#NodeArchitecture=ExampleInc_HW_Initiator/4010,Firmware/2.0.0.5
X#NodeArchitecture=ExampleInc_SW_Initiator/2.1,CPU_Arch/i686This document doesn't define the structure or content of the list of values, so that part is up to the implementers 🌸.
The initiator or target uses this key to tell the remote endpoint about its iSCSI node architecture. The details can include, but aren't limited to, iSCSI vendor software, firmware, or hardware versions, the OS version, or the hardware architecture. This key may be declared on a Discovery session or a Normal session ✨.
The length of the key value (the total length of the list-of-values) MUST NOT be greater than 255 bytes. X#NodeArchitecture MUST NOT be redeclared during the Login Phase 🔥.
13.26.2. Implementation Requirements
Here's the big rule 💖: the functional behavior of the iSCSI node (which includes the iSCSI protocol logic, meaning the SCSI, iSCSI, and TCP/IP protocols) MUST NOT depend on whether this key is present, absent, or what its content is. The key MUST NOT be used by iSCSI nodes for interoperability or for excluding other nodes. To keep things proper, key values SHOULD be set by the node itself, and there SHOULD NOT be provisions for the key values to contain user-defined text 🙅♀️.
Nodes implementing this key MUST choose one of the following implementation options:
- only transmit the key,
- only log the key values received from other nodes, or
- both transmit and log the key values.
Each node that chooses to transmit key values MUST be prepared to handle the response of iSCSI nodes that don't understand the key 🥹.
Nodes that transmit and/or log key values may also implement administrative mechanisms that disable and/or change the logging and key transmission details (see Section 9.4). So a valid behavior for this key is that a node is completely silent: it doesn't transmit any key value and just discards any key values it receives, without issuing a NotUnderstood response 🤫.
14. Rationale for Revised IANA Considerations 📚
This document makes pretty significant changes in this area, so this section explains the reasons behind them 💅. In [RFC3720], iSCSI used text string prefixes like X- and X# to tell extended login/text keys, digest algorithms, and authentication methods apart from their standardized counterparts. [RFC6648], however, strongly recommends against this practice 🙈. The main reason is that extensions using those prefixes may become standard over time, and at that point it can be infeasible to change their text string names because so many people are already using them.
iSCSI's experience with public extensions backs up [RFC6648] 🎀. The only extension item ever registered with IANA, the X#NodeArchitecture key, was specified as a standard key in a Standards Track RFC [RFC4850], so it didn't need the X# prefix. That key is also the only public iSCSI extension registered with IANA since RFC 3720 was originally published, which means the X#, Y#, and Z# public extension formats have basically never been used 💀.
So this document makes these IANA registration changes for iSCSI:
- The separate registries for
X#,Y#, andZ#public extensions are removed. The single entry in the registry forX#login/text keys (X#NodeArchitecture) is moved into the main "iSCSI Login/Text Keys" registry. IANA never created the latter two registries because nobody ever requested a registration for them. These public extension formats (X#,Y#,Z#) MUST NOT be used, with the exception of the existingX#NodeArchitecturekey 🧚. - The registration procedures for the main "iSCSI Login/Text Keys", "iSCSI digests", and "iSCSI authentication methods" IANA registries are changed to IETF Review [RFC5226] for possible future extensions to iSCSI. This includes a deliberate choice to remove the option of specifying an IANA-registered iSCSI extension in an RFC published via an RFC Editor Independent Submission, because the level of review in that process isn't enough for iSCSI extensions 🛑.
- The restriction against registering items using the private extension formats (
X-,Y-,Z-) in the main IANA registries is removed. Extensions using these formats MAY be registered under the IETF Review registration procedures. Each format is still restricted to the type of extension it's specified for in this RFC, and it MUST NOT be used for other types. For example, theX-extension format for extension login/text keys MUST NOT be used for digest algorithms or authentication methods 🌈.
15. IANA Considerations 🦋
The well-known TCP port number for iSCSI connections assigned by IANA is 3260, and that's the default iSCSI port ✨. Implementations that need a system TCP port number may use port 860, which IANA assigned as the iSCSI system port. To use port 860, though, it MUST be explicitly specified. Implementations MUST NOT default to port 860, because 3260 is the only allowed default 🙅♀️.
IANA has replaced the references for ports 860 and 3260, both TCP and UDP, with references to this document. You can check the details at http://www.iana.org/assignments/service-names-port-numbers.
IANA has updated all references to RFC 3720, RFC 4850, and RFC 5048 so they point to this RFC in all of the iSCSI registries that are part of the "Internet Small Computer System Interface (iSCSI) Parameters" set of registries 💖. That change reflects the fact that those three RFCs are obsoleted by this RFC. References to other RFCs that aren't being obsoleted (for example, RFC 3723 and RFC 5046) should not be changed.
IANA has performed these actions on the "iSCSI Login/Text Keys" registry:
- Changed the registration procedure to IETF Review from Standard Required.
- Changed the RFC 5048 reference for the registry to reference this RFC.
- Added the X#NodeArchitecture key from the "iSCSI extended key" registry, and changed its reference to this RFC.
- Changed all references to RFC 3720 and RFC 5048 to instead reference this RFC.
IANA has changed the registration procedures for the "iSCSI authentication methods" and "iSCSI digests" registries to IETF Review from RFC Required 🔥.
IANA has removed the "iSCSI extended key" registry, since its one entry was added to the "iSCSI Login/Text Keys" registry 👋.
IANA has marked the values 4 and 5 as obsolete for SPKM1 and SPKM2, respectively, in the "iSCSI authentication methods" subregistry of the "Internet Small Computer System Interface (iSCSI) Parameters" set of registries 💀.
IANA has added this document to the "iSCSI Protocol Level" registry with value 1, as mentioned in Section 13.24 🌸.
All the other IANA considerations stated in [RFC3720] and [RFC5048] remain unchanged. The assignments in the following subregistries aren't repeated in this document:
- iSCSI authentication methods (from Section 13 of [RFC3720])
- iSCSI digests (from Section 13 of [RFC3720])
This document obsoletes the SPKM1 and SPKM2 key values for the AuthMethod text key. Because of that, the SPKM_ text key prefix MUST be treated as obsolete and MUST NOT be reused 🫶.
16. References 📖
16.1. Normative References 📚
bestie, these are the receipts 🧾 every single one is a doc this spec leans on, so they're listed in full 💅
- [EUI] "Guidelines for 64-bit Global Identifier (EUI-64(TM))",
http://standards.ieee.org/regauth/oui/tutorials/EUI64.html. - [FC-FS3] INCITS Technical Committee T11, "Fibre Channel - Framing and Signaling - 3 (FC-FS-3)", ANSI INCITS 470-2011, 2011.
- [OUI] "IEEE OUI and "company_id" Assignments",
http://standards.ieee.org/regauth/oui. - [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts - Communication Layers", STD 3, RFC 1122, October 1989.
- [RFC1964] Linn, J., "The Kerberos Version 5 GSS-API Mechanism", RFC 1964, June 1996.
- [RFC1982] Elz, R. and R. Bush, "Serial Number Arithmetic", RFC 1982, August 1996.
- [RFC1994] Simpson, W., "PPP Challenge Handshake Authentication Protocol (CHAP)", RFC 1994, August 1996.
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
- [RFC2404] Madson, C. and R. Glenn, "The Use of HMAC-SHA-1-96 within ESP and AH", RFC 2404, November 1998.
- [RFC2406] Kent, S. and R. Atkinson, "IP Encapsulating Security Payload (ESP)", RFC 2406, November 1998.
- [RFC2451] Pereira, R. and R. Adams, "The ESP CBC-Mode Cipher Algorithms", RFC 2451, November 1998.
- [RFC2945] Wu, T., "The SRP Authentication and Key Exchange System", RFC 2945, September 2000.
- [RFC3454] Hoffman, P. and M. Blanchet, "Preparation of Internationalized Strings ("stringprep")", RFC 3454, December 2002.
- [RFC3566] Frankel, S. and H. Herbert, "The AES-XCBC-MAC-96 Algorithm and Its Use With IPsec", RFC 3566, September 2003.
- [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003.
- [RFC3686] Housley, R., "Using Advanced Encryption Standard (AES) Counter Mode With IPsec Encapsulating Security Payload (ESP)", RFC 3686, January 2004.
- [RFC3722] Bakke, M., "String Profile for Internet Small Computer Systems Interface (iSCSI) Names", RFC 3722, April 2004.
- [RFC3723] Aboba, B., Tseng, J., Walker, J., Rangan, V., and F. Travostino, "Securing Block Storage Protocols over IP", RFC 3723, April 2004.
- [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005.
- [RFC4106] Viega, J. and D. McGrew, "The Use of Galois/Counter Mode (GCM) in IPsec Encapsulating Security Payload (ESP)", RFC 4106, June 2005.
- [RFC4120] Neuman, C., Yu, T., Hartman, S., and K. Raeburn, "The Kerberos Network Authentication Service (V5)", RFC 4120, July 2005.
- [RFC4171] Tseng, J., Gibbons, K., Travostino, F., Du Laney, C., and J. Souza, "Internet Storage Name Service (iSNS)", RFC 4171, September 2005.
- [RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing Architecture", RFC 4291, February 2006.
- [RFC4301] Kent, S. and K. Seo, "Security Architecture for the Internet Protocol", RFC 4301, December 2005.
- [RFC4303] Kent, S., "IP Encapsulating Security Payload (ESP)", RFC 4303, December 2005.
- [RFC4304] Kent, S., "Extended Sequence Number (ESN) Addendum to IPsec Domain of Interpretation (DOI) for Internet Security Association and Key Management Protocol (ISAKMP)", RFC 4304, December 2005.
- [RFC4543] McGrew, D. and J. Viega, "The Use of Galois Message Authentication Code (GMAC) in IPsec ESP and AH", RFC 4543, May 2006.
- [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, October 2006.
- [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 5226, May 2008.
- [RFC5996] Kaufman, C., Hoffman, P., Nir, Y., and P. Eronen, "Internet Key Exchange Protocol Version 2 (IKEv2)", RFC 5996, September 2010.
- [RFC6960] Santesson, S., Myers, M., Ankney, R., Malpani, A., Galperin, S., and C. Adams, "X.509 Internet Public Key Infrastructure Online Certificate Status Protocol - OCSP", RFC 6960, June 2013.
- [RFC7144] Knight, F. and M. Chadalapaka, "Internet Small Computer System Interface (iSCSI) SCSI Features Update", RFC 7144, April 2014.
- [RFC7145] Ko, M. and A. Nezhinsky, "Internet Small Computer System Interface (iSCSI) Extensions for the Remote Direct Memory Access (RDMA) Specification", RFC 7145, April 2014.
- [RFC7146] Black, D. and P. Koning, "Securing Block Storage Protocols over IP: RFC 3723 Requirements Update for IPsec v3", RFC 7146, April 2014.
- [SAM2] INCITS Technical Committee T10, "SCSI Architecture Model - 2 (SAM-2)", ANSI INCITS 366-2003, ISO/IEC 14776-412, 2003.
- [SAM4] INCITS Technical Committee T10, "SCSI Architecture Model - 4 (SAM-4)", ANSI INCITS 447-2008, ISO/IEC 14776-414, 2008.
- [SPC2] INCITS Technical Committee T10, "SCSI Primary Commands - 2", ANSI INCITS 351-2001, ISO/IEC 14776-452, 2001.
- [SPC3] INCITS Technical Committee T10, "SCSI Primary Commands - 3", ANSI INCITS 408-2005, ISO/IEC 14776-453, 2005.
- [UML] ISO, "Unified Modeling Language (UML) Version 1.4.2", ISO/IEC 19501:2005.
- [UNICODE] The Unicode Consortium, "Unicode Standard Annex #15: Unicode Normalization Forms", 2013,
http://www.unicode.org/unicode/reports/tr15.
16.2. Informative References 🦋
these ones are the extra reading 📖 handy for context, not required to implement
- [Castagnoli93] Castagnoli, G., Brauer, S., and M. Herrmann, "Optimization of Cyclic Redundancy-Check Codes with 24 and 32 Parity Bits", IEEE Transact. on Communications, Vol. 41, No. 6, June 1993.
- [FC-SP-2] INCITS Technical Committee T11, "Fibre Channel Security Protocols 2", ANSI INCITS 496-2012, 2012.
- [IB] InfiniBand, "InfiniBand(TM) Architecture Specification", Vol. 1, Rel. 1.2.1, InfiniBand Trade Association,
http://www.infinibandta.org. - [RFC1737] Sollins, K. and L. Masinter, "Functional Requirements for Uniform Resource Names", RFC 1737, December 1994.
- [RFC2401] Kent, S. and R. Atkinson, "Security Architecture for the Internet Protocol", RFC 2401, November 1998.
- [RFC2407] Piper, D., "The Internet IP Security Domain of Interpretation for ISAKMP", RFC 2407, November 1998.
- [RFC2409] Harkins, D. and D. Carrel, "The Internet Key Exchange (IKE)", RFC 2409, November 1998.
- [RFC2608] Guttman, E., Perkins, C., Veizades, J., and M. Day, "Service Location Protocol, Version 2", RFC 2608, June 1999.
- [RFC2743] Linn, J., "Generic Security Service Application Program Interface Version 2, Update ", RFC 2743, January 2000.
- [RFC2865] Rigney, C., Willens, S., Rubens, A., and W. Simpson, "Remote Authentication Dial In User Service (RADIUS)", RFC 2865, June 2000.
- [RFC3385] Sheinwald, D., Satran, J., Thaler, P., and V. Cavanna, "Internet Protocol Small Computer System Interface (iSCSI) Cyclic Redundancy Check (CRC)/Checksum Considerations", RFC 3385, September 2002.
- [RFC3602] Frankel, S., Glenn, R., and S. Kelly, "The AES-CBC Cipher Algorithm and Its Use with IPsec", RFC 3602, September 2003.
- [RFC3720] Satran, J., Meth, K., Sapuntzakis, C., Chadalapaka, M., and E. Zeidner, "Internet Small Computer Systems Interface (iSCSI)", RFC 3720, April 2004.
- [RFC3721] Bakke, M., Hafner, J., Hufferd, J., Voruganti, K., and M. Krueger, "Internet Small Computer Systems Interface (iSCSI) Naming and Discovery", RFC 3721, April 2004.
- [RFC3783] Chadalapaka, M. and R. Elliott, "Small Computer Systems Interface (SCSI) Command Ordering Considerations with iSCSI", RFC 3783, May 2004.
- [RFC4121] Zhu, L., Jaganathan, K., and S. Hartman, "The Kerberos Version 5 Generic Security Service Application Program Interface (GSS-API) Mechanism: Version 2", RFC 4121, July 2005.
- [RFC4297] Romanow, A., Mogul, J., Talpey, T., and S. Bailey, "Remote Direct Memory Access (RDMA) over IP Problem Statement", RFC 4297, December 2005.
- [RFC4806] Myers, M. and H. Tschofenig, "Online Certificate Status Protocol (OCSP) Extensions to IKEv2", RFC 4806, February 2007.
- [RFC4850] Wysochanski, D., "Declarative Public Extension Key for Internet Small Computer Systems Interface (iSCSI) Node Architecture", RFC 4850, April 2007.
- [RFC5046] Ko, M., Chadalapaka, M., Hufferd, J., Elzur, U., Shah, H., and P. Thaler, "Internet Small Computer System Interface (iSCSI) Extensions for Remote Direct Memory Access (RDMA)", RFC 5046, October 2007.
- [RFC5048] Chadalapaka, M., Ed., "Internet Small Computer System Interface (iSCSI) Corrections and Clarifications", RFC 5048, October 2007.
- [RFC5433] Clancy, T. and H. Tschofenig, "Extensible Authentication Protocol - Generalized Pre-Shared Key (EAP-GPSK) Method", RFC 5433, February 2009.
- [RFC6648] Saint-Andre, P., Crocker, D., and M. Nottingham, "Deprecating the "X-" Prefix and Similar Constructs in Application Protocols", BCP 178, RFC 6648, June 2012.
- [SAS] INCITS Technical Committee T10, "Serial Attached SCSI - 2.1 (SAS-2.1)", ANSI INCITS 457-2010, 2010.
- [SBC2] INCITS Technical Committee T10, "SCSI Block Commands - 2 (SBC-2)", ANSI INCITS 405-2005, ISO/IEC 14776-322, 2005.
- [SPC4] INCITS Technical Committee T10, "SCSI Primary Commands - 4", ANSI INCITS 513-201x.
- [SPL] INCITS Technical Committee T10, "SAS Protocol Layer - 2 (SPL-2)", ANSI INCITS 505-2013, ISO/IEC 14776-262, 2013.
Appendix A. Examples 🎀
A.1. Read Operation Example 👀
okay this is the read flow, step by step, and it's giving very clean choreography 💃
+------------------+-----------------------+---------------------+
|Initiator Function| PDU Type | Target Function |
+------------------+-----------------------+---------------------+
| Command request |SCSI Command (read)>>> | |
| (read) | | |
+------------------+-----------------------+---------------------+
| | |Prepare Data Transfer|
+------------------+-----------------------+---------------------+
| Receive Data | <<< SCSI Data-In | Send Data |
+------------------+-----------------------+---------------------+
| Receive Data | <<< SCSI Data-In | Send Data |
+------------------+-----------------------+---------------------+
| Receive Data | <<< SCSI Data-In | Send Data |
+------------------+-----------------------+---------------------+
| | <<< SCSI Response |Send Status and Sense|
+------------------+-----------------------+---------------------+
| Command Complete | | |
+------------------+-----------------------+---------------------+the whole thing ends with Command Complete, and that's the main character moment 👑✨
A.2. Write Operation Example ✍️
Okay so here's the write flow as a table, bestie 💅 Read it top to bottom and you'll see the initiator and target taking turns.
+------------------+-----------------------+---------------------+
|Initiator Function| PDU Type | Target Function |
+------------------+-----------------------+---------------------+
| Command request |SCSI Command (write)>>>| Receive command |
| (write) | | and queue it |
+------------------+-----------------------+---------------------+
| | | Process old commands|
+------------------+-----------------------+---------------------+
| | | Ready to process |
| | <<< R2T | write command |
+------------------+-----------------------+---------------------+
| Send Data | SCSI Data-Out >>> | Receive Data |
+------------------+-----------------------+---------------------+
| | <<< R2T | Ready for data |
+------------------+-----------------------+---------------------+
| | <<< R2T | Ready for data |
+------------------+-----------------------+---------------------+
| Send Data | SCSI Data-Out >>> | Receive Data |
+------------------+-----------------------+---------------------+
| Send Data | SCSI Data-Out >>> | Receive Data |
+------------------+-----------------------+---------------------+
| | <<< SCSI Response |Send Status and Sense|
+------------------+-----------------------+---------------------+
| Command Complete | | |
+------------------+-----------------------+---------------------+A.3. R2TSN/DataSN Use Examples 🎀
Three little scenarios coming up, each one showing how the sequence numbers keep everything in order. So cute 🧚
A.3.1. Output (Write) Data DataSN/R2TSN Example 🌸
+-------------------+------------------------+---------------------+
|Initiator Function | PDU Type and Content | Target Function |
+-------------------+------------------------+---------------------+
| Command request |SCSI Command (write)>>> | Receive command |
| (write) | | and queue it |
+-------------------+------------------------+---------------------+
| | | Process old commands|
+-------------------+------------------------+---------------------+
| | <<< R2T | Ready for data |
| | R2TSN = 0 | |
+-------------------+------------------------+---------------------+
| | <<< R2T | Ready for more data |
| | R2TSN = 1 | |
+-------------------+------------------------+---------------------+
| Send Data | SCSI Data-Out >>> | Receive Data |
| for R2TSN 0 | DataSN = 0, F = 0 | |
+-------------------+------------------------+---------------------+
| Send Data | SCSI Data-Out >>> | Receive Data |
| for R2TSN 0 | DataSN = 1, F = 1 | |
+-------------------+------------------------+---------------------+
| Send Data | SCSI Data >>> | Receive Data |
| for R2TSN 1 | DataSN = 0, F = 1 | |
+-------------------+------------------------+---------------------+
| | <<< SCSI Response |Send Status and Sense|
| | ExpDataSN = 0 | |
+-------------------+------------------------+---------------------+
| Command Complete | | |
+-------------------+------------------------+---------------------+A.3.2. Input (Read) Data DataSN Example 🦋
+------------------+-----------------------+----------------------+
|Initiator Function| PDU Type | Target Function |
+------------------+-----------------------+----------------------+
| Command request |SCSI Command (read)>>> | |
| (read) | | |
+------------------+-----------------------+----------------------+
| | |Prepare Data Transfer |
+------------------+-----------------------+----------------------+
| Receive Data | <<< SCSI Data-In | Send Data |
| | DataSN = 0, F = 0 | |
+------------------+-----------------------+----------------------+
| Receive Data | <<< SCSI Data-In | Send Data |
| | DataSN = 1, F = 0 | |
+------------------+-----------------------+----------------------+
| Receive Data | <<< SCSI Data-In | Send Data |
| | DataSN = 2, F = 1 | |
+------------------+-----------------------+----------------------+
| | <<< SCSI Response |Send Status and Sense |
| | ExpDataSN = 3 | |
+------------------+-----------------------+----------------------+
| Command Complete | | |
+------------------+-----------------------+----------------------+A.3.3. Bidirectional DataSN Example 💜
+------------------+-----------------------+---------------------+
|Initiator Function| PDU Type | Target Function |
+------------------+-----------------------+---------------------+
| Command request |SCSI Command >>> | |
| (Read-Write) | Read-Write | |
+------------------+-----------------------+---------------------+
| | | Process old commands|
+------------------+-----------------------+---------------------+
| | <<< R2T | Ready to process |
| | R2TSN = 0 | write command |
+------------------+-----------------------+---------------------+
| * Receive Data | <<< SCSI Data-In | Send Data |
| | DataSN = 0, F = 0 | |
+------------------+-----------------------+---------------------+
| * Receive Data | <<< SCSI Data-In | Send Data |
| | DataSN = 1, F = 1 | |
+------------------+-----------------------+---------------------+
| * Send Data | SCSI Data-Out >>> | Receive Data |
| for R2TSN 0 | DataSN = 0, F = 1 | |
+------------------+-----------------------+---------------------+
| | <<< SCSI Response |Send Status and Sense|
| | ExpDataSN = 2 | |
+------------------+-----------------------+---------------------+
| Command Complete | | |
+------------------+-----------------------+---------------------+
* Send Data and Receive Data may be transferred simultaneously as in
an atomic Read-Old-Write-New or sequentially as in an atomic
Read-Update-Write (in the latter case, the R2T may follow the
received data).Quick aside: the asterisked rows are the Send Data and Receive Data pieces. They can happen at the same time (that's the atomic Read-Old-Write-New vibe) or one after the other (atomic Read-Update-Write), and in that second case the R2T can come after the received data. Iconic flexibility 🔥
A.3.4. Unsolicited and Immediate Output (Write) Data with DataSN Example 🍓
+------------------+------------------------+----------------------+
|Initiator Function| PDU Type and Content | Target Function |
+------------------+------------------------+----------------------+
| Command request |SCSI Command (write)>>> | Receive command |
| (write) |F = 0 | and data |
|+ immediate data | | and queue it |
+------------------+------------------------+----------------------+
| Send Unsolicited | SCSI Write Data >>> | Receive more Data |
| Data | DataSN = 0, F = 1 | |
+------------------+------------------------+----------------------+
| | | Process old commands |
+------------------+------------------------+----------------------+
| | <<< R2T | Ready for more data |
| | R2TSN = 0 | |
+------------------+------------------------+----------------------+
| Send Data | SCSI Write Data >>> | Receive Data |
| for R2TSN 0 | DataSN = 0, F = 1 | |
+------------------+------------------------+----------------------+
| | <<< SCSI Response |Send Status and Sense |
| | | |
+------------------+------------------------+----------------------+
| Command Complete | | |
+------------------+------------------------+----------------------+A.4. CRC Examples 🧮
Note: All values are hexadecimal. Lowkey the most satisfying part of the whole doc 🫶
32 bytes of zeroes:
Byte: 0 1 2 3
0: 00 00 00 00
...
28: 00 00 00 00
CRC: aa 36 91 8a32 bytes of ones:
Byte: 0 1 2 3
0: ff ff ff ff
...
28: ff ff ff ff
CRC: 43 ab a8 6232 bytes of incrementing 00..1f:
Byte: 0 1 2 3
0: 00 01 02 03
...
28: 1c 1d 1e 1f
CRC: 4e 79 dd 4632 bytes of decrementing 1f..00:
Byte: 0 1 2 3
0: 1f 1e 1d 1c
...
28: 03 02 01 00
CRC: 5c db 3f 11An iSCSI - SCSI Read (10) Command PDU, which is giving main character energy 👑:
Byte: 0 1 2 3
0: 01 c0 00 00
4: 00 00 00 00
8: 00 00 00 00
12: 00 00 00 00
16: 14 00 00 00
20: 00 00 04 00
24: 00 00 00 14
28: 00 00 00 18
32: 28 00 00 00
36: 00 00 00 00
40: 02 00 00 00
44: 00 00 00 00
CRC: 56 3a 96 d9Appendix B. Login Phase Examples ✨
okay bestie, let's look at some login phase examples 💅 each one shows a different way the initiator and target can do the security handshake 🫶
In the first example, the initiator and target authenticate each other with Kerberos 🔐
I-> Login (CSG,NSG=0,1 T=1)
InitiatorName=iqn.1999-07.com.os:hostid.77
TargetName=iqn.1999-07.com.example:diskarray.sn.88
AuthMethod=KRB5,SRP,None
T-> Login (CSG,NSG=0,0 T=0)
AuthMethod=KRB5
I-> Login (CSG,NSG=0,1 T=1)
KRB_AP_REQ=<krb_ap_req>(krb_ap_req holds the Kerberos V5 ticket and authenticator, with MUTUAL-REQUIRED set in the ap-options field 🎀)
If the authentication works out, the target carries on with:
T-> Login (CSG,NSG=0,1 T=1)
KRB_AP_REP=<krb_ap_rep>(krb_ap_rep is the Kerberos V5 mutual authentication reply 🌸)
If that also goes through, the initiator can move on with:
I-> Login (CSG,NSG=1,0 T=0) FirstBurstLength=8192
T-> Login (CSG,NSG=1,0 T=0) FirstBurstLength=4096
MaxBurstLength=8192
I-> Login (CSG,NSG=1,0 T=0) MaxBurstLength=8192
... more iSCSI Operational Parameters
T-> Login (CSG,NSG=1,0 T=0)
... more iSCSI Operational Parameters
And at the end:
I-> Login (CSG,NSG=1,3 T=1)
optional iSCSI parameters
T-> Login (CSG,NSG=1,3 T=1) "login accept"If the target fails to authenticate the initiator, the target responds with:
T-> Login "login reject"instead of the Login KRB_AP_REP message, and then it terminates the connection 💀
If the initiator fails to authenticate the target, the initiator terminates the connection (without responding to the Login KRB_AP_REP message) 🙈
Next up, only the initiator gets authenticated by the target, via Kerberos 🧚
I-> Login (CSG,NSG=0,1 T=1)
InitiatorName=iqn.1999-07.com.os:hostid.77
TargetName=iqn.1999-07.com.example:diskarray.sn.88
AuthMethod=SRP,KRB5,None
T-> Login-PR (CSG,NSG=0,0 T=0)
AuthMethod=KRB5
I-> Login (CSG,NSG=0,1 T=1)
KRB_AP_REQ=krb_ap_req(MUTUAL-REQUIRED is not set in the ap-options field of krb_ap_req 👀)
If the authentication succeeds, the target proceeds with:
T-> Login (CSG,NSG=0,1 T=1)
I-> Login (CSG,NSG=1,0 T=0)
... iSCSI parameters
T-> Login (CSG,NSG=1,0 T=0)
... iSCSI parameters
. . .
T-> Login (CSG,NSG=1,3 T=1)"login accept"Now the initiator and target authenticate each other with SRP 🦋
I-> Login (CSG,NSG=0,1 T=1)
InitiatorName=iqn.1999-07.com.os:hostid.77
TargetName=iqn.1999-07.com.example:diskarray.sn.88
AuthMethod=KRB5,SRP,None
T-> Login-PR (CSG,NSG=0,0 T=0)
AuthMethod=SRP
I-> Login (CSG,NSG=0,0 T=0)
SRP_U=<user>
TargetAuth=Yes
T-> Login (CSG,NSG=0,0 T=0)
SRP_N=<N>
SRP_g=<g>
SRP_s=<s>
I-> Login (CSG,NSG=0,0 T=0)
SRP_A=<A>
T-> Login (CSG,NSG=0,0 T=0)
SRP_B=<B>
I-> Login (CSG,NSG=0,1 T=1)
SRP_M=<M>If the initiator authentication succeeds, the target proceeds with:
T-> Login (CSG,NSG=0,1 T=1)
SRP_HM=<H(A | M | K)>where N, g, s, A, B, M, and H(A | M | K) are defined in [RFC2945] 📚
If the target authentication doesn't work out, the initiator terminates the connection. Otherwise, it keeps going 💪
I-> Login (CSG,NSG=1,0 T=0)
... iSCSI parameters
T-> Login (CSG,NSG=1,0 T=0)
... iSCSI parameters
And at the end:
I-> Login (CSG,NSG=1,3 T=1)
optional iSCSI parameters
T-> Login (CSG,NSG=1,3 T=1) "login accept"If the initiator authentication fails, the target responds with:
T-> Login "login reject"instead of the T-> Login SRP_HM=<H(A | M | K)> message, and it terminates the connection 💔
In this one, only the initiator is authenticated by the target, via SRP 🌈
I-> Login (CSG,NSG=0,1 T=1)
InitiatorName=iqn.1999-07.com.os:hostid.77
TargetName=iqn.1999-07.com.example:diskarray.sn.88
AuthMethod=KRB5,SRP,None
T-> Login-PR (CSG,NSG=0,0 T=0)
AuthMethod=SRP
I-> Login (CSG,NSG=0,0 T=0)
SRP_U=<user>
TargetAuth=No
T-> Login (CSG,NSG=0,0 T=0)
SRP_N=<N>
SRP_g=<g>
SRP_s=<s>
I-> Login (CSG,NSG=0,0 T=0)
SRP_A=<A>
T-> Login (CSG,NSG=0,0 T=0)
SRP_B=<B>
I-> Login (CSG,NSG=0,1 T=1)
SRP_M=<M>If the initiator authentication succeeds, the target proceeds with:
T-> Login (CSG,NSG=0,1 T=1)
I-> Login (CSG,NSG=1,0 T=0)
... iSCSI parameters
T-> Login (CSG,NSG=1,0 T=0)
... iSCSI parameters
And at the end:
I-> Login (CSG,NSG=1,3 T=1)
optional iSCSI parameters
T-> Login (CSG,NSG=1,3 T=1) "login accept"Next, the initiator and target authenticate each other with CHAP 🎀
I-> Login (CSG,NSG=0,0 T=0)
InitiatorName=iqn.1999-07.com.os:hostid.77
TargetName=iqn.1999-07.com.example:diskarray.sn.88
AuthMethod=KRB5,CHAP,None
T-> Login-PR (CSG,NSG=0,0 T=0)
AuthMethod=CHAP
I-> Login (CSG,NSG=0,0 T=0)
CHAP_A=<A1,A2>
T-> Login (CSG,NSG=0,0 T=0)
CHAP_A=<A1>
CHAP_I=<I>
CHAP_C=<C>
I-> Login (CSG,NSG=0,1 T=1)
CHAP_N=<N>
CHAP_R=<R>
CHAP_I=<I>
CHAP_C=<C>If the initiator authentication succeeds, the target proceeds with:
T-> Login (CSG,NSG=0,1 T=1)
CHAP_N=<N>
CHAP_R=<R>If the target authentication fails, the initiator aborts the connection. Otherwise, it proceeds 🫣
I-> Login (CSG,NSG=1,0 T=0)
... iSCSI parameters
T-> Login (CSG,NSG=1,0 T=0)
... iSCSI parameters
And at the end:
I-> Login (CSG,NSG=1,3 T=1)
optional iSCSI parameters
T-> Login (CSG,NSG=1,3 T=1) "login accept"If the initiator authentication fails, the target responds with:
T-> Login "login reject"instead of the Login CHAP_R=<response> "proceed and change stage" message, and it terminates the connection 🥀
In this next one, only the initiator is authenticated by the target, via CHAP ✨
I-> Login (CSG,NSG=0,1 T=0)
InitiatorName=iqn.1999-07.com.os:hostid.77
TargetName=iqn.1999-07.com.example:diskarray.sn.88
AuthMethod=KRB5,CHAP,None
T-> Login-PR (CSG,NSG=0,0 T=0)
AuthMethod=CHAP
I-> Login (CSG,NSG=0,0 T=0)
CHAP_A=<A1,A2>
T-> Login (CSG,NSG=0,0 T=0)
CHAP_A=<A1>
CHAP_I=<I>
CHAP_C=<C>
I-> Login (CSG,NSG=0,1 T=1)
CHAP_N=<N>
CHAP_R=<R>If the initiator authentication succeeds, the target proceeds with:
T-> Login (CSG,NSG=0,1 T=1)
I-> Login (CSG,NSG=1,0 T=0)
... iSCSI parameters
T-> Login (CSG,NSG=1,0 T=0)
... iSCSI parameters
And at the end:
I-> Login (CSG,NSG=1,3 T=1)
optional iSCSI parameters
T-> Login (CSG,NSG=1,3 T=1) "login accept"Here the initiator doesn't offer any security parameters 🌸 So it can send iSCSI parameters on the Login PDU with the T bit set to 1, and the target can answer with a final Login Response PDU right away:
I-> Login (CSG,NSG=1,3 T=1)
InitiatorName=iqn.1999-07.com.os:hostid.77
TargetName=iqn.1999-07.com.example:diskarray.sn.88
... iSCSI parameters
T-> Login (CSG,NSG=1,3 T=1) "login accept"
... ISCSI parametersLast one! Here the initiator does offer security parameters on the Login PDU, but the target doesn't pick any of them (it chooses the "None" values) 🙃
I-> Login (CSG,NSG=0,1 T=1)
InitiatorName=iqn.1999-07.com.os:hostid.77
TargetName=iqn.1999-07.com.example:diskarray.sn.88
AuthMethod=KRB5,SRP,None
T-> Login-PR (CSG,NSG=0,1 T=1)
AuthMethod=None
I-> Login (CSG,NSG=1,0 T=0)
... iSCSI parameters
T-> Login (CSG,NSG=1,0 T=0)
... iSCSI parameters
And at the end:
I-> Login (CSG,NSG=1,3 T=1)
optional iSCSI parameters
T-> Login (CSG,NSG=1,3 T=1) "login accept"Appendix C. SendTargets Operation 🎀
The text in this appendix is a normative part of this document, so this is official, no cap 📜✨
Okay so, to make setup easier for an initiator, iSCSI gives you the SendTargets Text Request 🧚 The initiator uses SendTargets to ask for a list of targets it might be able to access, plus the list of addresses (IP address and TCP port) where those targets can be reached 💖
To use SendTargets, an initiator has to start one of two kinds of sessions first. If the initiator starts the session with the key SessionType=Discovery, that's a Discovery session, and you don't have to specify a target name 🦋 Otherwise it's a Normal operational session. The SendTargets command MUST only be sent during the Full Feature Phase of a Normal or Discovery session 💅
A system with targets MUST support Discovery sessions on each of its iSCSI IP address-port pairs, and it MUST support the SendTargets command on the Discovery session 🔥 In a Discovery session, a target MUST return all path information (IP address-port pairs and Target Portal Group Tags) for the targets on the target Network Entity that the requesting initiator is authorized to access. Main character energy for sure 👑
A target MUST support the SendTargets command on operational sessions too. These only return path information about the target the session is connected to, so they don't have to tell you about other target names defined on the responding system 🌸
An initiator MAY use the SendTargets command however it sees fit 🫶
A SendTargets command is a single Text Request PDU. That PDU has exactly one text key and value. The text key MUST be SendTargets. What you get back depends on the value, and also on whether the session is a Discovery session or an operational one 🍓
The value has to be one of these:
All
<iSCSI-target-name>
<nothing>Here's the breakdown, bestie:
All: The initiator wants info on all the relevant targets the implementation knows about. This value MUST be supported on a Discovery session and MUST NOT be supported on an operational session 😭<iSCSI-target-name>: If you specify an iSCSI Target Name, the session should give back addresses for just that named target, if possible. This value MUST be supported on Discovery sessions. A Discovery session MUST be capable of returning addresses for those targets that would have come back if value=All had been used 💜<nothing>: The session should only give back addresses for the target it's logged in to. This MUST be supported on operational sessions and MUST NOT return targets other than the one the session is logged in to 🙈
The response is a Text Response with a list of zero or more targets and, optionally, their addresses. Each target comes back as a target record. A target record begins with the TargetName text key, followed by a list of TargetAddress text keys, and it ends at the end of the Text Response or at the next TargetName key, which starts a new record. No text keys other than TargetName and TargetAddress are permitted within a SendTargets response. Strict, but iconic 💀
For the format of the TargetName, see Section 13.4 🦋
A Discovery session MAY respond to a SendTargets request with its complete list of targets, or with a list that's based on the name of the initiator logged in to the session ✨
A SendTargets response MUST NOT contain target names if there are no targets for the requesting initiator to access 🙅♀️
Each target record can include zero or more TargetAddress fields 🎀
Every target record starts with one text key in this form:
TargetName=<target-name-goes-here>Then comes zero or more address keys in this form:
TargetAddress=<hostname-or-ipaddress>[:<tcp-port>],
<portal-group-tag>The hostname-or-ipaddress is a domain name, an IPv4 address, or an IPv6 address ([RFC4291]), as specified for the TargetAddress key 🧚
If the same hostname-or-ipaddress shows up in TargetAddress responses for a given node (with the port absent or the same), that would probably mean multiple address families are being used at once (IPv6 and IPv4) 🌈
Each TargetAddress belongs to a portal group, identified by its numeric Target Portal Group Tag (see Section 13.9). The iSCSI Target Name, together with this tag, makes up the SCSI port identifier. The tag only has to be unique within a given target's name list of addresses 💖
Multiple-connection sessions can span iSCSI addresses that belong to the same portal group 🫶
Multiple-connection sessions cannot span iSCSI addresses that belong to different portal groups 🙅♀️
If a SendTargets response reports an iSCSI address for a target, it SHOULD also report all the other addresses in its portal group in that same response 🔥
A SendTargets Text Response can be longer than a single Text Response PDU, and it uses the long Text Responses as specified 🌸
After getting a list of targets from the Discovery session, an iSCSI initiator can start new sessions to log in to the discovered targets for full operation. The initiator MAY keep the Discovery session open and MAY send later SendTargets commands to discover new targets 🦋
Examples:
This example is the SendTargets response from a single target with no other interface ports ✨
The initiator sends a Text Request that contains:
SendTargets=AllThe target sends a Text Response that contains:
TargetName=iqn.1993-11.com.example:diskarray.sn.8675309In this simple case, all the target had to return was the target name. The initiator assumes that the IP address and TCP port for this target are the same as the ones used on the current connection to the default iSCSI target 💅
The next example has two internal iSCSI targets, each reachable through two different ports with different IP addresses. Here's the Text Response:
TargetName=iqn.1993-11.com.example:diskarray.sn.8675309
TargetAddress=10.1.0.45:3000,1
TargetAddress=10.1.1.45:3000,2
TargetName=iqn.1993-11.com.example:diskarray.sn.1234567
TargetAddress=10.1.0.45:3000,1
TargetAddress=10.1.1.45:3000,2Both targets share both addresses, and the multiple addresses are probably there for multi-path support 🛤️ The initiator can connect to either target name on either address. Each address has its own Target Portal Group Tag, and they don't support spanning multiple-connection sessions with each other. Keep in mind that the Target Portal Group Tags for the two named targets are independent of each other. Portal group "1" on the first target is not necessarily the same as portal group "1" on the second target 🎀
In the example above, a DNS host name or an IPv6 address could have been returned instead of an IPv4 address 🧚
The next Text Response shows a target that supports sessions spanning multiple addresses, and it shows more about how Target Portal Group Tags work 👑
TargetName=iqn.1993-11.com.example:diskarray.sn.8675309
TargetAddress=10.1.0.45:3000,1
TargetAddress=10.1.1.46:3000,1
TargetAddress=10.1.0.47:3000,2
TargetAddress=10.1.1.48:3000,2
TargetAddress=10.1.1.49:3000,3In this example, any of the target addresses can be used to reach the same target. A single-connection session can be set up to any of these TCP addresses. A multiple-connection session could span addresses .45 and .46, or .47 and .48, but it can't span any other combination. The TargetAddress with its own tag (.49) can't be combined with any other address in the same session 🙈
This SendTargets response doesn't say whether .49 supports multiple connections per session. That's communicated through the MaxConnections text key when you log in to the target 💜
Appendix D. Algorithmic Presentation of Error Recovery Classes 🦋
This appendix illustrates the error recovery classes using a pseudo-programming language. The procedure names are picked to be obvious to most implementers 🍓 Each of the recovery classes has initiator procedures as well as target procedures. These algorithms focus on the mechanics of the error recovery classes and don't exhaustively describe every other aspect or case. Some examples of this approach:
- Handling for only certain Opcode types is shown.
- Only certain reason codes (e.g., Recovery in Logout command) are outlined.
- Resultant cases, such as recovery of Synchronization on a header digest error, are considered out of scope in these algorithms. In this particular example, a header digest error may lead to connection recovery if some type of Sync and Steering layer is not implemented.
These algorithms try to convey the iSCSI error recovery concepts in the simplest terms, and they aren't designed to be optimal 💅✨
D.1. General Data Structure and Procedure Description 🧚
This section defines the procedures and data structures that all the error recovery algorithms commonly use. The structures may not be the exhaustive representations of what a typical implementation requires 🌸
Data structure definitions:
struct TransferContext {
int TargetTransferTag;
int ExpectedDataSN;
};
struct TCB { /* task control block */
Boolean SoFarInOrder;
int ExpectedDataSN; /* used for both R2Ts and Data */
int MissingDataSNList[MaxMissingDPDU];
Boolean FbitReceived;
Boolean StatusXferd;
Boolean CurrentlyAllegiant;
int ActiveR2Ts;
int Response;
char *Reason;
struct TransferContext
TransferContextList[MaxOutstandingR2T];
int InitiatorTaskTag;
int CmdSN;
int SNACK_Tag;
};
struct Connection {
struct Session SessionReference;
Boolean SoFarInOrder;
int CID;
int State;
int CurrentTimeout;
int ExpectedStatSN;
int MissingStatSNList[MaxMissingSPDU];
Boolean PerformConnectionCleanup;
};
struct Session {
int NumConnections;
int CmdSN;
int Maxconnections;
int ErrorRecoveryLevel;
struct iSCSIEndpoint OtherEndInfo;
struct Connection ConnectionList[MaxSupportedConns];
};Procedure descriptions:
Receive-an-In-PDU(transport connection, inbound PDU);
check-basic-validity(inbound PDU);
Start-Timer(timeout handler, argument, timeout value);
Build-And-Send-Reject(transport connection, bad PDU, reason code);D.2. Within-command Error Recovery Algorithms ✨
D.2.1. Procedure Descriptions ✨
okay so this is the cast list for the within-command recovery party 💅 each one is a little helper that does one job, and the code below is verbatim so you can see exactly how they're named:
Recover-Data-if-Possible(last required DataSN, task control block);
Build-And-Send-DSnack(task control block);
Build-And-Send-RDSnack(task control block);
Build-And-Send-Abort(task control block);
SCSI-Task-Completion(task control block);
Build-And-Send-A-Data-Burst(transport connection, data-descriptor,
task control block);
Build-And-Send-R2T(transport connection, data-descriptor,
task control block);
Build-And-Send-Status(transport connection, task control block);
Transfer-Context-Timeout-Handler(transfer context);Notes:
- 🫶 one procedure we use here isn't defined in this section, it's
Handle-Status-SNACK-request, and you'll find it hanging out in Appendix D.3 🦋 - 💖 the response-processing pseudocode from the target algorithms covers every solicited PDU that carries the StatSN, so that includes the SCSI Response, the Text Response, and friends. it's giving consistency ✨
D.2.2. Initiator Algorithms
bestie, this is where the initiator gets to be the main character 👑 the pseudocode is copied exactly, so the weird spacing and the little typos stay right where they are:
Recover-Data-if-Possible(LastRequiredDataSN, TCB)
{
if (operational ErrorRecoveryLevel > 0) {
if (# of missing PDUs is trackable) {
Note the missing DataSNs in TCB.
if (the task spanned a change in
MaxRecvDataSegmentLength) {
if (TCB.StatusXferd is TRUE)
drop the status PDU;
Build-And-Send-RDSnack(TCB);
} else {
Build-And-Send-DSnack(TCB);
}
} else {
TCB.Reason = "Protocol Service CRC error";
}
} else {
TCB.Reason = "Protocol Service CRC error";
}
if (TCB.Reason == "Protocol Service CRC error") {
Clear the missing PDU list in the TCB.
if (TCB.StatusXferd is not TRUE)
Build-And-Send-Abort(TCB);
}
}
Receive-an-In-PDU(Connection, CurrentPDU)
{
check-basic-validity(CurrentPDU);
if (Header-Digest-Bad) discard, return;
Retrieve TCB for CurrentPDU.InitiatorTaskTag.
if ((CurrentPDU.type == Data)
or (CurrentPDU.type = R2T)) {
if (Data-Digest-Bad for Data) {
send-data-SNACK = TRUE;
LastRequiredDataSN = CurrentPDU.DataSN;
} else {
if (TCB.SoFarInOrder = TRUE) {
if (current DataSN is expected) {
Increment TCB.ExpectedDataSN.
} else {
TCB.SoFarInOrder = FALSE;
send-data-SNACK = TRUE;
}
} else {
if (current DataSN was considered missing) {
remove current DataSN from missing PDU list.
} else if (current DataSN is higher than expected) {
send-data-SNACK = TRUE;
} else {
discard, return;
}
Adjust TCB.ExpectedDataSN if appropriate.
}
LastRequiredDataSN = CurrentPDU.DataSN - 1;
}
if (send-data-SNACK is TRUE and
task is not already considered failed) {
Recover-Data-if-Possible(LastRequiredDataSN, TCB);
}
if (missing data PDU list is empty) {
TCB.SoFarInOrder = TRUE;
}
if (CurrentPDU.type == R2T) {
Increment ActiveR2Ts for this task.
Create a data-descriptor for the data burst.
Build-And-Send-A-Data-Burst(Connection, data-descriptor, TCB);
}
} else if (CurrentPDU.type == Response) {
if (Data-Digest-Bad) {
send-status-SNACK = TRUE;
} else {
TCB.StatusXferd = TRUE;
Store the status information in TCB.
if (ExpDataSN does not match) {
TCB.SoFarInOrder = FALSE;
Recover-Data-if-Possible(current DataSN, TCB);
}
if (missing data PDU list is empty) {
TCB.SoFarInOrder = TRUE;
}
}
} else { /* REST UNRELATED TO WITHIN-COMMAND-RECOVERY, NOT SHOWN */
}
if ((TCB.SoFarInOrder == TRUE) and
(TCB.StatusXferd == TRUE)) {
SCSI-Task-Completion(TCB);
}
}D.2.3. Target Algorithms
and now the target's turn to shine 🎀 same deal here, every line is copied exactly as written:
Receive-an-In-PDU(Connection, CurrentPDU)
{
check-basic-validity(CurrentPDU);
if (Header-Digest-Bad) discard, return;
Retrieve TCB for CurrentPDU.InitiatorTaskTag.
if (CurrentPDU.type == Data) {
Retrieve TContext from CurrentPDU.TargetTransferTag;
if (Data-Digest-Bad) {
Build-And-Send-Reject(Connection, CurrentPDU,
Payload-Digest-Error);
Note the missing data PDUs in MissingDataRange[].
send-recovery-R2T = TRUE;
} else {
if (current DataSN is not expected) {
Note the missing data PDUs in MissingDataRange[].
send-recovery-R2T = TRUE;
}
if (CurrentPDU.Fbit == TRUE) {
if (current PDU is solicited) {
Decrement TCB.ActiveR2Ts.
}
if ((current PDU is unsolicited and
data received is less than I/O length and
data received is less than FirstBurstLength)
or (current PDU is solicited and the length of
this burst is less than expected)) {
send-recovery-R2T = TRUE;
Note the missing data in MissingDataRange[].
}
}
}
Increment TContext.ExpectedDataSN.
if (send-recovery-R2T is TRUE and
task is not already considered failed) {
if (operational ErrorRecoveryLevel > 0) {
Increment TCB.ActiveR2Ts.
Create a data-descriptor for the data burst
from MissingDataRange.
Build-And-Send-R2T(Connection, data-descriptor, TCB);
} else {
if (current PDU is the last unsolicited)
TCB.Reason = "Not enough unsolicited data";
else
TCB.Reason = "Protocol Service CRC error";
}
}
if (TCB.ActiveR2Ts == 0) {
Build-And-Send-Status(Connection, TCB);
}
} else if (CurrentPDU.type == SNACK) {
snack-failure = FALSE;
if (operational ErrorRecoveryLevel > 0) {
if (CurrentPDU.type == Data/R2T) {
if (the request is satisfiable) {
if (request for Data) {
Create a data-descriptor for the data burst
from BegRun and RunLength.
Build-And-Send-A-Data-Burst(Connection,
data-descriptor, TCB);
} else { /* R2T */
Create a data-descriptor for the data burst
from BegRun and RunLength.
Build-And-Send-R2T(Connection, data-descriptor,
TCB);
}
} else {
snack-failure = TRUE;
}
} else if (CurrentPDU.type == status) {
Handle-Status-SNACK-request(Connection, CurrentPDU);
} else if (CurrentPDU.type == DataACK) {
Consider all data up to CurrentPDU.BegRun as
acknowledged.
Free up the retransmission resources for that data.
} else if (CurrentPDU.type == R-Data SNACK) {
Create a data descriptor for a data burst
covering all unacknowledged data.
Build-And-Send-A-Data-Burst(Connection,
data-descriptor, TCB);
TCB.SNACK_Tag = CurrentPDU.SNACK_Tag;
if (there's no more data to send) {
Build-And-Send-Status(Connection, TCB);
}
}
} else { /* operational ErrorRecoveryLevel = 0 */
snack-failure = TRUE;
}
if (snack-failure == TRUE) {
Build-And-Send-Reject(Connection, CurrentPDU,
SNACK-Reject);
if (TCB.StatusXferd != TRUE) {
TCB.Reason = "SNACK rejected";
Build-And-Send-Status(Connection, TCB);
}
}
} else { /* REST UNRELATED TO WITHIN-COMMAND-RECOVERY, NOT SHOWN */
}
}
Transfer-Context-Timeout-Handler(TContext)
{
Retrieve TCB and Connection from TContext.
Decrement TCB.ActiveR2Ts.
if (operational ErrorRecoveryLevel > 0 and
task is not already considered failed) {
Note the missing data PDUs in MissingDataRange[].
Create a data-descriptor for the data burst
from MissingDataRange[].
Build-And-Send-R2T(Connection, data-descriptor, TCB);
} else {
TCB.Reason = "Protocol Service CRC error";
if (TCB.ActiveR2Ts = 0) {
Build-And-Send-Status(Connection, TCB);
}
}
}D.3. Within-connection Recovery Algorithms 🌈
D.3.1. Procedure Descriptions
okay, this is the within-connection squad 🧚 here are the procedure names, copied exactly:
Procedure descriptions:
Recover-Status-if-Possible(transport connection,
currently received PDU);
Evaluate-a-StatSN(transport connection, currently received PDU);
Retransmit-Command-if-Possible(transport connection, CmdSN);
Build-And-Send-SSnack(transport connection);
Build-And-Send-Command(transport connection,
task control block);
Command-Acknowledge-Timeout-Handler(task control block);
Status-Expect-Timeout-Handler(transport connection);
Build-And-Send-NOP-Out(transport connection);
Handle-Status-SNACK-request(transport connection,
Status SNACK PDU);
Retransmit-Status-Burst(Status SNACK, task control block);
Is-Acknowledged(beginning StatSN, run length);
Implementation-specific parameters that are tunable:
InitiatorProactiveSNACKEnabledNotes:
- 🦋 the initiator algorithms only deal with unsolicited NOP-In PDUs when they're generating Status SNACKs. a solicited NOP-In PDU does have an assigned StatSN, though, and if it shows up out of order it can kick off the out-of-order StatSN handling in the within-command algorithms, which then leads to
Recover-Status-if-Possible💅 - 🍓 the pseudocode might retransmit unacknowledged commands in more cases than it needs to, but that's not a correctness problem, because the target is required to discard the duplicate CmdSNs ✨
- 🌸 the procedure
Build-And-Send-Asyncis defined in the connection recovery algorithms, so go check there if you're looking for it 🫶 - 💜
Status-Expect-Timeout-Handlerdescribes how initiators can proactively try to get the Status if they want to. it's assumed to be triggered well before the standard ULP timeout, so it's like an early warning system, lowkey iconic 😭
D.3.2. Initiator Algorithms ✨
okay bestie, this is the initiator's side of the within-connection recovery stuff 💅 it's giving detective energy, because every branch is about spotting a missing StatSN or a bad digest and deciding what to do next 🔍
Here's the first one, where the initiator tries to recover status if it can 🫶
Recover-Status-if-Possible(Connection, CurrentPDU)
{
if ((Connection.state == LOGGED_IN) and
connection is not already considered failed) {
if (operational ErrorRecoveryLevel > 0) {
if (# of missing PDUs is trackable) {
Note the missing StatSNs in Connection
that were not already requested with SNACK;
Build-And-Send-SSnack(Connection);
} else {
Connection.PerformConnectionCleanup = TRUE;
}
} else {
Connection.PerformConnectionCleanup = TRUE;
}
if (Connection.PerformConnectionCleanup == TRUE) {
Start-Timer(Connection-Cleanup-Handler, Connection, 0);
}
}
}so the vibe is: if you're logged in and the connection isn't already considered failed 🌸 and your operational ErrorRecoveryLevel is above 0, you either note the missing StatSNs you haven't asked for yet and send a SNACK, or, if you can't track them, you flag the connection for cleanup ✨ if the level is 0, cleanup is the only move 💀 and whenever cleanup is flagged, the timer goes off right away 🦋
Next up is retransmitting the command, which is only a thing if the ErrorRecoveryLevel is above 0 🎀
Retransmit-Command-if-Possible(Connection, CmdSN)
{
if (operational ErrorRecoveryLevel > 0) {
Retrieve the InitiatorTaskTag, and thus TCB for the CmdSN.
Build-And-Send-Command(Connection, TCB);
}
}the main character here is the TCB 👑 you grab the InitiatorTaskTag for the CmdSN, use it to find the TCB, and then send the command again 💖
Now for the big one, evaluating a StatSN 🧚 this function starts with send-status-SNACK set to FALSE, and then it's basically a flowchart. If things are in order, it bumps the ExpectedStatSN. If they're not, it flips SoFarInOrder to FALSE and asks for a status SNACK. When things are already out of order, it checks whether this StatSN is one that was marked missing, and if it's just higher than expected, it asks for a SNACK. Otherwise it discards the PDU 🍓
Evaluate-a-StatSN(Connection, CurrentPDU)
{
send-status-SNACK = FALSE;
if (Connection.SoFarInOrder == TRUE) {
if (current StatSN is the expected) {
Increment Connection.ExpectedStatSN.
} else {
Connection.SoFarInOrder = FALSE;
send-status-SNACK = TRUE;
}
} else {
if (current StatSN was considered missing) {
remove current StatSN from the missing list.
} else {
if (current StatSN is higher than expected){
send-status-SNACK = TRUE;
} else {
send-status-SNACK = FALSE;
discard the PDU;
}
}
Adjust Connection.ExpectedStatSN if appropriate.
if (missing StatSN list is empty) {
Connection.SoFarInOrder = TRUE;
}
}
return send-status-SNACK;
}and then the flag comes back up 🌈 after the StatSN check, it goes back to the caller, so the caller knows if a status SNACK is needed.
Here's the big receiver function, which gets an incoming PDU and sorts it out by type 💅 it checks basic validity and drops the PDU if the Header-Digest is bad 🙈 then it finds the TCB from the InitiatorTaskTag. NOP-In PDUs get handled when they're unsolicited, Reject PDUs only matter for a data digest error on immediate data, and Response PDUs run the StatSN check and possibly ask for recovery. Everything else is out of scope here and isn't shown 🦋
Receive-an-In-PDU(Connection, CurrentPDU)
{
check-basic-validity(CurrentPDU);
if (Header-Digest-Bad) discard, return;
Retrieve TCB for CurrentPDU.InitiatorTaskTag.
if (CurrentPDU.type == NOP-In) {
if (the PDU is unsolicited) {
if (current StatSN is not expected) {
Recover-Status-if-Possible(Connection,
CurrentPDU);
}
if (current ExpCmdSN is not Session.CmdSN) {
Retransmit-Command-if-Possible(Connection,
CurrentPDU.ExpCmdSN);
}
}
} else if (CurrentPDU.type == Reject) {
if (it is a data digest error on immediate data) {
Retransmit-Command-if-Possible(Connection,
CurrentPDU.BadPDUHeader.CmdSN);
}
} else if (CurrentPDU.type == Response) {
send-status-SNACK = Evaluate-a-StatSN(Connection,
CurrentPDU);
if (send-status-SNACK == TRUE)
Recover-Status-if-Possible(Connection, CurrentPDU);
} else { /* REST UNRELATED TO WITHIN-CONNECTION-RECOVERY,
* NOT SHOWN */
}
}Two timeout handlers come next 🧚 when a command's acknowledge timer goes off, the handler finds the Connection for that TCB and retransmits the command if it can 🌸
Command-Acknowledge-Timeout-Handler(TCB)
{
Retrieve the Connection for TCB.
Retransmit-Command-if-Possible(Connection, TCB.CmdSN);
}And when the status expect timer goes off, what happens depends on the ErrorRecoveryLevel 🍓 at level above 0, it sends a NOP-Out. Otherwise, if InitiatorProactiveSNACKEnabled is set and the connection is still logged in and not already considered failed, it sends a SNACK for the status 💜
Status-Expect-Timeout-Handler(Connection)
{
if (operational ErrorRecoveryLevel > 0) {
Build-And-Send-NOP-Out(Connection);
} else if (InitiatorProactiveSNACKEnabled){
if ((Connection.state == LOGGED_IN) and
connection is not already considered failed) {
Build-And-Send-SSnack(Connection);
}
}
}D.3.3. Target Algorithms 🎀
Now we flip over to the target's side, and the only thing covered here is handling a status SNACK request 🦋
Handle-Status-SNACK-request(Connection, CurrentPDU)
{
if (operational ErrorRecoveryLevel > 0) {
if (request for an acknowledged run) {
Build-And-Send-Reject(Connection, CurrentPDU,
Protocol-Error);
} else if (request for an untransmitted run) {
discard, return;
} else {
Retransmit-Status-Burst(CurrentPDU, TCB);
}
} else {
Build-And-Send-Async(Connection, DroppedConnection,
DefaultTime2Wait, DefaultTime2Retain);
}
}so with ErrorRecoveryLevel above 0: a request for an acknowledged run gets a Protocol-Error Reject, a request for an untransmitted run gets discarded, and anything else gets the status burst retransmitted 💅 if the level is 0, the target sends an Async message about the dropped connection instead 💀
D.4. Connection Recovery Algorithms 👑
This section is all about getting connections back on track when things go sideways 🌈
D.4.1. Procedure Descriptions ✨
Here's the lineup of procedures this section relies on. Each one just has a name and its inputs, so you can see who's talking to who 💖
Build-And-Send-Async(transport connection, reason code,
minimum time, maximum time);
Pick-A-Logged-In-Connection(session);
Build-And-Send-Logout(transport connection,
logout connection identifier, reason code);
PerformImplicitLogout(transport connection,
logout connection identifier, target information);
PerformLogin(transport connection, target information);
CreateNewTransportConnection(target information);
Build-And-Send-Command(transport connection, task control block);
Connection-Cleanup-Handler(transport connection);
Connection-Resource-Timeout-Handler(transport connection);
Quiesce-And-Prepare-for-New-Allegiance(session, task control block);
Build-And-Send-Logout-Response(transport connection,
CID of connection in recovery, reason code);
Build-And-Send-TaskMgmt-Response(transport connection,
task mgmt command PDU, response code);
Establish-New-Allegiance(task control block, transport connection);
Schedule-Command-To-Continue(task control block);Note:
- Transport exception conditions such as unexpected connection termination, connection reset, and hung connection while the connection is in the Full Feature Phase are all assumed to be asynchronously signaled to the iSCSI layer using the
Transport_Exception_Handlerprocedure. 🫶
D.4.2. Initiator Algorithms 🦋
This is the initiator's connection recovery toolkit 💅 the first function takes an incoming PDU, checks that it's valid, and then handles it by type. Async PDUs can mean a dropped connection, a logout request, or a dropped session 😭 LogoutResponse and LoginResponse PDUs deal with the cleanup connections and the implicit logouts 🌸
Receive-an-In-PDU(Connection, CurrentPDU)
{
check-basic-validity(CurrentPDU);
if (Header-Digest-Bad) discard, return;
Retrieve TCB from CurrentPDU.InitiatorTaskTag.
if (CurrentPDU.type == Async) {
if (CurrentPDU.AsyncEvent == ConnectionDropped) {
Retrieve the AffectedConnection for
CurrentPDU.Parameter1.
AffectedConnection.CurrentTimeout =
CurrentPDU.Parameter3;
AffectedConnection.State = CLEANUP_WAIT;
Start-Timer(Connection-Cleanup-Handler,
AffectedConnection, CurrentPDU.Parameter2);
} else if (CurrentPDU.AsyncEvent == LogoutRequest)) {
AffectedConnection = Connection;
AffectedConnection.State = LOGOUT_REQUESTED;
AffectedConnection.PerformConnectionCleanup = TRUE;
AffectedConnection.CurrentTimeout =
CurrentPDU.Parameter3;
Start-Timer(Connection-Cleanup-Handler,
AffectedConnection, 0);
} else if (CurrentPDU.AsyncEvent == SessionDropped)) {
for (each Connection) {
Connection.State = CLEANUP_WAIT;
Connection.CurrentTimeout = CurrentPDU.Parameter3;
Start-Timer(Connection-Cleanup-Handler,
Connection, CurrentPDU.Parameter2);
}
Session.state = FAILED;
}
} else if (CurrentPDU.type == LogoutResponse) {
Retrieve the CleanupConnection for CurrentPDU.CID.
if (CurrentPDU.Response = failure) {
CleanupConnection.State = CLEANUP_WAIT;
} else {
CleanupConnection.State = FREE;
}
} else if (CurrentPDU.type == LoginResponse) {
if (this is a response to an implicit Logout) {
Retrieve the CleanupConnection.
if (successful) {
CleanupConnection.State = FREE;
Connection.State = LOGGED_IN;
} else {
CleanupConnection.State = CLEANUP_WAIT;
DestroyTransportConnection(Connection);
}
}
} else { /* REST UNRELATED TO CONNECTION-RECOVERY,
* NOT SHOWN */
}
if (CleanupConnection.State == FREE) {
for (each command that was active on CleanupConnection) {
/* Establish new connection allegiance */
NewConnection = Pick-A-Logged-In-Connection(Session);
Build-And-Send-Command(NewConnection, TCB);
}
}
}once a cleanup connection hits FREE, every command that was active on it gets moved to a new logged-in connection 🚀
Next is the cleanup handler 🧚 if the connection can still exchange iSCSI PDUs, it gets used for the Logout. If not, a resource timeout gets started, and then it either picks another logged-in connection or creates a new transport connection and does an implicit Logout on it 💖
Connection-Cleanup-Handler(Connection)
{
Retrieve Session from Connection.
if (Connection can still exchange iSCSI PDUs) {
NewConnection = Connection;
} else {
Start-Timer(Connection-Resource-Timeout-Handler,
Connection, Connection.CurrentTimeout);
if (there are other logged-in connections) {
NewConnection = Pick-A-Logged-In-Connection(Session);
} else {
NewConnection =
CreateTransportConnection(Session.OtherEndInfo);
Initiate an implicit Logout on NewConnection for
Connection.CID.
return;
}
}
Build-And-Send-Logout(NewConnection, Connection.CID,
RecoveryRemove);
}Last but not least, the transport exception handler 💅 it flags the connection for cleanup. If the event is an unexpected transport disconnect, the connection goes into CLEANUP_WAIT with the DefaultTime2Retain timeout and a timer on DefaultTime2Wait. For any other event, the connection just goes FREE 🌈
Transport_Exception_Handler(Connection)
{
Connection.PerformConnectionCleanup = TRUE;
if (the event is an unexpected transport disconnect) {
Connection.State = CLEANUP_WAIT;
Connection.CurrentTimeout = DefaultTime2Retain;
Start-Timer(Connection-Cleanup-Handler, Connection,
DefaultTime2Wait);
} else {
Connection.State = FREE;
}
}D.4.3. Target Algorithms ✨
okay so here's the target side of connection recovery, and it's giving pseudocode realness 💅 no prose needed, just read the code bestie 🫶
Receive-an-In-PDU(Connection, CurrentPDU)
{
check-basic-validity(CurrentPDU);
if (Header-Digest-Bad) discard, return;
else if (Data-Digest-Bad) {
Build-And-Send-Reject(Connection, CurrentPDU,
Payload-Digest-Error);
discard, return;
}
Retrieve TCB and Session.
if (CurrentPDU.type == Logout) {
if (CurrentPDU.ReasonCode = RecoveryRemove) {
Retrieve the CleanupConnection from CurrentPDU.CID).
for (each command active on CleanupConnection) {
Quiesce-And-Prepare-for-New-Allegiance(Session,
TCB);
TCB.CurrentlyAllegiant = FALSE;
}
Cleanup-Connection-State(CleanupConnection);
if ((quiescing successful) and (cleanup successful))
{
Build-And-Send-Logout-Response(Connection,
CleanupConnection.CID, Success);
} else {
Build-And-Send-Logout-Response(Connection,
CleanupConnection.CID, Failure);
}
}
} else if ((CurrentPDU.type == Login) and
operational ErrorRecoveryLevel == 2) {
Retrieve the CleanupConnection from CurrentPDU.CID).
for (each command active on CleanupConnection) {
Quiesce-And-Prepare-for-New-Allegiance(Session,
TCB);
TCB.CurrentlyAllegiant = FALSE;
}
Cleanup-Connection-State(CleanupConnection);
if ((quiescing successful) and (cleanup successful))
{
Continue with the rest of the login processing;
} else {
Build-And-Send-Login-Response(Connection,
CleanupConnection.CID, Target Error);
}
}
} else if (CurrentPDU.type == TaskManagement) {
if (CurrentPDU.function == "TaskReassign") {
if (Session.ErrorRecoveryLevel < 2) {
Build-And-Send-TaskMgmt-Response(Connection,
CurrentPDU,
"Task allegiance reassignment not
supported");
} else if (task is not found) {
Build-And-Send-TaskMgmt-Response(Connection,
CurrentPDU, "Task not in task set");
} else if (task is currently allegiant) {
Build-And-Send-TaskMgmt-Response(Connection,
CurrentPDU, "Task still allegiant");
} else {
Establish-New-Allegiance(TCB, Connection);
TCB.CurrentlyAllegiant = TRUE;
Schedule-Command-To-Continue(TCB);
}
}
} else { /* REST UNRELATED TO CONNECTION-RECOVERY,
* NOT SHOWN */
}
}
Transport_Exception_Handler(Connection)
{
Connection.PerformConnectionCleanup = TRUE;
if (the event is an unexpected transport disconnect) {
Connection.State = CLEANUP_WAIT;
Start-Timer(Connection-Resource-Timeout-Handler,
Connection, (DefaultTime2Wait+DefaultTime2Retain));
if (this Session has Full Feature Phase connections
left) {
DifferentConnection =
Pick-A-Logged-In-Connection(Session);
Build-And-Send-Async(DifferentConnection,
DroppedConnection, DefaultTime2Wait,
DefaultTime2Retain);
}
} else {
Connection.State = FREE;
}
}Appendix E. Clearing Effects of Various Events on Targets 🧚
E.1. Clearing Effects on iSCSI Objects 🎀
Okay bestie, this is the big clearing cheat sheet 💅 The tables show how a target responds to each event listed in the rows. The second table picks up where the first one leaves off and covers clearing actions for more objects on those same events. Here's the legend:
- Y means yes: cleared, discarded, or reset on the event in that row. Unless noted otherwise, the clearing only applies to the initiator port that issued the request. 🦋
- N means no: not affected, so it stays at its previous value. 🌸
- NA means not applicable or not defined. 🙈
+------+------+------+------+------+
|IT (1)|IC (2)|CT (5)|ST (6)|PP (7)|
+----------------------+------+------+------+------+------+
|connection failure (8)|Y |Y |N |N |Y |
+----------------------+------+------+------+------+------+
|connection state |NA |NA |Y |N |NA |
|timeout (9) | | | | | |
+----------------------+------+------+------+------+------+
|session timeout/ |Y |Y |Y |Y |Y (14)|
|closure/reinstatement | | | | | |
|(10) | | | | | |
+----------------------+------+------+------+------+------+
|session continuation |NA |NA |N (11)|N |NA |
|(12) | | | | | |
+----------------------+------+------+------+------+------+
|successful connection |Y |Y |Y |N |Y (13)|
|close logout | | | | | |
+----------------------+------+------+------+------+------+
|session failure (18) |Y |Y |N |N |Y |
+----------------------+------+------+------+------+------+
|successful recovery |Y |Y |N |N |Y (13)|
|Logout | | | | | |
+----------------------+------+------+------+------+------+
|failed Logout |Y |Y |N |N |Y |
+----------------------+------+------+------+------+------+
|connection Login |NA |NA |NA |Y (15)|NA |
|(leading) | | | | | |
+----------------------+------+------+------+------+------+
|connection Login |NA |NA |N (11)|N |Y |
|(non-leading) | | | | | |
+----------------------+------+------+------+------+------+
|TARGET COLD RESET (16)|Y (20)|Y |Y |Y |Y |
+----------------------+------+------+------+------+------+
|TARGET WARM RESET (16)|Y (20)|Y |Y |Y |Y |
+----------------------+------+------+------+------+------+
|LU reset (19) |Y (20)|Y |Y |Y |Y |
+----------------------+------+------+------+------+------+
|power cycle (16) |Y |Y |Y |Y |Y |
+----------------------+------+------+------+------+------+Here's what the labels in that first table mean:
- (1) IT is for Incomplete TTTs: Target Transfer Tags where the target is still waiting to receive PDUs. Examples include TTTs received via R2T, NOP-In, and so on. 🧚
- (2) IC is for Immediate Commands: commands that are immediate but still waiting to be executed on a target, like ABORT TASK SET. ⭐
- (5) CT is for Connection Tasks: tasks that are active on the iSCSI connection in question. 💜
- (6) ST is for Session Tasks: tasks active on the whole iSCSI session. It's basically the union of the connection tasks across every participating connection. 👑
- (7) PP is for Partial PDUs: PDUs that were partly sent and are waiting for transport window credit so they can finish. 🍓
- (8) Connection failure is a connection exception. One of the transport connections shut down, got reset, or timed out, and that abruptly ended the iSCSI Full Feature Phase connection. A connection failure always moves the connection state machine into the CLEANUP_WAIT state. 😭
- (9) A connection state timeout happens when a connection spends longer in the CLEANUP_WAIT state than was agreed on during login negotiation. That pushes the connection to the FREE state (the M1 transition in the connection cleanup state diagram, see Section 8.2). 💀
- (10) Session timeout, closure, and reinstatement are defined in Section 6.3.5. 🌈
- (11) This clearing effect is "Y" only when it's a connection reinstatement and the operational ErrorRecoveryLevel is less than 2. 🔥
- (12) Session continuation is defined in Section 6.3.6. ✨
- (13) This clearing effect is only valid when the connection is being logged out on a different connection and the connection being logged out on the target may still have some partial PDUs waiting to be sent. Otherwise it's "NA". 🦋
- (14) This clearing effect only applies to a "close the session" logout in a multi-connection session. Everywhere else it's "NA". 🫶
- (15) Only applies if this leading connection login is a session reinstatement. If not, it's "NA". 🌸
- (16) This operation affects all logged-in initiators. 🎀
- (18) Session failure is defined in Section 6.3.6. 🙈
- (19) This operation affects all logged-in initiators, but the clearing effects only apply to the LU being reset. 💅
- (20) With standard multi-task abort semantics (Section 4.2.3.3), a TARGET WARM RESET, a TARGET COLD RESET, or an LU reset clears the active TTTs once it completes. FastAbort multi-task abort semantics (Section 4.2.3.4) don't guarantee that the active TTTs are cleared by the end of the reset operations. FastAbort is designed to clear TTTs "lazily", after the TMF Response has already been delivered. So when TaskReporting=FastAbort (Section 13.23) is operational on a session, the clearing effect of reset operations on "Incomplete TTTs" is "N". 🧚
Now the second table, which covers more objects. Its footnotes are below it.
+------+-------+------+------+-------+
|DC (1)|DD (2) |SS (3)|CS (4)|DS (5) |
+---------------------+------+-------+------+------+-------+
|connection failure |N |Y |N |N |N |
+---------------------+------+-------+------+------+-------+
|connection state |Y |NA |Y |N |NA |
|timeout | | | | | |
+---------------------+------+-------+------+------+-------+
|session timeout/ |Y |Y |Y (7) |Y |NA |
|closure/reinstatement| | | | | |
+---------------------+------+-------+------+------+-------+
|session continuation |N (11)|NA (12)|NA |N |NA (13)|
+---------------------+------+-------+------+------+-------+
|successful connection|Y |Y |Y |N |NA |
|close Logout | | | | | |
+---------------------+------+-------+------+------+-------+
|session failure |N |Y |N |N |N |
+---------------------+------+-------+------+------+-------+
|successful recovery |Y |Y |Y |N |N |
|Logout | | | | | |
+---------------------+------+-------+------+------+-------+
|failed Logout |N |Y (9) |N |N |N |
+---------------------+------+-------+------+------+-------+
|connection Login |NA |NA |N (8) |N (8) |NA |
|(leading | | | | | |
+---------------------+------+-------+------+------+-------+
|connection Login |N (11)|NA (12)|N (8) |N |NA (13)|
|(non-leading) | | | | | |
+---------------------+------+-------+------+------+-------+
|TARGET COLD RESET |Y |Y |Y |Y (10)|NA |
+---------------------+------+-------+------+------+-------+
|TARGET WARM RESET |Y |Y |N |N |NA |
+---------------------+------+-------+------+------+-------+
|LU reset |N |Y |N |N |N |
+---------------------+------+-------+------+------+-------+
|power cycle |Y |Y |Y |Y (10)|NA |
+---------------------+------+-------+------+------+-------+And the footnotes for that second table:
- (1) DC is for Discontiguous Commands: commands that belong to the connection in question and are waiting to be reordered in the iSCSI layer. Every "Y" in this column assumes the task causing the event (if the event comes from a task) was issued as an immediate command, because the discontiguities can sit ahead of that task. 🌈
- (2) DD is for Discontiguous Data: data PDUs received for the task in question that are waiting to be reordered because of earlier discontiguities in the DataSN. 🍓
- (3) "SS" means the StatSN. 🎀
- (4) "CS" means the CmdSN. 🦋
- (5) "DS" means the DataSN. 🧚
- (7) This action clears the StatSN on all the connections. 👑
- (8) This sequence number gets instantiated on this event. ✨
- (9) A logout failure drives the connection state machine into the CLEANUP_WAIT state, just like the connection failure event. So it has a similar effect on this and several other protocol aspects. 😭
- (10) This gets cleared because all sessions with all initiators are terminated. 🔥
- (11) This clearing effect is "Y" if it's a connection reinstatement. 🌸
- (12) This clearing effect is "Y" only when it's a connection reinstatement and the operational ErrorRecoveryLevel is 2. 💜
- (13) This clearing effect is "N" only when it's a connection reinstatement and the operational ErrorRecoveryLevel is 2. 🫶
E.2. Clearing Effects on SCSI Objects 🌈
The only iSCSI protocol action that can cause clearing actions on SCSI objects is the "I_T nexus loss" notification (Section 6.3.5.1 ("Loss of Nexus Notification")). [SPC3] describes what this notification clears across a bunch of SCSI attributes. On top of that, SCSI standards documents such as [SAM2] and [SBC2] define extra clearing actions that can happen to several SCSI objects during SCSI events like LU resets and power-on resets. 💅
Since iSCSI defines a TARGET COLD RESET as a "protocol-equivalent" to a target power cycle, the iSCSI TARGET COLD RESET also has to be treated as the power-on reset event when you interpret the actions in the SCSI standards. 🧚
When the iSCSI session gets reconstructed between the same SCSI ports with the same nexus identifier, reestablishing the same I_T nexus, every SCSI object that's defined not to clear on the "I_T nexus loss" notification (things like persistent reservations) is automatically associated with the new session. 🦋🎀
Acknowledgments ✨
okay so huge shoutout to the people on the original IPS Working Group who made significant contributions to RFCs 3720, 3980, 4850, and 5048 🫶 The authors of those original RFCs, which are now consolidated into this one single document, were:
- RFC 3720: Julian Satran, Kalman Meth, Costa Sapuntzakis, Mallikarjun Chadalapaka, Efri Zeidner
- RFC 3980: Marjorie Krueger, Mallikarjun Chadalapaka, Rob Elliott
- RFC 4850: David Wysochanski
- RFC 5048: Mallikarjun Chadalapaka
Thanks so much to Fred Knight for the UML notations and drawings in this doc 🎨 He really made the diagrams pop.
We also want to acknowledge the people who helped with this revised document: David Harrington, Paul Koning, Mark Edwards, Rob Elliott, and Martin Stiemerling 💜
Big thanks to Yi Zeng and Nico Williams for suggesting and/or reviewing the Kerberos-related security considerations text 🔐 Those sections are seriously important, so we really appreciate it.
The authors are also super grateful for the feedback during the Last Call review process. Their input significantly improved this document ✨ The reviewers were Stephen Farrell, Brian Haberman, Barry Leiba, Pete Resnick, Sean Turner, Alexey Melnikov, Kathleen Moriarty, Fred Knight, Mike Christie, Qiang Wang, Shiv Rajpal, and Andy Banta 🌸
Last but not least, this document benefited a lot from the Storm Working Group at large, who gave tons of review input 🦋
Comments may be sent to Mallikarjun Chadalapaka 💌
Authors' Addresses 📮
Mallikarjun Chadalapaka
Microsoft
One Microsoft Way
Redmond, WA 98052
USA
EMail: cbm@chadalapaka.com
Julian Satran
Infinidat Ltd.
EMail: julians@infinidat.com, julian@satran.net
Kalman Meth
IBM Haifa Research Lab
Haifa University Campus - Mount Carmel
Haifa 31905, Israel
Phone +972.4.829.6341
EMail: meth@il.ibm.com
David L. Black
EMC Corporation
176 South St.
Hopkinton, MA 01748
USA
Phone +1 (508) 293-7953
EMail: david.black@emc.com📦 where this page comes from
- ietf: rfc7143 2014-04
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms