RFC 7143
Internet Small Computer System Interface (iSCSI) Protocol (Consolidated)
Pages: 295
Proposed Standard
Obsoletes: 3720 3980 4850 5048
Updates: 3721
Proposed Standard
Obsoletes: 3720 3980 4850 5048
Updates: 3721
Part 3 of 10 – Pages 36 to 63
4.2.3. iSCSI Task Management
4.2.3.1. Task Management Overview
iSCSI task management features allow an initiator to 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
Protocol behavior defined in this section SHOULD be implemented by
all iSCSI implementations complying with this document, noting that
some steps below may not be compatible with [RFC3720] semantics.
However, protocol behavior defined in this section MUST be exhibited
by iSCSI implementations on an iSCSI session when they negotiate the
TaskReporting (Section 13.23) key to "FastAbort" on that session.
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 NOT send any more Data-Out PDUs for affected tasks on the
issuing connection of the issuing iSCSI session once the TMF is
sent to the target.
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) MUST respond to each Async Message PDU with a Task Termination
AsyncEvent (5) as defined in Section 11.9.
d) MUST treat the TMF Response as terminating all affected tasks
for which responses have not been received and MUST discard any
responses for affected tasks received after the TMF Response is
passed to the SCSI layer (although the semantics defined in
this section ensure that such an out-of-order scenario will
never happen with a compliant target implementation).
The target iSCSI layer:
a) MUST wait for all commands of the affected tasks to be received
based on the CmdSN ordering on the issuing session. 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. In the case of target-scoped
requests (i.e., TARGET WARM RESET and TARGET COLD RESET), all
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".
b) MUST propagate the TMF Request to, and receive the response
from, the target SCSI layer.
c) MUST leave all active "affected TTTs" (i.e., active TTTs
associated with affected tasks) valid.
d) MUST send an Asynchronous Message PDU with AsyncEvent=5
(Section 11.9) on:
1) each connection of each third-party session to which at
least one affected task is allegiant 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 (say, due to a target
reset), then one Async Message PDU MUST be sent for each
such LU on each connection that has at least one allegiant
affected task. The LUN field in the Asynchronous Message
PDU MUST be set to match the LUN for each such LU.
e) MUST address the Response Fence flag on the TMF Response on the
issuing session as defined in Section 4.2.2.3.3.
f) MUST address 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 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).
g) MUST free up the affected TTTs (and STags for iSER, if
applicable) and the corresponding buffers, if any, once it
receives each associated NOP-Out acknowledgment that the
initiator generated in response to each Async Message.
Technically, the TMF servicing is complete in Step e). Data
transfers corresponding to terminated tasks may, however, still be in
progress 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 MAY be sent
at the end of Step e) despite these outstanding Data transfers until
Step g). Step g) specifies an event to free up any such resources
that may have been reserved to support outstanding data transfers.
4.2.3.5. Affected Tasks Shared across Standard and FastAbort Sessions
If an iSCSI target implementation is capable of supporting
TaskReporting=FastAbort functionality (Section 13.23), it may end up
in a situation where some sessions have TaskReporting=RFC3720
operational (RFC 3720 sessions) while some other sessions have
TaskReporting=FastAbort operational (FastAbort sessions) even while
accessing a shared set of affected tasks (Section 4.2.3.2). If the
issuing session is an RFC 3720 session, the iSCSI target
implementation is FastAbort-capable, and the third-party affected
session is a FastAbort session, the following behavior SHOULD be
exhibited by the iSCSI target layer:
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 to which at least one affected task is allegiant.
If there are multiple affected LUs, then 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 the
Asynchronous Message PDU MUST be set to match the LUN for each
such LU.
b) After Step e) of the target behavior in Section 4.2.3.3, free
up the affected TTTs (and STags for iSER, if applicable) and
the corresponding buffers, if any, once each associated NOP-Out
acknowledgment is received that the third-party initiator
generated in response to each Async Message sent in Step a).
If the issuing session is a FastAbort session, the iSCSI target implementation is FastAbort-capable, and the third-party affected session is an RFC 3720 session, the iSCSI target layer MUST NOT send Asynchronous Message PDUs on the third-party session to prompt the FastAbort behavior. If the third-party affected session is a FastAbort session and the issuing session is 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. Note that an initiator MAY thus receive these Async Messages on a third-party affected session even if the session is a single-connection session.4.2.3.6. Rationale behind the FastAbort Semantics
There are fundamentally three basic objectives behind the semantics specified in Sections 4.2.3.3 and 4.2.3.4. a) Maintaining an ordered command flow I_T nexus abstraction to the target SCSI layer even with multi-connection sessions. - Target iSCSI processing of a TMF Request must maintain the single flow illusion. The target behavior in Step b) of Section 4.2.3.3 and the target behavior in Step a) of Section 4.2.3.4 correspond to this objective. b) Maintaining a single ordered response flow I_T nexus abstraction to the initiator SCSI layer even with multi- connection sessions when one response (i.e., TMF Response) could imply the status of other unfinished tasks from the initiator's perspective. - The target must ensure that the initiator does not see "old" task responses (that were placed on the wire chronologically earlier than the TMF Response) after seeing the TMF Response. The target behavior in Step d) of Section 4.2.3.3 and the target behavior in Step e) of Section 4.2.3.4 correspond to this objective. - 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 notified of 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. It would thus be inappropriate to deliver a SCSI Response for a task after the task state is cleared on the initiator, i.e., after the UA is notified. The UA notification contained in
the first SCSI Response PDU on each affected third-party
I_T_L nexus after the TMF action thus MUST NOT pass the
affected task responses on any of the iSCSI sessions
accessing the LU. The target behavior in Step e) of
Section 4.2.3.3 and the target behavior in Step f) of
Section 4.2.3.4 correspond to this objective.
c) Draining all active TTTs corresponding to affected tasks in a
deterministic fashion.
- Data-Out PDUs with stale TTTs arriving after the tasks are
terminated can create a buffer management problem even for
traditional iSCSI implementations and is fatal for the
connection for iSCSI/iSER implementations. 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 to be deterministically freed up later (as in
Steps c) and g) of Section 4.2.3.4).
The only other notable optimization is the plugging. If all tasks on
an I_T nexus will be aborted anyway (as with a target reset), there
is no need to wait to receive all commands to plug the CmdSN holes.
The target iSCSI layer can simply plug all missing CmdSN slots and
move on with TMF processing. The first objective (maintaining a
single ordered command flow) is still met with this optimization
because the target SCSI layer only sees ordered commands.
4.2.4. iSCSI Login
The purpose of the iSCSI login is to enable a TCP connection for
iSCSI use, authentication of the parties, negotiation of the
session's parameters, and marking of the connection as belonging to
an iSCSI session.
A session is used to identify to a target all the connections with 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.)
The targets listen on a well-known TCP port or other TCP port for
incoming connections. The initiator begins the login process 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 occur in many different ways and is
subject to negotiation; see Section 12.
To protect the TCP connection, an IPsec security association MAY be established before the Login Request. For information 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 occurred and operational parameters have been set, the session transitions to the Full Feature Phase and the initiator may start to send SCSI commands. The security policy for whether and by what means a target chooses to authorize an initiator is beyond the scope of this document. 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 the selection of the connection endpoint. For a new session, the TSIH is zero. 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 describe InitiatorName later in this section. Any persistent state (e.g., persistent reservations) on the target that is associated with a SCSI initiator port is identified based on this value pair. Any state associated with 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 is 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 receiving 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) when 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 encapsulating 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. Thus, 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) is sent as either solicited data or unsolicited data. Solicited data are 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 are 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 are meant to reduce the effect of latency on throughput (no R2T is needed to start sending data). In addition, immediate data is meant to reduce the protocol overhead (both bandwidth and execution time). An iSCSI initiator MAY choose not to send unsolicited data, 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 the 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 are 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 (e.g., 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 that are consistent with the values used at the task instantiation, based on the Initiator Task Tag (e.g., the LUN used in an R2T PDU MUST be the same as the one used in the SCSI Command PDU used to instantiate 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 -- i.e., no message involving an aborted task will be seen by the SCSI initiator after receiving the task management response. In iSCSI, initiators and targets interact asynchronously over several connections. iSCSI specifies the protocol mechanism and implementation requirements needed to present a synchronous SCSI view while using an asynchronous iSCSI infrastructure.4.2.6. iSCSI Connection Termination
An iSCSI connection may be terminated via a transport connection shutdown or a transport reset. A transport reset is assumed to be an exceptional event. Graceful TCP connection shutdowns are done 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. If a connection is terminated while in the Full Feature Phase, connection cleanup (see Section 7.14) is required prior to recovery. By doing connection cleanup before starting recovery, the initiator and target will avoid receiving stale PDUs after recovery.4.2.7. iSCSI Names
Both targets and initiators require names for the purpose of identification. In addition, names enable iSCSI storage resources to be managed, regardless of location (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 in authentication of targets to initiators and initiators to targets. This name is also used to identify and manage iSCSI storage resources. iSCSI names must be unique within the operation domain of the end user. However, because the operation domain of an IP network is potentially worldwide, the iSCSI name formats are architected to be worldwide unique. To assist naming authorities in the construction of worldwide unique names, iSCSI provides three name formats for different types of naming authorities.
iSCSI names are associated with iSCSI nodes, and not iSCSI network adapter cards, to ensure that the replacement of network adapter cards does not require reconfiguration of all SCSI and iSCSI resource allocation information. Some SCSI commands require that protocol-specific identifiers be communicated within SCSI CDBs. See Section 2.2 for the definition of the SCSI port name/identifier for iSCSI ports. An initiator may discover the iSCSI Target Names to which it has access, 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. Although [RFC3721] implies an SLP ([RFC2608]) implementation requirement, SLP has not been widely implemented or deployed for use with iSCSI in practice. iSCSI implementations therefore SHOULD NOT rely on SLP-based discovery interoperability.4.2.7.1. iSCSI Name Properties
Each iSCSI node, whether it is an initiator, a target, or both, MUST have an iSCSI name. Whenever 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 such that there is only one iSCSI Node Name for the iSCSI node overall. Note the related requirements in Section 9.2.1 on how to map CHAP names to iSCSI names in such a scenario. Initiators and targets MUST support the receipt of 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 to which it wishes to connect in the first Login Request of a new session or connection. The only exception is if a Discovery session (see Section 4.3) is to be established. In this case, the iSCSI Initiator Name is still required, but the iSCSI Target Name MAY be omitted. iSCSI names have the following 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 the following 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 the use of 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 is not tied
to a port or other hardware that can be changed. For instance, 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
are simply paths to the same SCSI layer. In most operating systems,
the named entity is the operating system image.
Similarly, a target name should not be tied to hardware interfaces
that can be changed. A target name should identify the logical
target and must be the same for the target, regardless of the
physical portion being addressed. This assists iSCSI initiators in
determining that the two targets it has discovered are really two
paths to the same target.
The iSCSI name is designed to fulfill the functional requirements for Uniform Resource Names (URNs) [RFC1737]. For example, it is required that the name have a global scope, be independent of address or location, and 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 the following 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) - The UTF-8 encoding of the name is not larger than 223 bytes. The stringprep process is described in [RFC3454]; iSCSI's use of the stringprep process is described in [RFC3722]. The stringprep process is a method designed by the Internationalized Domain Name (IDN) working group to translate human-typed strings into a format that can be compared as opaque strings. iSCSI names are expected to be used by administrators for purposes such as system configuration; for this reason, characters that may lead to human confusion among different iSCSI names (e.g., punctuation, spacing, diacritical marks) should be avoided, even when such characters are allowed as stringprep processing output by [RFC3722]. The stringprep process also converts strings into equivalent strings of lowercase characters. The stringprep process does not need to be implemented if the 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, as well as lowercase Unicode characters as specified in [RFC3722]. Once iSCSI names encoded in UTF-8 are "normalized" as described in this section, they may be safely compared byte for byte.
4.2.7.3. iSCSI Name Structure
An iSCSI name consists of two parts -- a type designator followed by a unique name string. iSCSI uses three existing naming authorities in constructing globally unique iSCSI names. The type designator in an iSCSI name indicates the naming authority on which the name is based. The three iSCSI name formats are the following: 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 assists in the formation of 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 at the time of writing this document. The creation of additional naming type designators for iSCSI may be considered by the IETF and detailed in separate RFCs.
The following table summarizes 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)
This iSCSI name type can be used by any organization that owns a
domain name. This naming format is useful when an end user or
service provider wishes to assign iSCSI names for targets and/or
initiators.
To generate names of this type, the person or organization generating
the name must own a registered domain name. This domain name does
not have to resolve to an address; it just needs to be reserved to
prevent others from generating iSCSI names using the same
domain name.
Since a domain name can expire, be acquired by another entity, or may
be used to generate iSCSI names by both owners, the domain name must
be additionally qualified by a date during which the naming authority
owned the domain name. A date code is provided as part of the "iqn."
format for this reason.
The iSCSI qualified name string consists of:
- The string "iqn.", used to distinguish these names 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 the 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.xyz
4.2.7.5. Type "eui." (IEEE EUI-64 Format)
The IEEE Registration Authority provides a service for assigning
globally unique identifiers [EUI]. The EUI-64 format is used to
build a global identifier in other network protocols. For example,
Fibre Channel defines a method of encoding it into a WorldWideName.
For more information on registering for EUI identifiers, see [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.02004567A425678D
The 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 constructing worldwide unique identifiers that use various identifier registration authorities. This identifier format is used by the Fibre Channel and SAS SCSI transport protocols. As FC and SAS constitute a large fraction of networked SCSI ports, the NAA format is a widely used format for SCSI transports. The objective behind iSCSI supporting a direct representation of an NAA format Name is to facilitate construction of a target device name that translates easily across multiple namespaces for a SCSI storage device containing ports served by different transports. More specifically, this format allows implementations wherein one NAA identifier can be assigned as the basis for the SCSI device name for a SCSI target with both SAS ports and iSCSI ports. 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 follows: Type NAA identifier (ASCII-encoded hexadecimal) +--++--------------+ | || | naa.52004567BA64678D An example of an iSCSI name with a 128-bit NAA value follows: Type NAA identifier (ASCII-encoded hexadecimal) +--++------------------------------+ | || | naa.62004567BA64678D0123456789ABCDEF The 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 formatted in an ASCII-hexadecimal representation has a maximum size of 32 characters (128-bit NAA format). As a result, there is no issue with this naming format exceeding the maximum size for iSCSI Node Names.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. All iSCSI session and connection parameters are reinitialized on session and connection creation. 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.4.2.9. Message Synchronization and Steering
iSCSI presents a mapping of the SCSI protocol onto TCP. This encapsulation is accomplished by sending iSCSI PDUs of varying lengths. Unfortunately, TCP does not have a built-in mechanism for signaling message boundaries at the TCP layer. iSCSI overcomes this obstacle by placing the message length in the iSCSI message header. This serves to delineate the end of the current message as well as the beginning of the next message. In situations where IP packets are delivered in order from the network, iSCSI message framing is not an issue and messages are processed one after the other. In the presence of 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, at which time the data must be copied to the application buffers. In iSCSI, it is desirable to steer the SCSI data within these out-of-order TCP segments into the preallocated SCSI buffers rather than store them in temporary buffers. This decreases the need for dedicated reassembly buffers as well as the latency and bandwidth related to extra copies.
Relying solely on the "message length" information from the iSCSI message header may make it impossible to find iSCSI message boundaries in subsequent TCP segments due to the loss of a TCP segment that contains the iSCSI message length. The missing TCP segment(s) must be received before any of the following segments can be steered to the correct SCSI buffers (due to the inability to determine the iSCSI message boundaries). Since these segments cannot be steered to the correct location, they must be saved in temporary buffers that must then be copied to the SCSI buffers. Different schemes can be used to recover synchronization. The details of any such schemes are beyond this protocol specification, but it suffices to note that [RFC4297] provides an overview of the direct data placement problem on IP networks, and [RFC5046] specifies a protocol extension for iSCSI that facilitates this direct data placement objective. 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 accomplished by using the identifying tag and the data offset fields in the iSCSI header in addition to 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 are used to determine the offset within the buffer.4.2.9.1. Sync/Steering and iSCSI PDU Length
When a large iSCSI message is sent, the TCP segment(s) that contains 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 indicates to which SCSI buffers the data are to be steered was lost. To minimize the amount of buffering, 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
The following diagram shows an example of how multiple iSCSI nodes
(targets in this case) can coexist within the same Network Entity and
can share Network Portals (IP addresses and TCP ports). Other more
complex configurations are also possible. For detailed descriptions
of the components of these diagrams, 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
This section describes the part of the iSCSI Architecture Model that has the most bearing on the relationship between iSCSI and the SCSI Architecture Model. - Network Entity - represents a device or gateway that is accessible from the IP network. A Network Entity must have one or more Network Portals (see the "Network Portal" item below), each of which can be used by some iSCSI nodes (see the next item) contained in that Network Entity to gain access to the IP network. - iSCSI Node - represents 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 is accessible via one or more Network Portals (see below). An iSCSI node is identified by its iSCSI name (see Sections 4.2.7 and 13). The separation of the iSCSI name from the addresses used by and for the iSCSI node allows multiple iSCSI nodes to use the same addresses and allows the same iSCSI node to use multiple addresses. - An alias string may also be associated with an iSCSI node. The alias allows an organization to associate a user-friendly string with the iSCSI name. However, the alias string is not a substitute for the iSCSI name. - Network Portal - 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; some implementations will have the ability to combine connections in a session across multiple Network Portals. A portal group defines a set of Network Portals within an iSCSI node that collectively supports the capability of coordinating a session with connections that span these 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 utilized 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, 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 following diagram shows an example of one such configuration 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
This section describes the relationship between the SCSI Architecture
Model [SAM2] and constructs of the SCSI device, SCSI port and I_T
nexus, and the iSCSI constructs described in Section 4.4.1.
This relationship implies implementation requirements in order to
conform to the SAM-2 model and other SCSI operational functions.
These requirements are detailed in Section 4.4.3. The following list outlines mappings of SCSI architectural elements to iSCSI. a) SCSI Device - This is the SAM-2 term for an entity that contains one or more SCSI ports that are 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 within an iSCSI node that provides the SCSI functionality. As such, 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 to interface 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 is negotiated through the login process between an iSCSI initiator node and an iSCSI target node. At successful completion of this process, 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 used in SCSI parameter data, the SCSI port name MUST be encoded as: 1) the iSCSI name in UTF-8 format, followed by 2) a comma separator (1 byte), followed by
3) the ASCII character 'i' (for SCSI initiator port) or the
ASCII character 't' (for SCSI target port) (1 byte),
followed by
4) a comma separator (1 byte), followed by
5) 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 identifies
this port as either a SCSI initiator port or a SCSI target
port.
c) I_T nexus - This indicates a 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 conjunction 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
This section describes implementation and behavioral requirements
that result from the mapping of SCSI constructs to the iSCSI
constructs defined above. Between a given SCSI initiator port and a
given SCSI target port, only one I_T nexus (session) can exist. No
more than one nexus relationship (parallel nexus) is allowed by
[SAM2]. Therefore, at any given time, only one session with the same
SSID can exist between a given iSCSI initiator node and an iSCSI
target node.
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]) provides a mechanism to facilitate compliance with the ISID RULE. See Section 10.1.1. The iSCSI initiator node should manage the assignment of ISIDs prior to session initiation. The "ISID RULE" does not preclude the use of the same ISID from the same iSCSI initiator with different target portal groups on the same iSCSI target or on other iSCSI targets (see Section 10.1.1). Allowing this would be analogous to a single SCSI initiator port having relationships (nexus) with multiple SCSI target ports on the same SCSI target device or SCSI target ports on other SCSI target devices. It is also possible to have multiple sessions with different ISIDs to the same target portal group. Each such session would be considered to be with a different initiator even when the sessions originate from the same initiator device. The same ISID may be used by a different iSCSI initiator because it is the iSCSI name together with the ISID that identifies the SCSI initiator port. 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). After being selected, the same TSIH value MUST be used whenever the initiator or target refers to the session and a TSIH is required.4.4.3.1. I_T Nexus State
Certain nexus relationships contain an 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). In order for that state to be restored, the iSCSI initiator should reestablish its session (re-login) to the same target portal group using the previous ISID. That is, it should reinstate the session via iSCSI session reinstatement (Section 6.3.5) or continue via session continuation (Section 6.3.6). This is because the SCSI initiator port identifier and the SCSI target port identifier (or relative target port) form the datum that the SCSI LU device server uses to identify the I_T nexus.
4.4.3.2. Reservations
There are two reservation management methods defined in the SCSI standards: reserve/release reservations, based on the RESERVE and RELEASE commands [SPC2]; and 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 suggested as an 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 details and specific requirements. In contrast, [SPC2] does not specify detailed persistence requirements for reserve/release reservation state after an I_T nexus failure. Nonetheless, when reserve/release reservations are supported by an iSCSI target, the preferred implementation approach is to preserve reserve/release reservation state for iSCSI session reinstatement (see Section 6.3.5) or session continuation (see Section 6.3.6). Two additional caveats apply to reserve/release reservations: - Retention of a failed session's reserve/release reservation state by an iSCSI target, even after that failed iSCSI session is not 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. - 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].
(next page on part 4)