diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/Changelog open-iscsi-2.0-872-rc4-bnx2i.work/Changelog
--- open-iscsi-2.0-872-rc4-bnx2i/Changelog 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/Changelog 2012-03-05 23:02:46.000000000 -0600
@@ -1,132 +1,114 @@
-open-iscsi-2.0-871 - open-iscsi-2.0.870
+open-iscsi-2.0-872 - open-iscsi-2.0.871
-Boaz Harrosh (1):
- open-iscsi: Makefile: separate out user: and kernel: make targets
+Avi Kaplan (2):
+ Remove unused field iscsi_conn from struct iscsi_sw_tcp_conn
+ Change restore_callbacks argument iscsi_sw_tcp_conn to iscsi_conn
Erez Zilber (1):
- Add Module.markers to .gitignore
+ Fix 2.6.14-23_compat.patch to support all RHEL 5.X versions
-Karen Xie (2):
- userspace - add new transport cxgb3i
- userspace - setting interface ip address
-
-Mike Christie (84):
- iscsid: fix relogin retry handling
- iscsid idbm: print out header and tail to seperate records
- ibft: add support to use iscsi_ibft module and log into all portals found in firmware
- fwparam: rm unused filepath argument
- iscsid idbm: move record strings to header
- iscsiadm: discovery mode supports the --show
- iscsiadm: have fw discovery handle --op arguments
- iscsiadm: fix output ordering
- iscsi modules: fix compilation
- iscsid/iscsiadm: fix strto* usage
- iscsid: fix logout response and time2wait handling
- iscsiadm: remove default bnx2i iface
- iscsid/iscsiadm: support multiple inititor names per host.
- iscsiadm: print session and session info running through ifaces in iface mode
- iscsid: update transport handle
- idbm: have idbm_rec_update_param update the value string of the matching rec_info
- iscsi mod: sync up kernel modules with 2.6.29
- iscsi mod: 2.6.27 compat
- iscsi mod: 2.6.26 compat
- iscsi mod: 2.6.24-25 compat
- iscsi mod: 2.6.20-23 compat
- iscsi mod: 2.6.14-19 compat
- iscsi mod: fix up 2.6.14-19 compat patch
- iscsi mod iscsi_tcp: compat fix for pI4/pI6
- build: add a make user
- iscsi tools: fix chap
- PATCH: iscsi tools: do not use exit()
- PATCH: fix iBFT firmware reading with newer kernels
- 2.6.29-rc libiscsi: Fix scsi command timeout oops in iscsi_eh_timed_out
- iscsi mod: 2.6.14-19 compat
- iscsi tools: convert from strncat to strlcat
- iscsi tools: convert from strncpy to strlcpy
- iscsi tool make: add notification that iscsi start was made
- iscsid: Fix up connection failed messages
- docs: fix up iscsiadm man page iface info
- iscsi tools: update version in preparation for new release
- iscsid: flush sysfs cache.
- iscsid: mv event loop code to new file
- docs: update readme with libiscsi_tcp info
-
-
-
-
--------------------------------------------------------------------
-open-iscsi-2.0-870 - open-iscsi-2.0.869
-
-Doron Shoham (1):
- log.c: add error messages when allocation shared memory
-
-Erez Zilber (2):
- Minor fixes in iscsi_discovery documentation
- rm unused variable in fw_entry.c
-
-Hannes Reinecke (1):
- Add SLES10 SP2 compat
-
-Hans de Goede (1):
- PATCH: add error checking to iscsi discovery db lock creation
-
-Mike Christie (58):
- change mgmt_ipc to logout by sid
- iscsi class/if kernel: add ifacename attr
- add ifacename support tools
- rm db param
- rm num_transports from sysfs header.
- Add bind by initiatorname
- break up iface code and add default iser, tcp/default and bnx2i ifaces
- Use startup definition in util.c.
- set header digests to off by default
- fix compile warning for missing iface.h
- User 64 bit params mask.
- Do not allow iface setting to be changed in node mode.
- Fix bad merge. User iscsi param masks instead of params.
- Support mutlple ifaces with the same binding (lack of binding).
- Release transport entry when the transport is unloaded
- Fix ep_disconnect handling of invalid ep
- libiscsi: Fix nop timeout handling
- libiscsi: fix recv tmo
- Revert Release-transport-entry-when-the-transport-is-unload.patch
- pass ep to session creation
- Fix iser create bound session compat
- fix compilation on Fedora 9
- Fix sysfs handling of block:sdX and scsi bus changes
- Only autobind to ifaces with transport = tcp
- Increase login retry for iscsistart.
- Sync kernel modules to scsi-misc for 2.6.27.
- Update 2.6.14 - 2.6.19 compat patch
- Update 2.6.20 - 2.6.24 patch
- Update 2.6.24 - 2.6.25 patch
- iscsid: don't print enosys errors.
- libiscsi: support older tools that did not set can_queue/cmds_max
- Fix transport_name compat support.
- Fix idbm iscsid segfault when accsing ifaces
- Fix discovery and autobinding
- fix ipv6 login redirect support.
- Fix login redirect failure handling.
- remove sysfs_file
- fix dynamic tpgt support.
- Bump version for new release.
- Add compat patch for RHEL 5.2
- iscsid: adjust requested settings for user
- Sync kernel modules with 2.6.27
- Add 2.6.26 compat support
- Add Makefile support for 2.6.26 compat patch
- Add .gitignore files
- Revert broken SLES 10 compat patch.
- iscsi conf: increase default login max
- iscsi conf: partially revert increase default login max change
- modify initial login retry max
- libiscsi: fix data corruption when target has to resend data-in packets
- iscsi class: fix endpoint id handling
- handle ISCSI_ERR_INVALID_HOST
- iscsi_tcp: return a descriptive error value during connection errors
- libiscsi: fix locking in iscsi_eh_device_reset
- update 2.6.14-19_compat.patch
- update 2.6.20-21_compat.patch
- update 2.6.24_compat.patch
- Fix initiator.c compile warning
+Hannes Reinecke (2):
+ Allow update of discovery records.
+ Update 2.6.27_compat.patch for SLES 11
+
+Mike Christie (91):
+ Don't kill iscsid if logout from all nodes fail
+ iscsid: fix ISCSI_ERR_INVALID_HOST err handling
+ iscsid: add flag to indicate if driver needs iscsid to set ip
+ iscsid: add be2iscsi template
+ iscsid be2iscsi: add more driver limits
+ iscsid: start iscsid automatically when needed
+ iscsid: fix segfault during session sync up
+ iscsiadm: fix discovery record use
+ iscsi mod: sync to linux-2.6-iscsi tree's 2.6.33 feature window patches
+ iscsid: handle new replacement_timeout values
+ iscsi tools: support tgt reset timeout
+ iscsi-iname: fix misleading help description
+ iscsid: fix iferror log message
+ iscsi mod: Update 2.6.14-23_compat.patch patch
+ iscsiadm: fix login/logout message
+ do not use a semarg in shared-mem for semop calls
+ Fix wrong logs in log.c
+ update 2.6.26 compat patch
+ iscsi tools: Allow empty username for CHAP
+ iscsi ibft/boot: fix net dev loopup
+ iscsistart option to bring up NICs using configuration in iBFT.
+ ibft boot: mv setup nics to fw_entry.c so iscsiadm can use it
+ iscsistart ibft: fix fwparam network cmd
+ iscsid be2iscsi: don't set set_host_ip
+ iscsi tools: merge functions to get net iface name from mac address
+ ibft boot: do not setup nic if offload can be used
+ iscsistart ibft boot: setup iscsi offload during boot
+ ibft boot: remove be2iscsi
+ iscsi tools: idbm/fw function cleanup
+ iscsi tool: trivial fixes
+ ibft boot: add offload ibft support to iscsiadm
+ iscsiadm: only do auto iface setup when iface mode is run
+ ibft boot: add iscsiadm offload ibft rec support
+ doc: add iscsistart man page
+ doc: add iscsi-iname man page
+ ibft boot: fix dev to iface matching
+ offload boot: turn off
+ iscsi tools: nic setup cleanup
+ iscsi tools: fix compile errors
+ iscsi kern: fix 2.6.27 compat patch
+ iscsiadm: add nonpersistent mode to discovery mode
+ iscsi tool: mv idbm_node_setup_defaults to idbm.c
+ iscsi tools: cleanup get_global_string_param use
+ iscsi tools: make config file parser a little smarter.
+ iscsiadm: mv session management functions to new file
+ st discovery: fix reopen max handling
+ iscsid: have iscsid watch for new portals using sendtargets
+ iscsi tools: mv iscsid request helpers to its own file
+ iscsi tools: add str prefix to strings.c functions
+ iscsi tools: use open-isns services
+ iscsi tools: add MaxXmitDataSegmentLength param
+ iscsi tools: do not exit on mem alloc failures during discovery
+ Fix makefile cleanup
+ iscsid: add isns discovery daemon and SCN support
+ iscsid: support discovery daemon auto logout
+ isns: fix compilation
+ iscsi tools: fix null sysfs string handling
+ iscsi tools: fix compilation on s390
+ Update version number to 872
+ iscsi tools: fix MaxXmitDataSegmentLength=0 handling
+ be2iscsi iscsi tool: fix MaxXmitDataSegmentLength handling
+ iscsi tools: be2iscsi: fix initial_r2t_en handling
+ iscsi tools: prep for userspace libiscsi
+ iscsi tools: add log_info helper
+ iscsi tools: fix port handling for iscsiadm commands
+ iscsi tools: fix port handling for iscsiadm commands take 2
+ iscsid: fix discoveryd shutdown
+ iscsi scripts: use iscsiadm -k to shutdown daemon
+ iscsiadm: fix discovery record management
+ iscsid: fix sendtargets discovery daemon CHAP handling
+ iscsiadm: mv disc code to new function
+ iscsiadm: fix disc port handling
+ iscsiadm: add new discovery mode
+ iscsiadm: add isns db support
+ iscsiadm: cleanup default port handling
+ iscsid: use isns discovery rec for isns discoveryd setttings
+ iscsiadm: fix iface mode ENODEV handling
+ iscsiadm: mark discovery mode as depreciated
+ sync to upstream
+ 2.6.33 - 34 kernel compat patch
+ 2.6.28 - 32 kernel compat patch
+ 2.6.27 kernel compat patch
+ 2.6.26 kernel compat patch
+ 2.6.24 - 25 kernel compat patch
+ 2.6.14 - 23 kernel compat patch
+ iscsiadm: fix discovery2 db op return value
+ iscsiadm: print isns recs in discovery mode
+ iscsi boot: add support for iscsi boot sysfs module
+ iscsiadm: rename discovery2 mode as discoverydb
+ iscsiadm: fix boot code compile error
+ iscsiadm: fix iface update/delete return value fix
+
+Ritesh Raj Sarraf (3):
+ fix some spelling errors reported by lintian
+ minor manpage updates
+ Fix CVE-2009-1297
+
+Wulf C. Krueger (1):
+ Use DESTDIR when generating an InitiatorName.
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/doc/iscsiadm.8 open-iscsi-2.0-872-rc4-bnx2i.work/doc/iscsiadm.8
--- open-iscsi-2.0-872-rc4-bnx2i/doc/iscsiadm.8 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/doc/iscsiadm.8 2012-03-05 23:02:46.000000000 -0600
@@ -10,13 +10,13 @@ iscsiadm \- open-iscsi administration ut
\fBiscsiadm\fR \-m node [ \-hV ] [ \-d debug_level ] [ \-P printlevel ] [ \-L all,manual,automatic ] [ \-U all,manual,automatic ] [ \-S ] [ [ \-T targetname \-p ip:port \-I iface ] [ \-l | \-u | \-R | \-s] ]
[ [ \-o operation ] [ \-n name ] [ \-v value ] [ \-p ip:port ] ]
-\fBiscsiadm\fR \-m session [ \-hV ] [ \-d debug_level ] [ \-P printlevel ] [ \-r sessionid | sysfsdir [ \-R ] [ \-u | \-s ] ]
+\fBiscsiadm\fR \-m session [ \-hV ] [ \-d debug_level ] [ \-P printlevel ] [ \-r sessionid | sysfsdir [ \-R ] [ \-u | \-s | \-o new ] ]
-\fBiscsiadm\fR \-m iface [ \-hV ] [ \-d debug_level ] [ \-P printlevel ] [ \-I ifacename ] [ [ \-o operation ] [ \-n name ] [ \-v value ] ]
+\fBiscsiadm\fR \-m iface [ \-hV ] [ \-d debug_level ] [ \-P printlevel ] [ \-I ifacename | \-H hostno|MAC ] [ [ \-o operation ] [ \-n name ] [ \-v value ] ]
\fBiscsiadm\fR \-m fw [\-l]
-\fBiscsiadm\fR \-m host [ \-P printlevel ] [ \-H hostno ]
+\fBiscsiadm\fR \-m host [ \-P printlevel ] [ \-H hostno|MAC ]
\fBiscsiadm\fR \-k priority
@@ -49,7 +49,13 @@ print debugging information. Valid value
display help text and exit
.TP
-\fB\-I\fR, \fB\-\-interface\fI[iface]\fR
+\fB\-H\fR, \fB\-\-host=\fI[hostno|MAC]\fR
+The host agrument specifies the SCSI host to use for the operation. It can be
+the scsi host number assigned to the host by the kernel's scsi layer, or the
+MAC address of a scsi host.
+
+.TP
+\fB\-I\fR, \fB\-\-interface=\fI[iface]\fR
The interface argument specifies the iSCSI interface to use for the operation.
iSCSI interfaces (iface) are defined in /etc/iscsi/ifaces. For hardware
iSCSI (qla4xxx) the iface config must have the hardware address
@@ -141,6 +147,8 @@ operator.
Specifies a database operator \fIop\fR. \fIop\fR must be one of
\fInew\fR, \fIdelete\fR, \fIupdate\fR, \fIshow\fR or \fInonpersistent\fR.
.IP
+For iface mode, \fIapply\fR and \fIapplyall\fR are also applicable.
+.IP
This option is valid for all modes except fw. Delete should not be used on a running session. If it is iscsiadm will stop the session and then delete the
record.
.IP
@@ -148,7 +156,8 @@ record.
\fIrecid\fR is the target name and portal (IP:port). In iface mode, the \fIrecid\fR
is the iface name. In discovery mode, the \fIrecid\fR is the portal and
discovery type.
-
+.IP
+In session mode, the \fInew\fR operation logs in a new session using the same node database and iface information as the specified session.
.IP
In discovery mode, if the \fIrecid\fR and new operation is passed in, but the \fI--discover\fR argument is not, then iscsiadm will only create a discovery record (it will not perform discovery). If the \fI--discover\fR argument is passed in with the portal and discovery type, then iscsiadm will create the discovery record if needed, and it will create records for portals returned by the target that do not yet have a node DB record.
.IP
@@ -163,10 +172,22 @@ sid is passed in.
.IP
\fInonpersistent\fR instructs iscsiadm to not manipulate the node DB.
+.IP
+\fIapply\fR will cause the network settings to take effect on the specified iface.
+
+.IP
+\fIapplyall\fR will cause the network settings to take effect on all the ifaces whose MAC address or host number matches that of the specific host.
+
.TP
\fB\-p\fR, \fB\-\-portal=\fIip[:port]\fR
-Use target portal with ip-address \fIip\fR and \fIport\fR, the default
-\fIport\fR value is 3260.
+Use target portal with ip-address \fIip\fR and \fIport\fR. If port is not passed
+in the default \fIport\fR value is 3260.
+.IP
+IPv6 addresses can bs specified as [ddd.ddd.ddd.ddd]:port or
+ddd.ddd.ddd.ddd.
+.IP
+Hostnames can also be used for the ip argument.
+
.IP
This option is only valid for discovery, or for node operations with
the \fInew\fR operator.
@@ -294,6 +315,152 @@ or
SendTargets (st)
discovery type. An SLP implementation is under development.
+.SH EXIT STATUS
+
+On success 0 is returned. On error one of the return codes below will
+be returned.
+
+Commands that operation on multiple objects (sessions, records, etc),
+iscsiadm/iscsistart will return the first error that is encountered.
+iscsiadm/iscsistart will attempt to execute the operation on the objects it
+can. If no objects are found ISCSI_ERR_NO_OBJS_FOUND is returned.
+
+
+.TP
+.B
+0
+ISCSI_SUCCESS - command executed successfully.
+
+.TP
+.B
+1
+ISCSI_ERR - generic error code.
+
+.TP
+.B
+2
+ISCSI_ERR_SESS_NOT_FOUND - session could not be found.
+
+.TP
+.B
+3
+ISCSI_ERR_NOMEM - could not allocate resource for operation.
+.TP
+.B
+4
+ISCSI_ERR_TRANS - connect problem caused operation to fail.
+
+.TP
+.B
+5
+ISCSI_ERR_LOGIN - generic iSCSI login failure.
+
+.TP
+.B
+6
+ISCSI_ERR_IDBM - error accessing/managing iSCSI DB.
+
+.TP
+.B
+7
+ISCSI_ERR_INVAL - invalid argument.
+
+.TP
+.B
+8
+ISCSI_ERR_TRANS_TIMEOUT - connection timer exired while trying to connect.
+
+.TP
+.B
+9
+ISCSI_ERR_INTERNAL - generic internal iscsid/kernel failure.
+
+.TP
+.B
+10
+ISCSI_ERR_LOGOUT - iSCSI logout failed.
+
+.TP
+.B
+11
+ISCSI_ERR_PDU_TIMEOUT - iSCSI PDU timedout.
+
+.TP
+.B
+12
+ISCSI_ERR_TRANS_NOT_FOUND - iSCSI transport module not loaded in kernel or iscsid.
+
+.TP
+.B
+13
+ISCSI_ERR_ACCESS - did not have proper OS permissions to access iscsid or execute iscsiadm command.
+
+.TP
+.B
+14
+ISCSI_ERR_TRANS_CAPS - transport module did not support operation.
+
+.TP
+.B
+15
+ISCSI_ERR_SESS_EXISTS - session is logged in.
+
+.TP
+.B
+16
+ISCSI_ERR_INVALID_MGMT_REQ - invalid IPC MGMT request.
+
+.TP
+.B
+17
+ISCSI_ERR_ISNS_UNAVAILABLE - iSNS service is not supported.
+
+.TP
+.B
+18
+ISCSI_ERR_ISCSID_COMM_ERR - a read/write to iscsid failed.
+
+.TP
+.B
+19
+ISCSI_ERR_FATAL_LOGIN - fatal iSCSI login error.
+
+.TP
+.B
+20
+ISCSI_ERR_ISCSID_NOTCONN - could ont connect to iscsid.
+
+.TP
+.B
+21
+ISCSI_ERR_NO_OBJS_FOUND - no records/targets/sessions/portals found to execute operation on.
+
+.TP
+.B
+22
+ISCSI_ERR_SYSFS_LOOKUP - could not lookup object in sysfs.
+
+.TP
+.B
+23
+ISCSI_ERR_HOST_NOT_FOUND - could not lookup host.
+
+.TP
+.B
+24
+ISCSI_ERR_LOGIN_AUTH_FAILED - login failed due to authorization failure.
+
+.TP
+.B
+25
+ISCSI_ERR_ISNS_QUERY - iSNS query failure.
+
+.TP
+.B
+26
+ISCSI_ERR_ISNS_REG_FAILED - iSNS registration/deregistration failed.
+
+
.SH EXAMPLES
.nf
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/doc/iscsid.8 open-iscsi-2.0-872-rc4-bnx2i.work/doc/iscsid.8
--- open-iscsi-2.0-872-rc4-bnx2i/doc/iscsid.8 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/doc/iscsid.8 2012-03-05 23:02:46.000000000 -0600
@@ -35,6 +35,9 @@ run under user ID \fIuid\fR (default is
.BI [-g|--gid=]\fIgid\fP
run under user group ID \fIgid\fR (default is the current user group ID).
.TP
+.BI [-n|--no-pid-file]\fP
+do not write a process ID file.
+.TP
.BI [-p|--pid=]\fIpid\-file\fP
write process ID to \fIpid\-file\fR rather than the default
\fI/var/run/iscsid.pid\fR
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/doc/iscsistart.8 open-iscsi-2.0-872-rc4-bnx2i.work/doc/iscsistart.8
--- open-iscsi-2.0-872-rc4-bnx2i/doc/iscsistart.8 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/doc/iscsistart.8 2012-03-05 23:06:00.000000000 -0600
@@ -51,6 +51,10 @@ Bring up the network as specified by iBF
.BI [-f|--fwparam_print]
Print the iBFT or OF info to STDOUT
.TP
+.BI [-P|--param=]\fINAME=VALUE\fP
+Set the parameter with the name NAME to VALUE. NAME is one of the settings
+in the node record or iscsid.conf. Multiple params can be passed in.
+.TP
.BI [-h|--help]
Display this help and exit
.TP
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/etc/iface.example open-iscsi-2.0-872-rc4-bnx2i.work/etc/iface.example
--- open-iscsi-2.0-872-rc4-bnx2i/etc/iface.example 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/etc/iface.example 2012-03-05 23:02:46.000000000 -0600
@@ -60,3 +60,138 @@
# the same subnet.
# iface.net_ifacename = eth0
# iface.ipaddress = 102.50.50.101
+
+# OPTIONAL: iface.bootproto
+#
+# Valid values are:
+# "dhcp" and "static"
+#
+# REQUIRED when IPv4 address need to be obtained dynamically using DHCP
+# example:
+# iface.bootproto = dhcp
+#
+# OPTIONAL when the IPv4 address is set statically
+# example:
+# iface.ipaddress = 102.50.50.101
+# iface.bootproto = static
+#
+
+# OPTIONAL: iface.vlan_id
+# Used to set the VLAN ID for the iSCSI interfae.
+# example
+# iface.vlan_id = 1022
+
+# OPTIONAL: iface.vlan_priority
+# Used to set the VLAN priority for the iSCSI interfae.
+# example
+# iface.vlan_priority = 1
+
+# OPTIONAL: iface.vlan_state
+# Used to enable or disable the VLAN on the iSCSI interface
+# example
+# iface.vlan_state = enable
+
+# OPTIONAL: iface.ipv6_linklocal
+# Specify the IPV6 Link Local Address with the
+# link local prefix of FE80::0/64
+# example:
+# iface.ipv6_linklocal = fe80:0000:0000:0000:020e:1eff:1111:2221
+
+# OPTIONAL: iface.ipv6_router
+# Used to set a default IPV6 router
+# example:
+# iface.ipv6_router = fe80:0000:0000:0000:7ae7:d1ff:fe72:4048
+
+# OPTIONAL: iface.ipv6_autocfg
+# Used to set the discovery protocol to obtain IPV6 address
+# For example qla4xxx support neighbor discovery
+# example:
+# iface.ipv6_autocfg = nd
+
+# OPTIONAL: iface.linklocal_autocfg
+# For transport like qla4xxx this allows to auto configure the
+# IPV6 link local address based on the MAC address of the iSCSI
+# interface
+
+# OPTIONAL: iface.router_autocfg
+# Required to set the IPv6 router discovery protocol
+# To set the router discovery protocol to Neighbor Discovery specify "nd"
+# example:
+# iface.router_autocfg = nd
+
+# OPTIONAL: iface.state
+# By default the iface is enabled
+# iface.state = enable
+# To disable the iface set the state to "disable"
+# iface.state = disable
+
+# iface.iface_num
+# REQUIRED: When there are more than 1 interface to be configured.
+# For transports like qla4xxx, one can specify two IPV6 interfaces
+# in such case the iface_num must be set correctly
+# example:
+# iface settings for first IPV6 interface
+# iface.iscsi_ifacename = iface-qla4xxx-ipv6-1
+# iface.iface_num = 0
+#
+# iface settings for second IPV6 interface
+# iface.iscsi_ifacename = iface-qla4xxx-ipv6-2
+# iface.iface_num = 1
+
+# Here are some example iface files
+# IPV4 sample config file with static IP address:
+# BEGIN RECORD 2.0-872
+# iface.iscsi_ifacename = qla4xxx-3
+# iface.ipaddress = 192.168.1.75
+# iface.hwaddress = 00:0e:1e:04:93:92
+# iface.transport_name = qla4xxx
+# iface.bootproto = static
+# iface.subnet_mask = 255.255.255.0
+# iface.gateway = 192.168.1.1
+# iface.state = enable
+# iface.vlan = <empty>
+# iface.iface_num = 0
+# END RECORD
+#
+# IPV6 sample config file with neighbor discovery:
+# BEGIN RECORD 2.0-872
+# iface.iscsi_ifacename = qla4xxx-3-1
+# iface.ipaddress =
+# iface.hwaddress = 00:0e:1e:04:93:92
+# iface.transport_name = qla4xxx
+# iface.ipv6_autocfg = nd
+# iface.linklocal_autocfg = auto
+# iface.router_autocfg = nd
+# iface.ipv6_linklocal = fe80:0000:0000:0000:020e:1eff:1111:2221
+# iface.ipv6_router = auto
+# iface.state = enable
+# iface.vlan = <empty>
+# iface.iface_num = 0
+# END RECORD
+
+# Ipv4 sample config file (DHCP configuration):
+# BEGIN RECORD 2.0-872
+# iface.iscsi_ifacename = qla4xxx-3
+# iface.hwaddress = 00:0e:1e:04:93:92
+# iface.transport_name = qla4xxx
+# iface.bootproto = dhcp
+# iface.state = enable
+# iface.vlan = <empty>
+# iface.iface_num = 0
+# END RECORD
+
+# Sample ipv6 config file(manual configured IPs):
+# BEGIN RECORD 2.0-872
+# iface.iscsi_ifacename = iface-new-file
+# iface.ipaddress = fec0:ce00:7014:0041:1111:2222:1e04:9392
+# iface.hwaddress = 00:0e:1e:04:93:92
+# iface.transport_name = qla4xxx
+# iface.ipv6_autocfg = <empty>
+# iface.linklocal_autocfg = <empty>
+# iface.router_autocfg = <empty>
+# iface.ipv6_linklocal = fe80:0000:0000:0000:0000:0000:1e04:9392
+# iface.ipv6_router = fe80:0000:0000:0000:7ae7:d1ff:fe72:4048
+# iface.state = enable
+# iface.vlan = <empty>
+# iface.iface_num = 0
+# END RECORD
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/etc/initd/boot.suse open-iscsi-2.0-872-rc4-bnx2i.work/etc/initd/boot.suse
--- open-iscsi-2.0-872-rc4-bnx2i/etc/initd/boot.suse 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/etc/initd/boot.suse 2012-03-05 23:02:46.000000000 -0600
@@ -4,36 +4,37 @@
#
### BEGIN INIT INFO
# Provides: iscsiboot
-# Required-Start: boot.proc
-# Should-Start:
-# Required-Stop:
+# Required-Start:
+# Should-Start: boot.multipath
+# Required-Stop:
# Should-Stop:
# Default-Start: B
# Default-Stop:
-# Short-Description: Starts the iSCSI initiator daemon
-#
+# Short-Description: iSCSI initiator daemon root-fs support
+# Description: Starts the iSCSI initiator daemon if the
+# root-filesystem is on an iSCSI device
+#
### END INIT INFO
ISCSIADM=/sbin/iscsiadm
-PID_FILE=/var/run/iscsi.pid
CONFIG_FILE=/etc/iscsid.conf
DAEMON=/sbin/iscsid
-ARGS="-c $CONFIG_FILE -p $PID_FILE"
+ARGS="-c $CONFIG_FILE"
# Source LSB init functions
. /etc/rc.status
#
-# This service is run right after booting. So all activated targets
-# must be enabled during mkinitrd run and thus should not be removed
-# when the open-iscsi service is stopped.
+# This service is run right after booting. So all targets activated
+# during mkinitrd run should not be removed when the open-iscsi
+# service is stopped.
#
iscsi_mark_root_nodes()
{
$ISCSIADM -m session 2> /dev/null | while read t num i target ; do
ip=${i%%:*}
- STARTUP=`$ISCSIADM -m node -p $ip -T $target | grep "node.conn\[0\].startup" | cut -d' ' -f3`
- if [ "$STARTUP" != "onboot" ] ; then
+ STARTUP=`$ISCSIADM -m node -p $ip -T $target 2> /dev/null | grep "node.conn\[0\].startup" | cut -d' ' -f3`
+ if [ "$STARTUP" -a "$STARTUP" != "onboot" ] ; then
$ISCSIADM -m node -p $ip -T $target -o update -n node.conn[0].startup -v onboot
fi
done
@@ -50,13 +51,12 @@ fi
case "$1" in
start)
- [ ! -d /var/lib/open-iscsi ] && mkdir -p /var/lib/open-iscsi
echo -n "Starting iSCSI initiator for the root device: "
startproc $DAEMON $ARGS
rc_status -v
iscsi_mark_root_nodes
;;
- stop)
+ stop|restart|reload)
rc_failed 0
;;
status)
@@ -68,13 +68,8 @@ case "$1" in
rc_status -v
fi
;;
- restart)
- $0 stop
- sleep 1
- $0 start
- ;;
*)
- echo "Usage: $0 {start|stop|status|restart}"
+ echo "Usage: $0 {start|stop|status|restart|reload}"
exit 1
;;
esac
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/etc/initd/initd.suse open-iscsi-2.0-872-rc4-bnx2i.work/etc/initd/initd.suse
--- open-iscsi-2.0-872-rc4-bnx2i/etc/initd/initd.suse 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/etc/initd/initd.suse 2012-03-05 23:02:46.000000000 -0600
@@ -5,20 +5,22 @@
### BEGIN INIT INFO
# Provides: iscsi
# Required-Start: $network
-# Should-Start:
-# Required-Stop:
-# Should-Stop:
+# Should-Start: iscsitarget multipathd
+# Required-Stop: $network
+# Should-Stop: multipathd
# Default-Start: 3 5
# Default-Stop:
-# Short-Description: Starts and stops the iSCSI client initiator
-#
+# Short-Description: iSCSI initiator daemon
+# Description: The iSCSI initator is used to create and
+# manage iSCSI connections to a iSCSI Target.
+#
### END INIT INFO
-PID_FILE=/var/run/iscsi.pid
CONFIG_FILE=/etc/iscsi/iscsid.conf
DAEMON=/sbin/iscsid
ISCSIADM=/sbin/iscsiadm
-ARGS="-c $CONFIG_FILE -p $PID_FILE"
+BRCM_ISCSIUIO=/sbin/brcm_iscsiuio
+ARGS="-c $CONFIG_FILE -n"
# Source LSB init functions
. /etc/rc.status
@@ -26,66 +28,359 @@ ARGS="-c $CONFIG_FILE -p $PID_FILE"
# Reset status of this service
rc_reset
+DM_MAJOR=$(sed -n 's/\(.*\) device-mapper/\1/p' /proc/devices)
+
iscsi_login_all_nodes()
{
echo -n "Setting up iSCSI targets: "
$ISCSIADM -m node --loginall=automatic 2> /dev/null
- if [ $? == 19 ] ; then
+ if [ $? == 21 ] ; then
rc_failed 6
fi
rc_status -v
}
-iscsi_logout_all_nodes()
+#
+# Try to load all required modules prior to startup
+#
+iscsi_load_transport_modules()
{
- echo -n "Closing all iSCSI connections: "
- # Logout from all sessions marked automatic
- if ! $ISCSIADM -m node --logoutall=automatic 2> /dev/null; then
- if [ $? == 19 ] ; then
- RETVAL=6
- else
- RETVAL=1
+ loaded=$(sed -n "/^iscsi_tcp/p" /proc/modules)
+ if [ -z "$loaded" ] ; then
+ modprobe iscsi_tcp
+ if [ $? = 0 ] ; then
+ echo -n " tcp"
+ fi
+ fi
+
+ for iface in /etc/iscsi/ifaces/*; do
+ [ -f "$iface" ] || continue
+ [ "$iface" = "iface.example" ] && continue
+ # Check if the iface has been configured
+ result=$(sed '/#.*/D;/iface.iscsi_ifacename/D;/iface.hwaddress/D;/iface.transport_name/D' $iface)
+ if [ "$result" ] ; then
+ mod=$(sed -n 's/iface.transport_name *= *\(.*\)/\1/p' $iface)
+ loaded=$(sed -n "/^$mod/p" /proc/modules)
+ if [ -z "$loaded" ] ; then
+ modprobe $mod
+ if [ $? = 0 ] ; then
+ echo -n " $mod"
fi
- rc_failed $RETVAL
+ fi
fi
- rc_status -v
+ done
+}
- # Not sure whether this is still needed
- sleep 1
- return ${RETVAL:-0}
+#
+# Set a temporary startmode for ifdown
+#
+iscsi_modify_if_startmode()
+{
+ local ifname=$1
+ local tmp_ifcfg=/dev/.sysconfig/network/if-$ifname
+
+ if [ -e "$tmp_ifcfg" ] ; then
+ . $tmp_ifcfg
+ if [ "$startmode" ] ; then
+ return
+ fi
+ fi
+ : disabling shutdown on $ifname
+ echo "startmode=nfsroot" >> $tmp_ifcfg
}
-iscsi_umount_all_luns()
+iscsi_get_ifacename_from_session()
{
- local d m dev p s
+ local session=$1
+ local ifacename
- cat /proc/mounts | sed -ne '/^\/dev\/.*/p' | while read d m t o x; do
- if [ "$m" = "/" ] ; then
- continue;
+ ifacename=$(iscsiadm -m session -r ${session##.*/session} 2> /dev/null | \
+ sed -n 's/iface.iscsi_ifacename = \(.*\)/\1/p')
+ if [ -z "$ifacename" ] ; then
+ # Check for iBFT
+ ifacename=$(iscsiadm -m fw 2> /dev/null)
+ if [ -n "$ifacename" ] ; then
+ ifacename="fw"
fi
+ fi
+ echo $ifacename
+}
+
+iscsi_get_hwaddress_from_iface()
+{
+ local iface=$1
+ local hwaddress
+
+ hwaddress=$(iscsiadm -m iface -I "$iface" 2> /dev/null | sed -n 's/iface.hwaddress = \(.*\)/\1/p')
+ [ "$hwaddress" = "<empty>" ] && hwaddress=
+
+ echo $hwaddress
+}
+
+iscsi_get_ifname_from_iface()
+{
+ local iface=$1
+ local ifname
+
+ ifname=$(iscsiadm -m iface -I "$iface" 2> /dev/null | sed -n 's/iface.net_ifacename = \(.*\)/\1/p')
+ [ "$ifname" = "<empty>" ] && ifname=
+
+ echo $ifname
+}
+
+iscsi_get_ipaddr_from_iface()
+{
+ local iface=$1
+ local ipaddr
+
+ ipaddr=$(iscsiadm -m iface -I "$iface" 2> /dev/null | sed -n 's/iface.ipaddress = \(.*\)/\1/p')
+ [ "$ipaddr" = "<empty>" ] && ipaddr=
+
+ echo $ipaddr
+}
+
+iscsi_get_ifname_from_firmware()
+{
+ local hwaddress
+
+ hwaddress=$(iscsiadm -m fw 2> /dev/null | sed -n 's/iface.net_ifacename = \(.*\)/\1/p')
+
+ echo $hwaddress
+}
+
+#
+# cxgb3i is using the HWAddress to select
+# the correct interface
+#
+iscsi_get_ifname_from_hwaddress()
+{
+ local hwaddress=$1
+
+ for if in /sys/class/net/*; do
+ [ -e "$if" ] || continue
+ read mac < $if/address
+ [ "$mac" = "$hwaddress" ] || continue
+ echo ${if##*/}
+ break
+ done
+}
+
+iscsi_get_ifname_from_ipaddr()
+{
+ local ipaddr=$1
+ local ifname
+
+ ifname=$(ip addr show to $ipaddr | sed -n 's/[0-9]*: \([^ :]*\): .*/\1/p')
+ return $ifname
+}
+
+#
+# Handle 'default' interface:
+# It is basically impossible to determine via which
+# interface the iSCSI traffic will flow, so we take
+# the easy option and ignore _all_ active interfaces
+# during shutdown
+#
+iscsi_modify_all_interfaces()
+{
+ ip link show up | sed -n '/.*LOOPBACK.*/d;s/[0-9]*: \(.*\): .*/\1/p' | while read ifname; do
+ iscsi_modify_if_startmode $ifname
+ done
+}
+
+#
+# Check iface setting and disable
+# affected network interfaces
+#
+iscsi_check_interface()
+{
+ local session=$1
+ local i h n
+
+ i=$(iscsi_get_ifacename_from_session $session)
+ [ -z "$i" ] && continue
+ if [ "$i" = "default" ] ; then
+ iscsi_modify_all_interfaces
+ elif [ "$i" = "fw" ] ; then
+ n=$(iscsi_get_ifname_from_firmware)
+ else
+ n=$(iscsi_get_ifname_from_iface $i)
+ if [ -z "$n" ] ; then
+ h=$(iscsi_get_hwaddress_from_iface $i)
+ if [ -n "$h" ] ; then
+ n=$(iscsi_get_ifname_from_hwaddress $h)
+ fi
+ fi
+ if [ -z "$n" ] ; then
+ h=$(iscsi_get_ipaddr_from_iface $i)
+ if [ -n "$h" ] ; then
+ n=$(iscsi_get_ifname_from_ipaddr $h)
+ fi
+ fi
+ fi
+ if [ "$n" ] ; then
+ iscsi_modify_if_startmode $n
+ fi
+}
+
+#
+# Check if device 'dev' is mounted
+# Returns the mount point on success
+#
+iscsi_check_if_mounted()
+{
+ local dev=$1
+ local d m t o x p
+
+ cat /proc/mounts | sed -ne '/^\/dev\/.*/p' | while read d m t o x; do
if [ -L "$d" ] ; then
d=$(readlink -f $d)
fi
- dev=${d##/dev}
+ [ -b "$d" ] || continue
+
+ b=$(ls -l $d | sed -n 's/.* \([0-9]*\), \([0-9]*\) .*/\1:\2/p')
+ p=$(cd -P /sys/dev/block/$b ; echo $PWD)
+
+ if [ -z "$p" ] ; then
+ d=${d##/dev}
+ p="/sys/block${d%%[0-9]*}"
+ fi
+
+ [ ! -d ${p} ] && continue
+
+ if [ -e $p/partition ] ; then
+ p=$(cd -P $p/../; echo $PWD)
+ fi
+ if [ "$dev" = "${p##*/}" ] ; then
+ echo $m
+ fi
+ done
+}
+
+#
+# Unwind block device stack
+#
+# Stops unwinding if either no more 'holders'
+# are found or if a device is mounted
+#
+# Unmounts top-level device and deconfigures
+# all devices down the stack
+#
+# Root fs is not unmounted
+#
+iscsi_unwind_stack()
+{
+ local p=$1
+ local d=${p##*/}
+ local u
+ local m
+
+ if [ ! -d ${p} ] ; then
+ return;
+ fi
+
+ m=$(iscsi_check_if_mounted $d)
+ if [ -z "$m" ] ; then
+ for s in $p/holders/* ; do
+ [ -e $s ] || continue
+ p=$(cd -P $s; echo $PWD)
+ u=$(iscsi_unwind_stack $p)
+ if [ "$u" ] ; then
+ echo -n "$u "
+ fi
+ done
+ else
+ if [ "$m" = "/" ] ; then
+ echo -n "$d "
+ return 1
+ fi
+ if ! umount $m ; then
+ echo -n "$d "
+ return 1
+ fi
+ fi
- if [ "${dev##/sd}" = "$dev" ] ; then
- continue;
+ if [ "${d#dm-}" != "$d" ] ; then
+ if ! dmsetup remove -j $DM_MAJOR -m ${d#dm-} 2> /dev/null ; then
+ echo -n "$d "
+ return 1
fi
- p="/sys/block${dev%%[0-9]*}"
+ fi
- if [ ! -d ${p} ] && [ ! -d ${p}/device ] ; then
- continue;
+ if [ "${d#md}" != "$d" ] ; then
+ if ! mdadm --manage /dev/$d --stop 2> /dev/null ; then
+ echo -n "$d "
+ return 1
fi
+ fi
+ return 0
+}
+
+#
+# Return all targets for a given session
+#
+iscsi_get_target()
+{
+ local session=$1
+ local d
+
+ for d in $session/device/target* ; do
+ [ -e "$d" ] || continue
+ echo "$d"
+ done
+}
+
+#
+# Checks all devices presented by a target
+# and tries to umount them.
+# Skip unmounting for the root fs.
+# Stops on the first device which could not be unmounted
+# and returns the mount device of that device.
+#
+iscsi_check_target()
+{
+ local t=$1
+ local d b m
- s=$(cd -P ${p}/device && echo $PWD)
+ for d in $t/* ; do
+ [ -d $d/block ] || continue
+ for b in $d/block/sd* ; do
+ [ -d "$b" ] || continue
+ m=$(iscsi_unwind_stack $b)
+ if [ -n "$m" ] ; then
+ echo $m
+ return 1
+ fi
+ done
+ done
+}
- case "$s" in
- */session[0-9]*/*)
- # This is an iSCSI device
- umount "$m"
- ;;
- esac
+#
+# Check all sessions for mounted devices
+# and shutdown the session if the affected
+# devices could be umounted cleanly.
+# If umount fails disable shutdown on all
+# affected network interfaces
+#
+iscsi_stop_sessions()
+{
+ local t m s i
+
+ i=0
+ for session in /sys/class/iscsi_session/session* ; do
+ [ -e "$session" ] || continue;
+ [ -e $session/device ] || continue
+ t=$(iscsi_get_target $session)
+ m=$(iscsi_check_target $t)
+ s=${session##*/session}
+ if [ -z "$m" ] ; then
+ iscsiadm -m session -r ${s} -u
+ i=$(( $i + 1 ))
+ else
+ iscsi_check_interface $s
+ fi
done
+ echo $i
}
iscsi_list_all_nodes()
@@ -101,84 +396,45 @@ iscsi_list_all_nodes()
done
}
-iscsi_discover_all_targets()
-{
- # Strip off any existing ID information
- RAW_NODE_LIST=`iscsiadm -m node | sed -nre 's/^(\[[0-9a-f]*\] )?(.*)$/\2/p'`
- # Obtain IPv4 list
- IPV4_NODE_LIST=`echo "$RAW_NODE_LIST" | sed -nre 's/^([0-9]{1,3}(\.[0-9]{1,3}){3}):[^: ]* (.*)$/\1 \3/p'`
- # Now obtain IPv6 list
- IPV6_NODE_LIST=`echo "$RAW_NODE_LIST" | sed -nre 's/^([0-9a-f]{1,4}(:[0-9a-f]{0,4}){6}:[0-9a-f]{1,4}):[^: ]* (.*)$/\1 \3/p'`
-
- DISC_TARGETS=""
- while read NODE_ADDR NODE_NAME; do
- [ -z "$NODE_ADDR" -a -z "$NODE_NAME" ] && continue
- NODE_ATTRS=`iscsiadm -m node -p "$NODE_ADDR" -T "$NODE_NAME"`
- NODE_STATUS=`echo "$NODE_ATTRS" | sed -nre 's/^.*node\.conn\[0\]\.startup = ([a-z]*).*$/\1/p'`
-
- if [ "$NODE_STATUS" == 'automatic' ]; then
- DISC_TARGETS=`echo "$DISC_TARGETS" | sed -re '/'"$NODE_ADDR"'/!{s/(.*)/\1 '"$NODE_ADDR"'/}'`
- fi
- done < <(echo "$IPV4_NODE_LIST"; echo "$IPV6_NODE_LIST")
-
- for TARGET_ADDR in $DISC_TARGETS; do
- echo -n "Attempting discovery on target at ${TARGET_ADDR}: "
- iscsiadm -m discovery -t st -p "$TARGET_ADDR" > /dev/null 2>&1
- if [ "$?" -ne 0 ]; then
- rc_failed 1
- rc_status -v
- return 1
- fi
- rc_status -v
- done
-}
-
case "$1" in
start)
- [ ! -d /var/lib/iscsi ] && mkdir -p /var/lib/iscsi
if checkproc $DAEMON ; then
RETVAL=0
else
echo -n "Starting iSCSI initiator service: "
- modprobe iscsi_tcp
- modprobe -q ib_iser
+ iscsi_load_transport_modules
+ if grep -q bnx2i /proc/modules && [ -x $BRCM_ISCSIUIO ] ; then
+ startproc $BRCM_ISCSIUIO
+ fi
startproc $DAEMON $ARGS
RETVAL=$?
rc_status -v
fi
if [ "$RETVAL" == "0" ]; then
- iscsi_discover_all_targets
- RETVAL=$?
- fi
- if [ "$RETVAL" == "0" ]; then
iscsi_login_all_nodes
fi
;;
stop)
- iscsi_umount_all_luns
- if iscsi_logout_all_nodes ; then
- iscsiadm -k 0
- RETVAL=$?
- else
- RETVAL=1
- fi
+ n=$(iscsi_stop_sessions)
echo -n "Stopping iSCSI initiator service: "
- if [ "$RETVAL" == "0" ]; then
- rm -f $PID_FILE
- status=0
- modprobe -r iscsi_tcp
- if [ "$?" -ne "0" -a "$?" -ne "1" ]; then
- status=1
- fi
- modprobe -q -r ib_iser
- if [ "$?" -ne "0" -a "$?" -ne "1" ]; then
- status=1
- fi
- rc_failed $status
- else
+ if [ "$n" ] && [ "$n" != "0" ] ; then
+ m=$(iscsiadm -m session 2> /dev/null)
+ if [ -z "$m" ] ; then
+ killproc -KILL $DAEMON
+ RETVAL=$?
+ if grep -q bnx2i /proc/modules && [ -x $BRCM_ISCSIUIO ]; then
+ killproc -KILL $BRCM_ISCSIUIO
+ fi
+ RETVAL=$?
+ else
+ RETVAL=1
+ fi
rc_failed $RETVAL
+ rc_status -v
+ else
+ # umounting failed, leave initiator running
+ rc_status -s
fi
- rc_status -v
;;
status)
echo -n "Checking for iSCSI initiator service: "
@@ -190,7 +446,7 @@ case "$1" in
rc_status -v
fi
;;
- restart)
+ restart|reload)
$0 stop
RETVAL=$?
if [ "$RETVAL" != "0" ]; then
@@ -201,7 +457,7 @@ case "$1" in
$0 start
;;
*)
- echo "Usage: $0 {start|stop|status|restart}"
+ echo "Usage: $0 {start|stop|status|restart|reload}"
exit 1
;;
esac
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/etc/iscsid.conf open-iscsi-2.0-872-rc4-bnx2i.work/etc/iscsid.conf
--- open-iscsi-2.0-872-rc4-bnx2i/etc/iscsid.conf 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/etc/iscsid.conf 2012-03-05 23:02:46.000000000 -0600
@@ -39,6 +39,10 @@ iscsid.startup = /sbin/iscsid
# To manually startup the session set to "manual". The default is manual.
node.startup = manual
+# For "automatic" startup nodes, setting this to "Yes" will try logins on each
+# available iface until one succeeds, and then stop. The default "No" will try
+# logins on all availble ifaces simultaneously.
+node.leading_login = No
# *************
# CHAP Settings
@@ -278,6 +282,11 @@ discovery.sendtargets.iscsi.MaxRecvDataS
# The default is to never use DataDigests or HeaderDigests.
#
+# For multipath configurations, you may want more than one session to be
+# created on each iface record. If node.session.nr_sessions is greater
+# than 1, performing a 'login' for that node will ensure that the
+# appropriate number of sessions is created.
+node.session.nr_sessions = 1
#************
# Workarounds
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/include/iscsi_err.h open-iscsi-2.0-872-rc4-bnx2i.work/include/iscsi_err.h
--- open-iscsi-2.0-872-rc4-bnx2i/include/iscsi_err.h 1969-12-31 18:00:00.000000000 -0600
+++ open-iscsi-2.0-872-rc4-bnx2i.work/include/iscsi_err.h 2012-03-05 23:02:46.000000000 -0600
@@ -0,0 +1,69 @@
+/*
+ * Return codes used by iSCSI tools.
+ */
+#ifndef _ISCSI_ERR_
+#define _ISCSI_ERR_
+
+enum {
+ ISCSI_SUCCESS = 0,
+ /* Generic error */
+ ISCSI_ERR = 1,
+ /* session could not be found */
+ ISCSI_ERR_SESS_NOT_FOUND = 2,
+ /* Could not allocate resource for operation */
+ ISCSI_ERR_NOMEM = 3,
+ /* Transport error caused operation to fail */
+ ISCSI_ERR_TRANS = 4,
+ /* Generic login failure */
+ ISCSI_ERR_LOGIN = 5,
+ /* Error accessing/managing iSCSI DB */
+ ISCSI_ERR_IDBM = 6,
+ /* Invalid argument */
+ ISCSI_ERR_INVAL = 7,
+ /* Connection timer exired while trying to connect */
+ ISCSI_ERR_TRANS_TIMEOUT = 8,
+ /* Generic internal iscsid failure */
+ ISCSI_ERR_INTERNAL = 9,
+ /* Logout failed */
+ ISCSI_ERR_LOGOUT = 10,
+ /* iSCSI PDU timedout */
+ ISCSI_ERR_PDU_TIMEOUT = 11,
+ /* iSCSI transport module not loaded in kernel or iscsid */
+ ISCSI_ERR_TRANS_NOT_FOUND = 12,
+ /* Permission denied */
+ ISCSI_ERR_ACCESS = 13,
+ /* Transport module did not support operation */
+ ISCSI_ERR_TRANS_CAPS = 14,
+ /* Session is logged in */
+ ISCSI_ERR_SESS_EXISTS = 15,
+ /* Invalid IPC MGMT request */
+ ISCSI_ERR_INVALID_MGMT_REQ = 16,
+ /* iSNS service is not supported */
+ ISCSI_ERR_ISNS_UNAVAILABLE = 17,
+ /* A read/write to iscsid failed */
+ ISCSI_ERR_ISCSID_COMM_ERR = 18,
+ /* Fatal login error */
+ ISCSI_ERR_FATAL_LOGIN = 19,
+ /* Could ont connect to iscsid */
+ ISCSI_ERR_ISCSID_NOTCONN = 20,
+ /* No records/targets/sessions/portals found to execute operation on */
+ ISCSI_ERR_NO_OBJS_FOUND = 21,
+ /* Could not lookup object in sysfs */
+ ISCSI_ERR_SYSFS_LOOKUP = 22,
+ /* Could not lookup host */
+ ISCSI_ERR_HOST_NOT_FOUND = 23,
+ /* Login failed due to authorization failure */
+ ISCSI_ERR_LOGIN_AUTH_FAILED = 24,
+ /* iSNS query failure */
+ ISCSI_ERR_ISNS_QUERY = 25,
+ /* iSNS registration/deregistration failed */
+ ISCSI_ERR_ISNS_REG_FAILED = 26,
+
+ /* Always last. Indicates end of error code space */
+ ISCSI_MAX_ERR_VAL,
+} iscsi_err;
+
+extern void iscsi_err_print_msg(int err);
+extern char *iscsi_err_to_str(int err);
+
+#endif
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/include/iscsi_if.h open-iscsi-2.0-872-rc4-bnx2i.work/include/iscsi_if.h
--- open-iscsi-2.0-872-rc4-bnx2i/include/iscsi_if.h 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/include/iscsi_if.h 2012-03-05 23:06:18.000000000 -0600
@@ -64,6 +64,9 @@ enum iscsi_uevent_e {
ISCSI_UEVENT_TRANSPORT_EP_CONNECT_THROUGH_HOST = UEVENT_BASE + 19,
ISCSI_UEVENT_PATH_UPDATE = UEVENT_BASE + 20,
+ ISCSI_UEVENT_SET_IFACE_PARAMS = UEVENT_BASE + 21,
+
+ ISCSI_UEVENT_MAX = ISCSI_UEVENT_SET_IFACE_PARAMS,
/* up events */
ISCSI_KEVENT_RECV_PDU = KEVENT_BASE + 1,
@@ -75,6 +78,10 @@ enum iscsi_uevent_e {
ISCSI_KEVENT_PATH_REQ = KEVENT_BASE + 7,
ISCSI_KEVENT_IF_DOWN = KEVENT_BASE + 8,
+ ISCSI_KEVENT_CONN_LOGIN_STATE = KEVENT_BASE + 9,
+ ISCSI_KEVENT_HOST_EVENT = KEVENT_BASE + 10,
+
+ ISCSI_KEVENT_MAX = ISCSI_KEVENT_HOST_EVENT,
};
enum iscsi_tgt_dscvr {
@@ -83,6 +90,13 @@ enum iscsi_tgt_dscvr {
ISCSI_TGT_DSCVR_SLP = 3,
};
+enum iscsi_host_event_code {
+ ISCSI_EVENT_LINKUP = 1,
+ ISCSI_EVENT_LINKDOWN,
+ /* must always be last */
+ ISCSI_EVENT_MAX,
+};
+
struct iscsi_uevent {
uint32_t type; /* k/u events type */
uint32_t iferror; /* carries interface or resource errors */
@@ -177,6 +191,10 @@ struct iscsi_uevent {
struct msg_set_path {
uint32_t host_no;
} set_path;
+ struct msg_set_iface_params {
+ uint32_t host_no;
+ uint32_t count;
+ } set_iface_params;
} u;
union {
/* messages k -> u */
@@ -198,6 +216,11 @@ struct iscsi_uevent {
uint32_t cid;
uint64_t recv_handle;
} recv_req;
+ struct msg_conn_login {
+ uint32_t sid;
+ uint32_t cid;
+ uint32_t state; /* enum iscsi_conn_state */
+ } conn_login;
struct msg_conn_error {
uint32_t sid;
uint32_t cid;
@@ -216,9 +239,29 @@ struct iscsi_uevent {
struct msg_notify_if_down {
uint32_t host_no;
} notify_if_down;
+ struct msg_host_event {
+ uint32_t host_no;
+ uint32_t data_size;
+ enum iscsi_host_event_code code;
+ } host_event;
} r;
} __attribute__ ((aligned (sizeof(uint64_t))));
+enum iscsi_param_type {
+ ISCSI_PARAM, /* iscsi_param (session, conn, target, LU) */
+ ISCSI_HOST_PARAM, /* iscsi_host_param */
+ ISCSI_NET_PARAM, /* iscsi_net_param */
+};
+
+struct iscsi_iface_param_info {
+ uint32_t iface_num; /* iface number, 0 - n */
+ uint32_t len; /* Actual length of the param */
+ uint16_t param; /* iscsi param value */
+ uint8_t iface_type; /* IPv4 or IPv6 */
+ uint8_t param_type; /* iscsi_param_type */
+ uint8_t value[0]; /* length sized value follows */
+} __packed;
+
/*
* To keep the struct iscsi_uevent size the same for userspace code
* compatibility, the main structure for ISCSI_UEVENT_PATH_UPDATE and
@@ -242,6 +285,71 @@ struct iscsi_path {
uint16_t pmtu;
} __attribute__ ((aligned (sizeof(uint64_t))));
+/* iscsi iface enabled/disabled setting */
+#define ISCSI_IFACE_DISABLE 0x01
+#define ISCSI_IFACE_ENABLE 0x02
+
+/* ipv4 bootproto */
+#define ISCSI_BOOTPROTO_STATIC 0x01
+#define ISCSI_BOOTPROTO_DHCP 0x02
+
+/* ipv6 addr autoconfig type */
+#define ISCSI_IPV6_AUTOCFG_DISABLE 0x01
+#define ISCSI_IPV6_AUTOCFG_ND_ENABLE 0x02
+#define ISCSI_IPV6_AUTOCFG_DHCPV6_ENABLE 0x03
+
+/* ipv6 link local addr type */
+#define ISCSI_IPV6_LINKLOCAL_AUTOCFG_ENABLE 0x01
+#define ISCSI_IPV6_LINKLOCAL_AUTOCFG_DISABLE 0x02
+
+/* ipv6 router addr type */
+#define ISCSI_IPV6_ROUTER_AUTOCFG_ENABLE 0x01
+#define ISCSI_IPV6_ROUTER_AUTOCFG_DISABLE 0x02
+
+#define ISCSI_IFACE_TYPE_IPV4 0x01
+#define ISCSI_IFACE_TYPE_IPV6 0x02
+
+#define ISCSI_MAX_VLAN_ID 4095
+#define ISCSI_MAX_VLAN_PRIORITY 7
+
+/* iscsi vlan enable/disabled setting */
+#define ISCSI_VLAN_DISABLE 0x01
+#define ISCSI_VLAN_ENABLE 0x02
+
+/* iSCSI network params */
+enum iscsi_net_param {
+ ISCSI_NET_PARAM_IPV4_ADDR = 1,
+ ISCSI_NET_PARAM_IPV4_SUBNET = 2,
+ ISCSI_NET_PARAM_IPV4_GW = 3,
+ ISCSI_NET_PARAM_IPV4_BOOTPROTO = 4,
+ ISCSI_NET_PARAM_MAC = 5,
+ ISCSI_NET_PARAM_IPV6_LINKLOCAL = 6,
+ ISCSI_NET_PARAM_IPV6_ADDR = 7,
+ ISCSI_NET_PARAM_IPV6_ROUTER = 8,
+ ISCSI_NET_PARAM_IPV6_ADDR_AUTOCFG = 9,
+ ISCSI_NET_PARAM_IPV6_LINKLOCAL_AUTOCFG = 10,
+ ISCSI_NET_PARAM_IPV6_ROUTER_AUTOCFG = 11,
+ ISCSI_NET_PARAM_IFACE_ENABLE = 12,
+ ISCSI_NET_PARAM_VLAN_ID = 13,
+ ISCSI_NET_PARAM_VLAN_PRIORITY = 14,
+ ISCSI_NET_PARAM_VLAN_ENABLED = 15,
+ ISCSI_NET_PARAM_VLAN_TAG = 16,
+ ISCSI_NET_PARAM_IFACE_TYPE = 17,
+ ISCSI_NET_PARAM_IFACE_NAME = 18,
+ ISCSI_NET_PARAM_MTU = 19,
+ ISCSI_NET_PARAM_PORT = 20,
+};
+
+enum iscsi_conn_state {
+ ISCSI_CONN_STATE_FREE,
+ ISCSI_CONN_STATE_XPT_WAIT,
+ ISCSI_CONN_STATE_IN_LOGIN,
+ ISCSI_CONN_STATE_LOGGED_IN,
+ ISCSI_CONN_STATE_IN_LOGOUT,
+ ISCSI_CONN_STATE_LOGOUT_REQUESTED,
+ ISCSI_CONN_STATE_CLEANUP_WAIT,
+};
+
/*
* Common error codes
*/
@@ -268,6 +376,7 @@ enum iscsi_err {
ISCSI_ERR_INVALID_HOST = ISCSI_ERR_BASE + 18,
ISCSI_ERR_XMIT_FAILED = ISCSI_ERR_BASE + 19,
ISCSI_ERR_TCP_CONN_CLOSE = ISCSI_ERR_BASE + 20,
+ ISCSI_ERR_SCSI_EH_SESSION_RST = ISCSI_ERR_BASE + 21,
};
/*
@@ -296,7 +405,7 @@ enum iscsi_param {
ISCSI_PARAM_PERSISTENT_PORT,
ISCSI_PARAM_SESS_RECOVERY_TMO,
- /* pased in through bind conn using transport_fd */
+ /* passed in through bind conn using transport_fd */
ISCSI_PARAM_CONN_PORT,
ISCSI_PARAM_CONN_ADDRESS,
@@ -318,6 +427,7 @@ enum iscsi_param {
ISCSI_PARAM_INITIATOR_NAME,
ISCSI_PARAM_TGT_RESET_TMO,
+ ISCSI_PARAM_TARGET_ALIAS,
/* must always be last */
ISCSI_PARAM_MAX,
};
@@ -358,6 +468,7 @@ enum iscsi_param {
#define ISCSI_ISID (1ULL << ISCSI_PARAM_ISID)
#define ISCSI_INITIATOR_NAME (1ULL << ISCSI_PARAM_INITIATOR_NAME)
#define ISCSI_TGT_RESET_TMO (1ULL << ISCSI_PARAM_TGT_RESET_TMO)
+#define ISCSI_TARGET_ALIAS (1ULL << ISCSI_PARAM_TARGET_ALIAS)
/* iSCSI HBA params */
enum iscsi_host_param {
@@ -394,6 +505,7 @@ enum iscsi_host_param {
#define CAP_DIGEST_OFFLOAD 0x1000 /* offload hdr and data digests */
#define CAP_PADDING_OFFLOAD 0x2000 /* offload padding insertion, removal,
and verification */
+#define CAP_LOGIN_OFFLOAD 0x4000 /* offload normal session login */
/*
* These flags describes reason of stop_conn() call
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/Makefile open-iscsi-2.0-872-rc4-bnx2i.work/Makefile
--- open-iscsi-2.0-872-rc4-bnx2i/Makefile 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/Makefile 2012-03-05 23:04:27.000000000 -0600
@@ -24,10 +24,10 @@ IFACEFILES = etc/iface.example
# using '$(MAKE)' instead of just 'make' allows make to run in parallel
# over multiple makefile.
-all: user kernel
+all: user
-user: ;
- cd utils/open-isns; ./configure; $(MAKE)
+user: utils/open-isns/Makefile
+ $(MAKE) -C utils/open-isns
$(MAKE) -C utils/sysdeps
$(MAKE) -C utils/fwparam_ibft
$(MAKE) -C usr
@@ -41,6 +41,9 @@ user: ;
@echo
@echo "Read README file for detailed information."
+utils/open-isns/Makefile: utils/open-isns/configure utils/open-isns/Makefile.in
+ cd utils/open-isns; ./configure CFLAGS="$(OPTFLAGS)" --with-security=no
+
kernel: force
$(MAKE) -C kernel
@echo "Kernel Compilation complete Output file"
@@ -68,7 +71,7 @@ clean:
install_initd_suse install_initd_redhat install_initd_debian \
install_etc install_iface install_doc install_kernel install_iname
-install: install_kernel install_programs install_doc install_etc \
+install: install_programs install_doc install_etc \
install_initd install_iname install_iface
install_user: install_programs install_doc install_etc \
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/README open-iscsi-2.0-872-rc4-bnx2i.work/README
--- open-iscsi-2.0-872-rc4-bnx2i/README 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/README 2012-03-05 23:03:47.000000000 -0600
@@ -166,7 +166,7 @@ term node to refer to a portal on a targ
require that --targetname and --portal argument be used when in node mode.
For session mode, a session id (sid) is used. The sid of a session can be
-found by running iscsiadm -m session -i. The session id is not currently
+found by running iscsiadm -m session -P 1. The session id is not currently
persistent and is partially determined by when the session is setup.
Note that some of the iSCSI Node and iSCSI Discovery operations
@@ -371,9 +371,10 @@ Usage: iscsiadm [OPTION]
iscsi_ifacename.
See below for examples.
- -m host --host=hostno --print=level
- Display information for a specific host if hostno
- is passed in. If no hostno is passed in then info
+ -m host --host=hostno|MAC --print=level
+ Display information for a specific host. The host
+ can be passed in by host number or by MAC address.
+ If a host is not passed in then info
for all hosts is printed.
Print level can be 0 to 4.
@@ -408,8 +409,9 @@ this the following is not needed for sof
Warning!!!!!!
This feature is experimental. The interface may change. When reporting
bugs, if you cannot do a "ping -I ethX target_portal", then check your
-network settings first. If you cannot ping the portal, then you will
-not be able to bind a session to a NIC.
+network settings first. Make sure the rp_filter setting is set to 0 or 2
+(see Prep section below for more info). If you cannot ping the portal,
+then you will not be able to bind a session to a NIC.
What is a scsi_host and iface for software, hardware and partial
offload iscsi?
@@ -427,6 +429,32 @@ structure. For each HBA port or for soft
device (ethX) or NIC, that you wish to bind sessions to you must create
a iface config /etc/iscsi/ifaces.
+Prep:
+
+The iface binding feature requires the sysctl setting
+net.ipv4.conf.default.rp_filter to be set to 0 or 2. This can be set
+in /etc/sysctl.conf by having the line:
+
+net.ipv4.conf.default.rp_filter = N
+
+where N is 0 or 2. Note that when setting this you may have to reboot
+the box for the value to take effect.
+
+
+rp_filter information from Documentation/networking/ip-sysctl.txt:
+
+rp_filter - INTEGER
+ 0 - No source validation.
+ 1 - Strict mode as defined in RFC3704 Strict Reverse Path
+ Each incoming packet is tested against the FIB and if the interface
+ is not the best reverse path the packet check will fail.
+ By default failed packets are discarded.
+ 2 - Loose mode as defined in RFC3704 Loose Reverse Path
+ Each incoming packet's source address is also tested against the FIB
+ and if the source address is not reachable via any interface
+ the packet check will fail.
+
+
Running:
# iscsiadm -m iface
@@ -488,10 +516,10 @@ some helpful management commands.
5.1.2 Setting up a iface for a iSCSI offload card
=================================================
-This section describes how to setup ifaces for use with Chelsio
-and Broadcom cards.
+This section describes how to setup ifaces for use with Chelsio, Broadcom and
+QLogic cards.
-By default, iscsiadm will create a iface for each Broadcom and Chelsio
+By default, iscsiadm will create a iface for each Broadcom, QLogic and Chelsio
port. The iface name will be of the form:
$transport/driver_name.$MAC_ADDRESS
@@ -502,6 +530,7 @@ Running:
default tcp,<empty>,<empty>,<empty>,<empty>
iser iser,<empty>,<empty>,<empty>,<empty>
cxgb3i.00:07:43:05:97:07 cxgb3i,00:07:43:05:97:07,<empty>,<empty>,<empty>
+qla4xxx.00:0e:1e:04:8b:2e qla4xxx,00:0e:1e:04:8b:2e,<empty>,<empty>,<empty>
Will report iface configurations that are setup in /etc/iscsi/ifaces.
@@ -520,7 +549,7 @@ default one in /etc/iscsi/initiatorname.
-To display these values in a more friendly run:
+To display these values in a more friendly way, run:
iscsiadm -m iface -I cxgb3i.00:07:43:05:97:07
# BEGIN RECORD 2.0-871
@@ -544,6 +573,38 @@ For the name of the value we want to upd
the "iscsiadm -m iface -I cxgb3i.00:07:43:05:97:07" command which is
"iface.ipaddress".
+Note2.
+
+For QLogic ports after updating the iface record, for network settings to take
+effect, one must apply or applyall the settings.
+
+iscsiadm -m iface -I qla4xxx.00:0e:1e:04:8b:2e -o apply or
+iscsiadm -m iface -H 00:0e:1e:04:8b:2e -o applyall
+
+With operation "apply" network setting for the specified iface will take effect.
+With operation "applyall" network settings for all ifaces on a specific host
+will take take effect. The host can be specified using the -H/--host argument
+by either the MAC address of the host or the host number.
+
+
+Here is an example of setting multiple IPv6 address on single iSCSI interface
+port.
+First interface (no need to set iface_num, it is 0 by default)
+
+iscsiadm -m iface -I qla4xxx.00:0e:1e:04:8b:2a -o update \
+ -n iface.ipaddress -v fec0:ce00:7014:0041:1111:2222:1e04:9392
+
+Create the second interface if it does not exist
+
+iscsiadm -m iface -I qla4xxx.00:0e:1e:04:8b:2a.1 -op=new
+iscsiadm -m iface -I qla4xxx.00:0e:1e:04:8b:2a -o update \
+ -n iface.iface_num -v 1 (iface_num is mandatory for second iface)
+iscsiadm -m iface -I qla4xxx.00:0e:1e:04:8b:2a -o update \
+ -n iface.ipaddress -v = fec0:ce00:7014:0041:1111:2222:1e04:9393
+iscsiadm -m iface -H 00:0e:1e:04:8b:2a --op=applyall
+
+Note: If there are common settings for multiple interfaces then the
+settings from 0th iface would be considered valid.
Now, we can use this iface to login into targets, which is described in the
next section.
@@ -624,6 +685,9 @@ To now log into targets it is the same a
If a record does not exist, it will be created using the iscsid.conf
discovery settings.
+ The argument to -p may also be a hostname instead of an address.
+ ./iscsiadm -m discoverydb -t st -p smoehost --discover
+
For the ifaces, iscsiadm will first search /etc/iscsi/ifaces for
interfaces using software iscsi. If any are found then nodes found
during discovery will be setup so that they can logged in through
@@ -748,6 +812,10 @@ To now log into targets it is the same a
./iscsiadm -m node -T iqn.2005-03.com.max \
-p [2001:c90::211:9ff:feb8:a9e9]:3260 -l
+ To specify a hostname the following can be used:
+
+ ./iscsiadm -m node -T iqn.2005-03.com.max -p somehost -l
+
- iSCSI Login to a specific portal through the NIC setup as iface0:
./iscsiadm -m node -T iqn.2005-03.com.max -p 192.168.0.4:3260 \
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/actor.c open-iscsi-2.0-872-rc4-bnx2i.work/usr/actor.c
--- open-iscsi-2.0-872-rc4-bnx2i/usr/actor.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/actor.c 2012-03-05 23:02:46.000000000 -0600
@@ -113,14 +113,13 @@ actor_schedule_private(actor_t *thread,
* state to scheduled, else add current time to ttschedule and
* insert in the queue at the correct point */
if (delay_time == 0) {
- if (poll_in_progress) {
+ /* For head addition, it must go onto the head of the
+ actor_list regardless if poll is in progress or not
+ */
+ if (poll_in_progress && !head) {
thread->state = ACTOR_POLL_WAITING;
- if (head)
- list_add(&thread->list,
- &poll_list);
- else
- list_add_tail(&thread->list,
- &poll_list);
+ list_add_tail(&thread->list,
+ &poll_list);
} else {
thread->state = ACTOR_SCHEDULED;
if (head)
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/auth.c open-iscsi-2.0-872-rc4-bnx2i.work/usr/auth.c
--- open-iscsi-2.0-872-rc4-bnx2i/usr/auth.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/auth.c 2012-03-05 23:02:46.000000000 -0600
@@ -194,27 +194,20 @@ get_random_bytes(unsigned char *data, un
fd = open("/dev/urandom", O_RDONLY);
while (length > 0) {
- if (fd)
- read(fd, &r, sizeof(long));
- else
+ if (!fd || read(fd, &r, sizeof(long)) != -1)
r = rand();
r = r ^ (r >> 8);
r = r ^ (r >> 4);
n = r & 0x7;
- if (fd)
- read(fd, &r, sizeof(long));
- else
+ if (!fd || read(fd, &r, sizeof(long)) != -1)
r = rand();
r = r ^ (r >> 8);
r = r ^ (r >> 5);
n = (n << 3) | (r & 0x7);
- if (fd)
- read(fd, &r, sizeof(long));
- else
+ if (!fd || read(fd, &r, sizeof(long)) != -1)
r = rand();
-
r = r ^ (r >> 8);
r = r ^ (r >> 5);
n = (n << 2) | (r & 0x3);
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/config.h open-iscsi-2.0-872-rc4-bnx2i.work/usr/config.h
--- open-iscsi-2.0-872-rc4-bnx2i/usr/config.h 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/config.h 2012-03-05 23:03:29.000000000 -0600
@@ -73,7 +73,7 @@ struct iscsi_connection_timeout_config {
int noop_out_timeout;
};
-/* all per-connection timeouts go in this structure.
+/* all per-session timeouts go in this structure.
* this structure is per-session, and can be configured
* by TargetName but not by Subnet.
*/
@@ -141,7 +141,8 @@ struct iscsi_sendtargets_config {
int discoveryd_poll_inval;
struct iscsi_auth_config auth;
struct iscsi_connection_timeout_config conn_timeo;
- struct iscsi_conn_operational_config iscsi;
+ struct iscsi_conn_operational_config conn_conf;
+ struct iscsi_session_operational_config session_conf;
};
struct iscsi_isns_config {
@@ -188,21 +189,46 @@ typedef struct session_rec {
int cmds_max;
int queue_depth;
int initial_login_retry_max;
+ int nr_sessions;
struct iscsi_auth_config auth;
struct iscsi_session_timeout_config timeo;
struct iscsi_error_timeout_config err_timeo;
struct iscsi_session_operational_config iscsi;
+ struct session_info *info;
+ unsigned sid;
+ /*
+ * This is a flag passed to iscsid. If set, multiple sessions are
+ * allowed to be initiated on this record
+ */
+ unsigned char multiple;
} session_rec_t;
#define ISCSI_TRANSPORT_NAME_MAXLEN 16
+#define ISCSI_MAX_STR_LEN 80
typedef struct iface_rec {
struct list_head list;
/* iscsi iface record name */
char name[ISCSI_MAX_IFACE_LEN];
+ uint32_t iface_num;
/* network layer iface name (eth0) */
char netdev[IFNAMSIZ];
char ipaddress[NI_MAXHOST];
+ char subnet_mask[NI_MAXHOST];
+ char gateway[NI_MAXHOST];
+ char bootproto[ISCSI_MAX_STR_LEN];
+ char ipv6_linklocal[NI_MAXHOST];
+ char ipv6_router[NI_MAXHOST];
+ char ipv6_autocfg[NI_MAXHOST];
+ char linklocal_autocfg[NI_MAXHOST];
+ char router_autocfg[NI_MAXHOST];
+ uint16_t vlan_id;
+ uint8_t vlan_priority;
+ char vlan_state[ISCSI_MAX_STR_LEN];
+ char state[ISCSI_MAX_STR_LEN]; /* 0 = disable,
+ * 1 = enable */
+ uint16_t mtu;
+ uint16_t port;
/*
* TODO: we may have to make this bigger and interconnect
* specific for infinniband
@@ -222,6 +248,7 @@ typedef struct node_rec {
char name[TARGET_NAME_MAXLEN];
int tpgt;
iscsi_startup_e startup;
+ int leading_login;
session_rec_t session;
conn_rec_t conn[ISCSI_CONN_MAX];
iface_rec_t iface;
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/cxgb3i.c open-iscsi-2.0-872-rc4-bnx2i.work/usr/cxgb3i.c
--- open-iscsi-2.0-872-rc4-bnx2i/usr/cxgb3i.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/cxgb3i.c 1969-12-31 18:00:00.000000000 -0600
@@ -1,24 +0,0 @@
-/*
- * cxgb3i helpers
- *
- * Copyright (C) 2006 Mike Christie
- * Copyright (C) 2006 Red Hat, Inc. All rights reserved.
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published
- * by the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful, but
- * WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- * General Public License for more details.
- */
-#include "initiator.h"
-
-void cxgb3i_create_conn(struct iscsi_conn *conn)
-{
- /* card can handle up to 15360 bytes */
- if (conn->max_recv_dlength > 8192)
- conn->max_recv_dlength = 8192;
-}
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/cxgb3i.h open-iscsi-2.0-872-rc4-bnx2i.work/usr/cxgb3i.h
--- open-iscsi-2.0-872-rc4-bnx2i/usr/cxgb3i.h 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/cxgb3i.h 1969-12-31 18:00:00.000000000 -0600
@@ -1,8 +0,0 @@
-#ifndef CXGB3I_TRANSPORT
-#define CXGB3I_TRANSPORT
-
-struct iscsi_conn;
-
-extern void cxgb3i_create_conn(struct iscsi_conn *conn);
-
-#endif
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/cxgbi.c open-iscsi-2.0-872-rc4-bnx2i.work/usr/cxgbi.c
--- open-iscsi-2.0-872-rc4-bnx2i/usr/cxgbi.c 1969-12-31 18:00:00.000000000 -0600
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/cxgbi.c 2012-03-05 23:02:46.000000000 -0600
@@ -0,0 +1,24 @@
+/*
+ * cxgb3i/cxgb4i helpers
+ *
+ * Copyright (C) 2006 Mike Christie
+ * Copyright (C) 2006 Red Hat, Inc. All rights reserved.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published
+ * by the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * General Public License for more details.
+ */
+#include "initiator.h"
+
+void cxgbi_create_conn(struct iscsi_conn *conn)
+{
+ /* card can handle up to 15360 bytes */
+ if (conn->max_recv_dlength > 8192)
+ conn->max_recv_dlength = 8192;
+}
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/cxgbi.h open-iscsi-2.0-872-rc4-bnx2i.work/usr/cxgbi.h
--- open-iscsi-2.0-872-rc4-bnx2i/usr/cxgbi.h 1969-12-31 18:00:00.000000000 -0600
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/cxgbi.h 2012-03-05 23:02:46.000000000 -0600
@@ -0,0 +1,8 @@
+#ifndef CXGBI_TRANSPORT
+#define CXGBI_TRANSPORT
+
+struct iscsi_conn;
+
+extern void cxgbi_create_conn(struct iscsi_conn *conn);
+
+#endif
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/dcb_app.c open-iscsi-2.0-872-rc4-bnx2i.work/usr/dcb_app.c
--- open-iscsi-2.0-872-rc4-bnx2i/usr/dcb_app.c 1969-12-31 18:00:00.000000000 -0600
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/dcb_app.c 2012-03-05 23:02:46.000000000 -0600
@@ -0,0 +1,387 @@
+/*******************************************************************************
+
+ DCB application support
+ Copyright(c) 2007-2011 Intel Corporation.
+
+ This program is free software; you can redistribute it and/or modify it
+ under the terms and conditions of the GNU General Public License,
+ version 2, as published by the Free Software Foundation.
+
+ This program is distributed in the hope it will be useful, but WITHOUT
+ ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+ more details.
+
+ You should have received a copy of the GNU General Public License along with
+ this program; if not, write to the Free Software Foundation, Inc.,
+ 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA.
+
+ The full GNU General Public License is included in this distribution in
+ the file called "COPYING".
+
+ Contact Information:
+ open-lldp Mailing List <lldp-devel@open-lldp.org>
+
+*******************************************************************************/
+
+#include <unistd.h>
+#include <stdlib.h>
+#include <string.h>
+#include <errno.h>
+#include <asm/errno.h>
+#include <fcntl.h>
+#include <sys/socket.h>
+#include <net/if.h>
+#include <linux/netlink.h>
+#include <linux/rtnetlink.h>
+#include "dcbnl.h"
+#include "dcb_app.h"
+#include "sysfs.h"
+
+/* Older kernels' rtnetlink.h may not have RTM_[GS]ETDCB */
+#ifndef RTM_GETDCB
+# define RTM_GETDCB 78
+#endif
+#ifndef RTM_SETDCB
+# define RTM_SETDCB 79
+#endif
+
+#define IEEE_SMASK_ETHTYPE (1 << IEEE_8021QAZ_APP_SEL_ETHERTYPE)
+#define IEEE_SMASK_STREAM (1 << IEEE_8021QAZ_APP_SEL_STREAM)
+#define IEEE_SMASK_DGRAM (1 << IEEE_8021QAZ_APP_SEL_DGRAM)
+#define IEEE_SMASK_ANY (1 << IEEE_8021QAZ_APP_SEL_ANY)
+
+#define NLA_DATA(nla) ((void *)((char *)(nla) + NLA_HDRLEN))
+#define NLA_NEXT(nla) (struct rtattr *)((char *)nla + NLMSG_ALIGN(nla->rta_len))
+
+/* Maximum size of response requested or message sent */
+#define MAX_MSG_SIZE 1024
+
+static struct nlmsghdr *start_dcbmsg(__u16 msg_type, __u8 arg)
+{
+ struct nlmsghdr *nlh;
+ struct dcbmsg *d;
+
+ nlh = malloc(MAX_MSG_SIZE);
+ if (!nlh)
+ return NULL;
+ memset(nlh, 0, MAX_MSG_SIZE);
+ nlh->nlmsg_type = msg_type;
+ nlh->nlmsg_flags = NLM_F_REQUEST;
+ nlh->nlmsg_seq = 0;
+ nlh->nlmsg_pid = getpid();
+ if (msg_type != RTM_GETDCB) {
+ free(nlh);
+ return NULL;
+ }
+
+ nlh->nlmsg_len = NLMSG_LENGTH(sizeof(struct dcbmsg));
+ d = NLMSG_DATA(nlh);
+ d->cmd = arg;
+ d->dcb_family = AF_UNSPEC;
+ d->dcb_pad = 0;
+
+ return nlh;
+}
+
+static struct rtattr *add_rta(struct nlmsghdr *nlh, __u16 rta_type,
+ void *attr, __u16 rta_len)
+{
+ struct rtattr *rta;
+
+ rta = (struct rtattr *)((char *)nlh + nlh->nlmsg_len);
+ rta->rta_type = rta_type;
+ rta->rta_len = rta_len + NLA_HDRLEN;
+ if (attr)
+ memcpy(NLA_DATA(rta), attr, rta_len);
+ nlh->nlmsg_len += NLMSG_ALIGN(rta->rta_len);
+
+ return rta;
+}
+
+static int dcbnl_send_msg(int nl_sd, struct nlmsghdr *nlh)
+{
+ struct sockaddr_nl nladdr;
+ void *buf = nlh;
+ int r, len = nlh->nlmsg_len;
+
+ memset(&nladdr, 0, sizeof(nladdr));
+ nladdr.nl_family = AF_NETLINK;
+
+ do {
+ r = sendto(nl_sd, buf, len, 0, (struct sockaddr *)&nladdr,
+ sizeof(nladdr));
+ } while (r < 0 && errno == EINTR);
+
+ if (r < 0)
+ return 1;
+
+ return 0;
+}
+
+static struct nlmsghdr *dcbnl_get_msg(int nl_sd)
+{
+ struct nlmsghdr *nlh;
+ int len;
+
+ nlh = malloc(MAX_MSG_SIZE);
+ if (!nlh)
+ return NULL;
+ memset(nlh, 0, MAX_MSG_SIZE);
+
+ len = recv(nl_sd, (void *)nlh, MAX_MSG_SIZE, 0);
+
+ if (len < 0 || nlh->nlmsg_type == NLMSG_ERROR ||
+ !NLMSG_OK(nlh, (unsigned int)len)) {
+ free(nlh);
+ return NULL;
+ }
+
+ return nlh;
+}
+
+static int get_dcbx_cap(int nl_sd, const char *ifname)
+{
+ struct nlmsghdr *nlh;
+ struct dcbmsg *d;
+ struct rtattr *rta;
+ int rval;
+
+ nlh = start_dcbmsg(RTM_GETDCB, DCB_CMD_GDCBX);
+ if (!nlh)
+ return -EIO;
+
+ add_rta(nlh, DCB_ATTR_IFNAME, (void *)ifname, strlen(ifname) + 1);
+ rval = dcbnl_send_msg(nl_sd, nlh);
+ free(nlh);
+ if (rval)
+ return -EIO;
+
+ /* Receive DCBX capabilities */
+ nlh = dcbnl_get_msg(nl_sd);
+ if (!nlh)
+ return -EIO;
+
+ d = (struct dcbmsg *)NLMSG_DATA(nlh);
+ rta = (struct rtattr *)(((char *)d) +
+ NLMSG_ALIGN(sizeof(struct dcbmsg)));
+
+ if (d->cmd != DCB_CMD_GDCBX || rta->rta_type != DCB_ATTR_DCBX) {
+ free(nlh);
+ return -EIO;
+ }
+
+ rval = *(__u8 *)NLA_DATA(rta);
+ free(nlh);
+ return rval;
+}
+
+static int get_cee_app_pri(int nl_sd, const char *ifname,
+ __u8 req_idtype, __u16 req_id)
+{
+ struct nlmsghdr *nlh;
+ struct dcbmsg *d;
+ struct rtattr *rta_parent, *rta_child;
+ int rval = 0;
+ __u8 idtype;
+ __u16 id;
+
+ nlh = start_dcbmsg(RTM_GETDCB, DCB_CMD_GAPP);
+ if (!nlh)
+ return -EIO;
+
+ add_rta(nlh, DCB_ATTR_IFNAME, (void *)ifname, strlen(ifname) + 1);
+ rta_parent = add_rta(nlh, DCB_ATTR_APP, NULL, 0);
+
+ rta_child = add_rta(nlh, DCB_APP_ATTR_IDTYPE,
+ (void *)&req_idtype, sizeof(__u8));
+ rta_parent->rta_len += NLA_ALIGN(rta_child->rta_len);
+
+ rta_child = add_rta(nlh, DCB_APP_ATTR_ID,
+ (void *)&req_id, sizeof(__u16));
+ rta_parent->rta_len += NLA_ALIGN(rta_child->rta_len);
+
+ rval = dcbnl_send_msg(nl_sd, nlh);
+ free(nlh);
+ if (rval)
+ return -EIO;
+
+ nlh = dcbnl_get_msg(nl_sd);
+ if (!nlh)
+ return -EIO;
+
+ d = (struct dcbmsg *)NLMSG_DATA(nlh);
+ rta_parent = (struct rtattr *)(((char *)d) +
+ NLMSG_ALIGN(sizeof(struct dcbmsg)));
+
+ if (d->cmd != DCB_CMD_GAPP) {
+ rval = -EIO;
+ goto get_error;
+ }
+ if (rta_parent->rta_type != DCB_ATTR_APP) {
+ rval = -EIO;
+ goto get_error;
+ }
+
+ rta_child = NLA_DATA(rta_parent);
+ rta_parent = NLA_NEXT(rta_parent);
+
+ idtype = *(__u8 *)NLA_DATA(rta_child);
+ rta_child = NLA_NEXT(rta_child);
+ if (idtype != req_idtype) {
+ rval = -EIO;
+ goto get_error;
+ }
+
+ id = *(__u16 *)NLA_DATA(rta_child);
+ rta_child = NLA_NEXT(rta_child);
+ if (id != req_id) {
+ rval = -EIO;
+ goto get_error;
+ }
+
+ rval = *(__u8 *)NLA_DATA(rta_child);
+
+get_error:
+ free(nlh);
+ return rval;
+}
+
+static int
+get_ieee_app_pri(int nl_sd, const char *ifname, __u8 ieee_mask, __u16 req_id)
+{
+ struct nlmsghdr *nlh;
+ struct dcbmsg *d;
+ struct rtattr *rta_parent, *rta_child;
+ int rval;
+
+ nlh = start_dcbmsg(RTM_GETDCB, DCB_CMD_IEEE_GET);
+ if (!nlh)
+ return -EIO;
+
+ add_rta(nlh, DCB_ATTR_IFNAME, (void *)ifname, strlen(ifname) + 1);
+
+ rval = dcbnl_send_msg(nl_sd, nlh);
+ free(nlh);
+ if (rval)
+ return -EIO;
+
+ nlh = dcbnl_get_msg(nl_sd);
+ if (!nlh)
+ return -EIO;
+
+ d = (struct dcbmsg *)NLMSG_DATA(nlh);
+ rta_parent = (struct rtattr *)(((char *)d) +
+ NLMSG_ALIGN(sizeof(struct dcbmsg)));
+
+ if (d->cmd != DCB_CMD_IEEE_GET) {
+ rval = -EIO;
+ goto get_error;
+ }
+ if (rta_parent->rta_type != DCB_ATTR_IFNAME) {
+ rval = -EIO;
+ goto get_error;
+ }
+
+ rta_parent = NLA_NEXT(rta_parent);
+
+ if (rta_parent->rta_type != DCB_ATTR_IEEE) {
+ rval = -EIO;
+ goto get_error;
+ }
+
+ rta_child = NLA_DATA(rta_parent);
+ rta_parent = NLA_NEXT(rta_parent);
+
+ for (; rta_parent > rta_child; rta_child = NLA_NEXT(rta_child)) {
+ if (rta_child->rta_type == DCB_ATTR_IEEE_APP_TABLE)
+ break;
+ }
+ if (rta_parent <= rta_child) {
+ rval = -EIO;
+ goto get_error;
+ }
+
+ rta_parent = rta_child;
+ rta_child = NLA_DATA(rta_parent);
+ rta_parent = NLA_NEXT(rta_parent);
+
+ rval = 0;
+ for (; rta_parent > rta_child; rta_child = NLA_NEXT(rta_child)) {
+ struct dcb_app *app;
+
+ if (rta_child->rta_type != DCB_ATTR_IEEE_APP)
+ continue;
+ app = (struct dcb_app *)NLA_DATA(rta_child);
+ if (app->protocol != req_id)
+ continue;
+ if ((1 << app->selector) & ieee_mask)
+ rval |= 1 << app->priority;
+ }
+
+get_error:
+ free(nlh);
+ return rval;
+}
+
+static int get_link_ifname(const char *ifname, char *link_ifname)
+{
+ int ifindex;
+
+ if (sysfs_get_int(ifname, "net", "iflink", &ifindex))
+ return -EIO;
+
+ if (!if_indextoname(ifindex, link_ifname))
+ return -ENODEV;
+
+ return 0;
+}
+
+static int get_app_pri(const char *iface, __u8 req_idtype, __u16 req_id,
+ __u8 ieee_mask)
+{
+ int dcbx_cap;
+ int pri;
+ int nl_sd;
+ char ifname[IFNAMSIZ];
+
+ if (get_link_ifname(iface, ifname))
+ return 0;
+
+ nl_sd = socket(PF_NETLINK, SOCK_RAW, NETLINK_ROUTE);
+ if (nl_sd < 0)
+ return -errno;
+
+ dcbx_cap = get_dcbx_cap(nl_sd, ifname);
+ if (dcbx_cap < 0 || !(dcbx_cap & DCB_CAP_DCBX_VER_IEEE))
+ pri = get_cee_app_pri(nl_sd, ifname, req_idtype, req_id);
+ else
+ pri = get_ieee_app_pri(nl_sd, ifname, ieee_mask, req_id);
+
+ close(nl_sd);
+ return pri;
+}
+
+int get_dcb_app_pri_by_stream_port(const char *ifname, int port)
+{
+ return get_app_pri(ifname, DCB_APP_IDTYPE_PORTNUM, port,
+ IEEE_SMASK_STREAM | IEEE_SMASK_ANY);
+}
+
+int get_dcb_app_pri_by_datagram_port(const char *ifname, int port)
+{
+ return get_app_pri(ifname, DCB_APP_IDTYPE_PORTNUM, port,
+ IEEE_SMASK_DGRAM | IEEE_SMASK_ANY);
+}
+
+int get_dcb_app_pri_by_port_sel(const char *ifname, int port, int sel)
+{
+ return get_app_pri(ifname, DCB_APP_IDTYPE_PORTNUM, port,
+ 1 << sel);
+}
+
+int get_dcb_app_pri_by_ethtype(const char *ifname, int ethtype)
+{
+ return get_app_pri(ifname, DCB_APP_IDTYPE_ETHTYPE, ethtype,
+ IEEE_SMASK_ETHTYPE);
+}
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/dcb_app.h open-iscsi-2.0-872-rc4-bnx2i.work/usr/dcb_app.h
--- open-iscsi-2.0-872-rc4-bnx2i/usr/dcb_app.h 1969-12-31 18:00:00.000000000 -0600
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/dcb_app.h 2012-03-05 23:02:46.000000000 -0600
@@ -0,0 +1,41 @@
+/*******************************************************************************
+
+ DCB application support
+ Copyright(c) 2010-2011 Intel Corporation.
+
+ This program is free software; you can redistribute it and/or modify it
+ under the terms and conditions of the GNU General Public License,
+ version 2, as published by the Free Software Foundation.
+
+ This program is distributed in the hope it will be useful, but WITHOUT
+ ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+ more details.
+
+ You should have received a copy of the GNU General Public License along with
+ this program; if not, write to the Free Software Foundation, Inc.,
+ 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA.
+
+ The full GNU General Public License is included in this distribution in
+ the file called "COPYING".
+
+ Contact Information:
+ open-lldp Mailing List <lldp-devel@open-lldp.org>
+
+*******************************************************************************/
+
+#ifndef _DCB_APP_H_
+#define _DCB_APP_H_
+
+int get_dcb_app_pri_by_ethtype(const char *ifname, int ethtype);
+
+int get_dcb_app_pri_by_stream_port(const char *ifname, int port);
+int get_dcb_app_pri_by_datagram_port(const char *ifname, int port);
+
+/*
+ * The selector values for the following call are defined in recent versions
+ * of the dcbnl.h file.
+ */
+int get_dcb_app_pri_by_port_sel(const char *ifname, int port, int sel);
+
+#endif /* _DCB_APP_H_ */
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/dcbnl.h open-iscsi-2.0-872-rc4-bnx2i.work/usr/dcbnl.h
--- open-iscsi-2.0-872-rc4-bnx2i/usr/dcbnl.h 1969-12-31 18:00:00.000000000 -0600
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/dcbnl.h 2012-03-05 23:02:46.000000000 -0600
@@ -0,0 +1,653 @@
+/*
+ * Local copy of the kernel's dcbnl.h
+ *
+ * Copyright (c) 2008-2011, Intel Corporation.
+ *
+ * This program is free software; you can redistribute it and/or modify it
+ * under the terms and conditions of the GNU General Public License,
+ * version 2, as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program; if not, write to the Free Software Foundation, Inc., 59 Temple
+ * Place - Suite 330, Boston, MA 02111-1307 USA.
+ *
+ * Author: Lucy Liu <lucy.liu@intel.com>
+ */
+
+#ifndef __LINUX_DCBNL_H__
+#define __LINUX_DCBNL_H__
+
+#include <linux/types.h>
+
+/* IEEE 802.1Qaz std supported values */
+#define IEEE_8021QAZ_MAX_TCS 8
+
+#define IEEE_8021QAZ_TSA_STRICT 0
+#define IEEE_8021QAZ_TSA_CB_SHAPER 1
+#define IEEE_8021QAZ_TSA_ETS 2
+#define IEEE_8021QAZ_TSA_VENDOR 255
+
+/* This structure contains the IEEE 802.1Qaz ETS managed object
+ *
+ * @willing: willing bit in ETS configuration TLV
+ * @ets_cap: indicates supported capacity of ets feature
+ * @cbs: credit based shaper ets algorithm supported
+ * @tc_tx_bw: tc tx bandwidth indexed by traffic class
+ * @tc_rx_bw: tc rx bandwidth indexed by traffic class
+ * @tc_tsa: TSA Assignment table, indexed by traffic class
+ * @prio_tc: priority assignment table mapping 8021Qp to traffic class
+ * @tc_reco_bw: recommended tc bandwidth indexed by traffic class for TLV
+ * @tc_reco_tsa: recommended tc bandwidth indexed by traffic class for TLV
+ * @reco_prio_tc: recommended tc tx bandwidth indexed by traffic class for TLV
+ *
+ * Recommended values are used to set fields in the ETS recommendation TLV
+ * with hardware offloaded LLDP.
+ *
+ * ----
+ * TSA Assignment 8 bit identifiers
+ * 0 strict priority
+ * 1 credit-based shaper
+ * 2 enhanced transmission selection
+ * 3-254 reserved
+ * 255 vendor specific
+ */
+struct ieee_ets {
+ __u8 willing;
+ __u8 ets_cap;
+ __u8 cbs;
+ __u8 tc_tx_bw[IEEE_8021QAZ_MAX_TCS];
+ __u8 tc_rx_bw[IEEE_8021QAZ_MAX_TCS];
+ __u8 tc_tsa[IEEE_8021QAZ_MAX_TCS];
+ __u8 prio_tc[IEEE_8021QAZ_MAX_TCS];
+ __u8 tc_reco_bw[IEEE_8021QAZ_MAX_TCS];
+ __u8 tc_reco_tsa[IEEE_8021QAZ_MAX_TCS];
+ __u8 reco_prio_tc[IEEE_8021QAZ_MAX_TCS];
+};
+
+/* This structure contains the IEEE 802.1Qaz PFC managed object
+ *
+ * @pfc_cap: Indicates the number of traffic classes on the local device
+ * that may simultaneously have PFC enabled.
+ * @pfc_en: bitmap indicating pfc enabled traffic classes
+ * @mbc: enable macsec bypass capability
+ * @delay: the allowance made for a round-trip propagation delay of the
+ * link in bits.
+ * @requests: count of the sent pfc frames
+ * @indications: count of the received pfc frames
+ */
+struct ieee_pfc {
+ __u8 pfc_cap;
+ __u8 pfc_en;
+ __u8 mbc;
+ __u16 delay;
+ __u64 requests[IEEE_8021QAZ_MAX_TCS];
+ __u64 indications[IEEE_8021QAZ_MAX_TCS];
+};
+
+/* CEE DCBX std supported values */
+#define CEE_DCBX_MAX_PGS 8
+#define CEE_DCBX_MAX_PRIO 8
+
+/**
+ * struct cee_pg - CEE Priority-Group managed object
+ *
+ * @willing: willing bit in the PG tlv
+ * @error: error bit in the PG tlv
+ * @pg_en: enable bit of the PG feature
+ * @tcs_supported: number of traffic classes supported
+ * @pg_bw: bandwidth percentage for each priority group
+ * @prio_pg: priority to PG mapping indexed by priority
+ */
+struct cee_pg {
+ __u8 willing;
+ __u8 error;
+ __u8 pg_en;
+ __u8 tcs_supported;
+ __u8 pg_bw[CEE_DCBX_MAX_PGS];
+ __u8 prio_pg[CEE_DCBX_MAX_PGS];
+};
+
+/**
+ * struct cee_pfc - CEE PFC managed object
+ *
+ * @willing: willing bit in the PFC tlv
+ * @error: error bit in the PFC tlv
+ * @pfc_en: bitmap indicating pfc enabled traffic classes
+ * @tcs_supported: number of traffic classes supported
+ */
+struct cee_pfc {
+ __u8 willing;
+ __u8 error;
+ __u8 pfc_en;
+ __u8 tcs_supported;
+};
+
+/* IEEE 802.1Qaz std supported values */
+#define IEEE_8021QAZ_APP_SEL_ETHERTYPE 1
+#define IEEE_8021QAZ_APP_SEL_STREAM 2
+#define IEEE_8021QAZ_APP_SEL_DGRAM 3
+#define IEEE_8021QAZ_APP_SEL_ANY 4
+
+/* This structure contains the IEEE 802.1Qaz APP managed object. This
+ * object is also used for the CEE std as well. There is no difference
+ * between the objects.
+ *
+ * @selector: protocol identifier type
+ * @protocol: protocol of type indicated
+ * @priority: 3-bit unsigned integer indicating priority
+ *
+ * ----
+ * Selector field values
+ * 0 Reserved
+ * 1 Ethertype
+ * 2 Well known port number over TCP or SCTP
+ * 3 Well known port number over UDP or DCCP
+ * 4 Well known port number over TCP, SCTP, UDP, or DCCP
+ * 5-7 Reserved
+ */
+struct dcb_app {
+ __u8 selector;
+ __u8 priority;
+ __u16 protocol;
+};
+
+/**
+ * struct dcb_peer_app_info - APP feature information sent by the peer
+ *
+ * @willing: willing bit in the peer APP tlv
+ * @error: error bit in the peer APP tlv
+ *
+ * In addition to this information the full peer APP tlv also contains
+ * a table of 'app_count' APP objects defined above.
+ */
+struct dcb_peer_app_info {
+ __u8 willing;
+ __u8 error;
+};
+
+struct dcbmsg {
+ __u8 dcb_family;
+ __u8 cmd;
+ __u16 dcb_pad;
+};
+
+/**
+ * enum dcbnl_commands - supported DCB commands
+ *
+ * @DCB_CMD_UNDEFINED: unspecified command to catch errors
+ * @DCB_CMD_GSTATE: request the state of DCB in the device
+ * @DCB_CMD_SSTATE: set the state of DCB in the device
+ * @DCB_CMD_PGTX_GCFG: request the priority group configuration for Tx
+ * @DCB_CMD_PGTX_SCFG: set the priority group configuration for Tx
+ * @DCB_CMD_PGRX_GCFG: request the priority group configuration for Rx
+ * @DCB_CMD_PGRX_SCFG: set the priority group configuration for Rx
+ * @DCB_CMD_PFC_GCFG: request the priority flow control configuration
+ * @DCB_CMD_PFC_SCFG: set the priority flow control configuration
+ * @DCB_CMD_SET_ALL: apply all changes to the underlying device
+ * @DCB_CMD_GPERM_HWADDR: get the permanent MAC address of the underlying
+ * device. Only useful when using bonding.
+ * @DCB_CMD_GCAP: request the DCB capabilities of the device
+ * @DCB_CMD_GNUMTCS: get the number of traffic classes currently supported
+ * @DCB_CMD_SNUMTCS: set the number of traffic classes
+ * @DCB_CMD_GBCN: set backward congestion notification configuration
+ * @DCB_CMD_SBCN: get backward congestion notification configration.
+ * @DCB_CMD_GAPP: get application protocol configuration
+ * @DCB_CMD_SAPP: set application protocol configuration
+ * @DCB_CMD_IEEE_SET: set IEEE 802.1Qaz configuration
+ * @DCB_CMD_IEEE_GET: get IEEE 802.1Qaz configuration
+ * @DCB_CMD_GDCBX: get DCBX engine configuration
+ * @DCB_CMD_SDCBX: set DCBX engine configuration
+ * @DCB_CMD_GFEATCFG: get DCBX features flags
+ * @DCB_CMD_SFEATCFG: set DCBX features negotiation flags
+ * @DCB_CMD_CEE_GET: get CEE aggregated configuration
+ */
+enum dcbnl_commands {
+ DCB_CMD_UNDEFINED,
+
+ DCB_CMD_GSTATE,
+ DCB_CMD_SSTATE,
+
+ DCB_CMD_PGTX_GCFG,
+ DCB_CMD_PGTX_SCFG,
+ DCB_CMD_PGRX_GCFG,
+ DCB_CMD_PGRX_SCFG,
+
+ DCB_CMD_PFC_GCFG,
+ DCB_CMD_PFC_SCFG,
+
+ DCB_CMD_SET_ALL,
+
+ DCB_CMD_GPERM_HWADDR,
+
+ DCB_CMD_GCAP,
+
+ DCB_CMD_GNUMTCS,
+ DCB_CMD_SNUMTCS,
+
+ DCB_CMD_PFC_GSTATE,
+ DCB_CMD_PFC_SSTATE,
+
+ DCB_CMD_BCN_GCFG,
+ DCB_CMD_BCN_SCFG,
+
+ DCB_CMD_GAPP,
+ DCB_CMD_SAPP,
+
+ DCB_CMD_IEEE_SET,
+ DCB_CMD_IEEE_GET,
+
+ DCB_CMD_GDCBX,
+ DCB_CMD_SDCBX,
+
+ DCB_CMD_GFEATCFG,
+ DCB_CMD_SFEATCFG,
+
+ DCB_CMD_CEE_GET,
+
+ __DCB_CMD_ENUM_MAX,
+ DCB_CMD_MAX = __DCB_CMD_ENUM_MAX - 1,
+};
+
+/**
+ * enum dcbnl_attrs - DCB top-level netlink attributes
+ *
+ * @DCB_ATTR_UNDEFINED: unspecified attribute to catch errors
+ * @DCB_ATTR_IFNAME: interface name of the underlying device (NLA_STRING)
+ * @DCB_ATTR_STATE: enable state of DCB in the device (NLA_U8)
+ * @DCB_ATTR_PFC_STATE: enable state of PFC in the device (NLA_U8)
+ * @DCB_ATTR_PFC_CFG: priority flow control configuration (NLA_NESTED)
+ * @DCB_ATTR_NUM_TC: number of traffic classes supported in the device (NLA_U8)
+ * @DCB_ATTR_PG_CFG: priority group configuration (NLA_NESTED)
+ * @DCB_ATTR_SET_ALL: bool to commit changes to hardware or not (NLA_U8)
+ * @DCB_ATTR_PERM_HWADDR: MAC address of the physical device (NLA_NESTED)
+ * @DCB_ATTR_CAP: DCB capabilities of the device (NLA_NESTED)
+ * @DCB_ATTR_NUMTCS: number of traffic classes supported (NLA_NESTED)
+ * @DCB_ATTR_BCN: backward congestion notification configuration (NLA_NESTED)
+ * @DCB_ATTR_IEEE: IEEE 802.1Qaz supported attributes (NLA_NESTED)
+ * @DCB_ATTR_DCBX: DCBX engine configuration in the device (NLA_U8)
+ * @DCB_ATTR_FEATCFG: DCBX features flags (NLA_NESTED)
+ * @DCB_ATTR_CEE: CEE std supported attributes (NLA_NESTED)
+ */
+enum dcbnl_attrs {
+ DCB_ATTR_UNDEFINED,
+
+ DCB_ATTR_IFNAME,
+ DCB_ATTR_STATE,
+ DCB_ATTR_PFC_STATE,
+ DCB_ATTR_PFC_CFG,
+ DCB_ATTR_NUM_TC,
+ DCB_ATTR_PG_CFG,
+ DCB_ATTR_SET_ALL,
+ DCB_ATTR_PERM_HWADDR,
+ DCB_ATTR_CAP,
+ DCB_ATTR_NUMTCS,
+ DCB_ATTR_BCN,
+ DCB_ATTR_APP,
+
+ /* IEEE std attributes */
+ DCB_ATTR_IEEE,
+
+ DCB_ATTR_DCBX,
+ DCB_ATTR_FEATCFG,
+
+ /* CEE nested attributes */
+ DCB_ATTR_CEE,
+
+ __DCB_ATTR_ENUM_MAX,
+ DCB_ATTR_MAX = __DCB_ATTR_ENUM_MAX - 1,
+};
+
+/**
+ * enum ieee_attrs - IEEE 802.1Qaz get/set attributes
+ *
+ * @DCB_ATTR_IEEE_UNSPEC: unspecified
+ * @DCB_ATTR_IEEE_ETS: negotiated ETS configuration
+ * @DCB_ATTR_IEEE_PFC: negotiated PFC configuration
+ * @DCB_ATTR_IEEE_APP_TABLE: negotiated APP configuration
+ * @DCB_ATTR_IEEE_PEER_ETS: peer ETS configuration - get only
+ * @DCB_ATTR_IEEE_PEER_PFC: peer PFC configuration - get only
+ * @DCB_ATTR_IEEE_PEER_APP: peer APP tlv - get only
+ */
+enum ieee_attrs {
+ DCB_ATTR_IEEE_UNSPEC,
+ DCB_ATTR_IEEE_ETS,
+ DCB_ATTR_IEEE_PFC,
+ DCB_ATTR_IEEE_APP_TABLE,
+ DCB_ATTR_IEEE_PEER_ETS,
+ DCB_ATTR_IEEE_PEER_PFC,
+ DCB_ATTR_IEEE_PEER_APP,
+ __DCB_ATTR_IEEE_MAX
+};
+#define DCB_ATTR_IEEE_MAX (__DCB_ATTR_IEEE_MAX - 1)
+
+enum ieee_attrs_app {
+ DCB_ATTR_IEEE_APP_UNSPEC,
+ DCB_ATTR_IEEE_APP,
+ __DCB_ATTR_IEEE_APP_MAX
+};
+#define DCB_ATTR_IEEE_APP_MAX (__DCB_ATTR_IEEE_APP_MAX - 1)
+
+/**
+ * enum cee_attrs - CEE DCBX get attributes
+ *
+ * @DCB_ATTR_CEE_UNSPEC: unspecified
+ * @DCB_ATTR_CEE_PEER_PG: peer PG configuration - get only
+ * @DCB_ATTR_CEE_PEER_PFC: peer PFC configuration - get only
+ * @DCB_ATTR_CEE_PEER_APP: peer APP tlv - get only
+ */
+enum cee_attrs {
+ DCB_ATTR_CEE_UNSPEC,
+ DCB_ATTR_CEE_PEER_PG,
+ DCB_ATTR_CEE_PEER_PFC,
+ DCB_ATTR_CEE_PEER_APP_TABLE,
+ __DCB_ATTR_CEE_MAX
+};
+#define DCB_ATTR_CEE_MAX (__DCB_ATTR_CEE_MAX - 1)
+
+enum peer_app_attr {
+ DCB_ATTR_CEE_PEER_APP_UNSPEC,
+ DCB_ATTR_CEE_PEER_APP_INFO,
+ DCB_ATTR_CEE_PEER_APP,
+ __DCB_ATTR_CEE_PEER_APP_MAX
+};
+#define DCB_ATTR_CEE_PEER_APP_MAX (__DCB_ATTR_CEE_PEER_APP_MAX - 1)
+
+/**
+ * enum dcbnl_pfc_attrs - DCB Priority Flow Control user priority nested attrs
+ *
+ * @DCB_PFC_UP_ATTR_UNDEFINED: unspecified attribute to catch errors
+ * @DCB_PFC_UP_ATTR_0: Priority Flow Control value for User Priority 0 (NLA_U8)
+ * @DCB_PFC_UP_ATTR_1: Priority Flow Control value for User Priority 1 (NLA_U8)
+ * @DCB_PFC_UP_ATTR_2: Priority Flow Control value for User Priority 2 (NLA_U8)
+ * @DCB_PFC_UP_ATTR_3: Priority Flow Control value for User Priority 3 (NLA_U8)
+ * @DCB_PFC_UP_ATTR_4: Priority Flow Control value for User Priority 4 (NLA_U8)
+ * @DCB_PFC_UP_ATTR_5: Priority Flow Control value for User Priority 5 (NLA_U8)
+ * @DCB_PFC_UP_ATTR_6: Priority Flow Control value for User Priority 6 (NLA_U8)
+ * @DCB_PFC_UP_ATTR_7: Priority Flow Control value for User Priority 7 (NLA_U8)
+ * @DCB_PFC_UP_ATTR_MAX: highest attribute number currently defined
+ * @DCB_PFC_UP_ATTR_ALL: apply to all priority flow control attrs (NLA_FLAG)
+ *
+ */
+enum dcbnl_pfc_up_attrs {
+ DCB_PFC_UP_ATTR_UNDEFINED,
+
+ DCB_PFC_UP_ATTR_0,
+ DCB_PFC_UP_ATTR_1,
+ DCB_PFC_UP_ATTR_2,
+ DCB_PFC_UP_ATTR_3,
+ DCB_PFC_UP_ATTR_4,
+ DCB_PFC_UP_ATTR_5,
+ DCB_PFC_UP_ATTR_6,
+ DCB_PFC_UP_ATTR_7,
+ DCB_PFC_UP_ATTR_ALL,
+
+ __DCB_PFC_UP_ATTR_ENUM_MAX,
+ DCB_PFC_UP_ATTR_MAX = __DCB_PFC_UP_ATTR_ENUM_MAX - 1,
+};
+
+/**
+ * enum dcbnl_pg_attrs - DCB Priority Group attributes
+ *
+ * @DCB_PG_ATTR_UNDEFINED: unspecified attribute to catch errors
+ * @DCB_PG_ATTR_TC_0: Priority Group Traffic Class 0 configuration (NLA_NESTED)
+ * @DCB_PG_ATTR_TC_1: Priority Group Traffic Class 1 configuration (NLA_NESTED)
+ * @DCB_PG_ATTR_TC_2: Priority Group Traffic Class 2 configuration (NLA_NESTED)
+ * @DCB_PG_ATTR_TC_3: Priority Group Traffic Class 3 configuration (NLA_NESTED)
+ * @DCB_PG_ATTR_TC_4: Priority Group Traffic Class 4 configuration (NLA_NESTED)
+ * @DCB_PG_ATTR_TC_5: Priority Group Traffic Class 5 configuration (NLA_NESTED)
+ * @DCB_PG_ATTR_TC_6: Priority Group Traffic Class 6 configuration (NLA_NESTED)
+ * @DCB_PG_ATTR_TC_7: Priority Group Traffic Class 7 configuration (NLA_NESTED)
+ * @DCB_PG_ATTR_TC_MAX: highest attribute number currently defined
+ * @DCB_PG_ATTR_TC_ALL: apply to all traffic classes (NLA_NESTED)
+ * @DCB_PG_ATTR_BW_ID_0: Percent of link bandwidth for Priority Group 0 (NLA_U8)
+ * @DCB_PG_ATTR_BW_ID_1: Percent of link bandwidth for Priority Group 1 (NLA_U8)
+ * @DCB_PG_ATTR_BW_ID_2: Percent of link bandwidth for Priority Group 2 (NLA_U8)
+ * @DCB_PG_ATTR_BW_ID_3: Percent of link bandwidth for Priority Group 3 (NLA_U8)
+ * @DCB_PG_ATTR_BW_ID_4: Percent of link bandwidth for Priority Group 4 (NLA_U8)
+ * @DCB_PG_ATTR_BW_ID_5: Percent of link bandwidth for Priority Group 5 (NLA_U8)
+ * @DCB_PG_ATTR_BW_ID_6: Percent of link bandwidth for Priority Group 6 (NLA_U8)
+ * @DCB_PG_ATTR_BW_ID_7: Percent of link bandwidth for Priority Group 7 (NLA_U8)
+ * @DCB_PG_ATTR_BW_ID_MAX: highest attribute number currently defined
+ * @DCB_PG_ATTR_BW_ID_ALL: apply to all priority groups (NLA_FLAG)
+ *
+ */
+enum dcbnl_pg_attrs {
+ DCB_PG_ATTR_UNDEFINED,
+
+ DCB_PG_ATTR_TC_0,
+ DCB_PG_ATTR_TC_1,
+ DCB_PG_ATTR_TC_2,
+ DCB_PG_ATTR_TC_3,
+ DCB_PG_ATTR_TC_4,
+ DCB_PG_ATTR_TC_5,
+ DCB_PG_ATTR_TC_6,
+ DCB_PG_ATTR_TC_7,
+ DCB_PG_ATTR_TC_MAX,
+ DCB_PG_ATTR_TC_ALL,
+
+ DCB_PG_ATTR_BW_ID_0,
+ DCB_PG_ATTR_BW_ID_1,
+ DCB_PG_ATTR_BW_ID_2,
+ DCB_PG_ATTR_BW_ID_3,
+ DCB_PG_ATTR_BW_ID_4,
+ DCB_PG_ATTR_BW_ID_5,
+ DCB_PG_ATTR_BW_ID_6,
+ DCB_PG_ATTR_BW_ID_7,
+ DCB_PG_ATTR_BW_ID_MAX,
+ DCB_PG_ATTR_BW_ID_ALL,
+
+ __DCB_PG_ATTR_ENUM_MAX,
+ DCB_PG_ATTR_MAX = __DCB_PG_ATTR_ENUM_MAX - 1,
+};
+
+/**
+ * enum dcbnl_tc_attrs - DCB Traffic Class attributes
+ *
+ * @DCB_TC_ATTR_PARAM_UNDEFINED: unspecified attribute to catch errors
+ * @DCB_TC_ATTR_PARAM_PGID: (NLA_U8) Priority group the traffic class belongs to
+ * Valid values are: 0-7
+ * @DCB_TC_ATTR_PARAM_UP_MAPPING: (NLA_U8) Traffic class to user priority map
+ * Some devices may not support changing the
+ * user priority map of a TC.
+ * @DCB_TC_ATTR_PARAM_STRICT_PRIO: (NLA_U8) Strict priority setting
+ * 0 - none
+ * 1 - group strict
+ * 2 - link strict
+ * @DCB_TC_ATTR_PARAM_BW_PCT: optional - (NLA_U8) If supported by the device and
+ * not configured to use link strict priority,
+ * this is the percentage of bandwidth of the
+ * priority group this traffic class belongs to
+ * @DCB_TC_ATTR_PARAM_ALL: (NLA_FLAG) all traffic class parameters
+ *
+ */
+enum dcbnl_tc_attrs {
+ DCB_TC_ATTR_PARAM_UNDEFINED,
+
+ DCB_TC_ATTR_PARAM_PGID,
+ DCB_TC_ATTR_PARAM_UP_MAPPING,
+ DCB_TC_ATTR_PARAM_STRICT_PRIO,
+ DCB_TC_ATTR_PARAM_BW_PCT,
+ DCB_TC_ATTR_PARAM_ALL,
+
+ __DCB_TC_ATTR_PARAM_ENUM_MAX,
+ DCB_TC_ATTR_PARAM_MAX = __DCB_TC_ATTR_PARAM_ENUM_MAX - 1,
+};
+
+/**
+ * enum dcbnl_cap_attrs - DCB Capability attributes
+ *
+ * @DCB_CAP_ATTR_UNDEFINED: unspecified attribute to catch errors
+ * @DCB_CAP_ATTR_ALL: (NLA_FLAG) all capability parameters
+ * @DCB_CAP_ATTR_PG: (NLA_U8) device supports Priority Groups
+ * @DCB_CAP_ATTR_PFC: (NLA_U8) device supports Priority Flow Control
+ * @DCB_CAP_ATTR_UP2TC: (NLA_U8) device supports user priority to
+ * traffic class mapping
+ * @DCB_CAP_ATTR_PG_TCS: (NLA_U8) bitmap where each bit represents a
+ * number of traffic classes the device
+ * can be configured to use for Priority Groups
+ * @DCB_CAP_ATTR_PFC_TCS: (NLA_U8) bitmap where each bit represents a
+ * number of traffic classes the device can be
+ * configured to use for Priority Flow Control
+ * @DCB_CAP_ATTR_GSP: (NLA_U8) device supports group strict priority
+ * @DCB_CAP_ATTR_BCN: (NLA_U8) device supports Backwards Congestion
+ * Notification
+ * @DCB_CAP_ATTR_DCBX: (NLA_U8) device supports DCBX engine
+ *
+ */
+enum dcbnl_cap_attrs {
+ DCB_CAP_ATTR_UNDEFINED,
+ DCB_CAP_ATTR_ALL,
+ DCB_CAP_ATTR_PG,
+ DCB_CAP_ATTR_PFC,
+ DCB_CAP_ATTR_UP2TC,
+ DCB_CAP_ATTR_PG_TCS,
+ DCB_CAP_ATTR_PFC_TCS,
+ DCB_CAP_ATTR_GSP,
+ DCB_CAP_ATTR_BCN,
+ DCB_CAP_ATTR_DCBX,
+
+ __DCB_CAP_ATTR_ENUM_MAX,
+ DCB_CAP_ATTR_MAX = __DCB_CAP_ATTR_ENUM_MAX - 1,
+};
+
+/**
+ * DCBX capability flags
+ *
+ * @DCB_CAP_DCBX_HOST: DCBX negotiation is performed by the host LLDP agent.
+ * 'set' routines are used to configure the device with
+ * the negotiated parameters
+ *
+ * @DCB_CAP_DCBX_LLD_MANAGED: DCBX negotiation is not performed in the host but
+ * by another entity
+ * 'get' routines are used to retrieve the
+ * negotiated parameters
+ * 'set' routines can be used to set the initial
+ * negotiation configuration
+ *
+ * @DCB_CAP_DCBX_VER_CEE: for a non-host DCBX engine, indicates the engine
+ * supports the CEE protocol flavor
+ *
+ * @DCB_CAP_DCBX_VER_IEEE: for a non-host DCBX engine, indicates the engine
+ * supports the IEEE protocol flavor
+ *
+ * @DCB_CAP_DCBX_STATIC: for a non-host DCBX engine, indicates the engine
+ * supports static configuration (i.e no actual
+ * negotiation is performed negotiated parameters equal
+ * the initial configuration)
+ *
+ */
+#define DCB_CAP_DCBX_HOST 0x01
+#define DCB_CAP_DCBX_LLD_MANAGED 0x02
+#define DCB_CAP_DCBX_VER_CEE 0x04
+#define DCB_CAP_DCBX_VER_IEEE 0x08
+#define DCB_CAP_DCBX_STATIC 0x10
+
+/**
+ * enum dcbnl_numtcs_attrs - number of traffic classes
+ *
+ * @DCB_NUMTCS_ATTR_UNDEFINED: unspecified attribute to catch errors
+ * @DCB_NUMTCS_ATTR_ALL: (NLA_FLAG) all traffic class attributes
+ * @DCB_NUMTCS_ATTR_PG: (NLA_U8) number of traffic classes used for
+ * priority groups
+ * @DCB_NUMTCS_ATTR_PFC: (NLA_U8) number of traffic classes which can
+ * support priority flow control
+ */
+enum dcbnl_numtcs_attrs {
+ DCB_NUMTCS_ATTR_UNDEFINED,
+ DCB_NUMTCS_ATTR_ALL,
+ DCB_NUMTCS_ATTR_PG,
+ DCB_NUMTCS_ATTR_PFC,
+
+ __DCB_NUMTCS_ATTR_ENUM_MAX,
+ DCB_NUMTCS_ATTR_MAX = __DCB_NUMTCS_ATTR_ENUM_MAX - 1,
+};
+
+enum dcbnl_bcn_attrs{
+ DCB_BCN_ATTR_UNDEFINED = 0,
+
+ DCB_BCN_ATTR_RP_0,
+ DCB_BCN_ATTR_RP_1,
+ DCB_BCN_ATTR_RP_2,
+ DCB_BCN_ATTR_RP_3,
+ DCB_BCN_ATTR_RP_4,
+ DCB_BCN_ATTR_RP_5,
+ DCB_BCN_ATTR_RP_6,
+ DCB_BCN_ATTR_RP_7,
+ DCB_BCN_ATTR_RP_ALL,
+
+ DCB_BCN_ATTR_BCNA_0,
+ DCB_BCN_ATTR_BCNA_1,
+ DCB_BCN_ATTR_ALPHA,
+ DCB_BCN_ATTR_BETA,
+ DCB_BCN_ATTR_GD,
+ DCB_BCN_ATTR_GI,
+ DCB_BCN_ATTR_TMAX,
+ DCB_BCN_ATTR_TD,
+ DCB_BCN_ATTR_RMIN,
+ DCB_BCN_ATTR_W,
+ DCB_BCN_ATTR_RD,
+ DCB_BCN_ATTR_RU,
+ DCB_BCN_ATTR_WRTT,
+ DCB_BCN_ATTR_RI,
+ DCB_BCN_ATTR_C,
+ DCB_BCN_ATTR_ALL,
+
+ __DCB_BCN_ATTR_ENUM_MAX,
+ DCB_BCN_ATTR_MAX = __DCB_BCN_ATTR_ENUM_MAX - 1,
+};
+
+/**
+ * enum dcb_general_attr_values - general DCB attribute values
+ *
+ * @DCB_ATTR_UNDEFINED: value used to indicate an attribute is not supported
+ *
+ */
+enum dcb_general_attr_values {
+ DCB_ATTR_VALUE_UNDEFINED = 0xff
+};
+
+#define DCB_APP_IDTYPE_ETHTYPE 0x00
+#define DCB_APP_IDTYPE_PORTNUM 0x01
+enum dcbnl_app_attrs {
+ DCB_APP_ATTR_UNDEFINED,
+
+ DCB_APP_ATTR_IDTYPE,
+ DCB_APP_ATTR_ID,
+ DCB_APP_ATTR_PRIORITY,
+
+ __DCB_APP_ATTR_ENUM_MAX,
+ DCB_APP_ATTR_MAX = __DCB_APP_ATTR_ENUM_MAX - 1,
+};
+
+/**
+ * enum dcbnl_featcfg_attrs - features conifiguration flags
+ *
+ * @DCB_FEATCFG_ATTR_UNDEFINED: unspecified attribute to catch errors
+ * @DCB_FEATCFG_ATTR_ALL: (NLA_FLAG) all features configuration attributes
+ * @DCB_FEATCFG_ATTR_PG: (NLA_U8) configuration flags for priority groups
+ * @DCB_FEATCFG_ATTR_PFC: (NLA_U8) configuration flags for priority
+ * flow control
+ * @DCB_FEATCFG_ATTR_APP: (NLA_U8) configuration flags for application TLV
+ *
+ */
+#define DCB_FEATCFG_ERROR 0x01 /* error in feature resolution */
+#define DCB_FEATCFG_ENABLE 0x02 /* enable feature */
+#define DCB_FEATCFG_WILLING 0x04 /* feature is willing */
+#define DCB_FEATCFG_ADVERTISE 0x08 /* advertise feature */
+enum dcbnl_featcfg_attrs {
+ DCB_FEATCFG_ATTR_UNDEFINED,
+ DCB_FEATCFG_ATTR_ALL,
+ DCB_FEATCFG_ATTR_PG,
+ DCB_FEATCFG_ATTR_PFC,
+ DCB_FEATCFG_ATTR_APP,
+
+ __DCB_FEATCFG_ATTR_ENUM_MAX,
+ DCB_FEATCFG_ATTR_MAX = __DCB_FEATCFG_ATTR_ENUM_MAX - 1,
+};
+
+#endif /* __LINUX_DCBNL_H__ */
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/discovery.c open-iscsi-2.0-872-rc4-bnx2i.work/usr/discovery.c
--- open-iscsi-2.0-872-rc4-bnx2i/usr/discovery.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/discovery.c 2012-03-05 23:02:46.000000000 -0600
@@ -43,6 +43,12 @@
#include "fw_context.h"
#include "iscsid_req.h"
#include "iscsi_util.h"
+#include "transport.h"
+#include "iscsi_sysfs.h"
+#include "iscsi_ipc.h"
+#include "iface.h"
+#include "iscsi_timer.h"
+#include "iscsi_err.h"
/* libisns includes */
#include "isns.h"
#include "paths.h"
@@ -54,10 +60,9 @@
#define DISCOVERY_NEED_RECONNECT 0xdead0001
-static int rediscover = 0;
-
static char initiator_name[TARGET_NAME_MAXLEN + 1];
static char initiator_alias[TARGET_NAME_MAXLEN + 1];
+static struct iscsi_ev_context ipc_ev_context;
static int request_initiator_name(void)
{
@@ -75,7 +80,7 @@ static int request_initiator_name(void)
rc = iscsid_exec_req(&req, &rsp, 1);
if (rc)
- return EIO;
+ return rc;
if (rsp.u.config.var[0] != '\0')
strcpy(initiator_name, rsp.u.config.var);
@@ -107,14 +112,14 @@ int discovery_isns_set_servername(char *
if (port > USHRT_MAX) {
log_error("Invalid port %d\n", port);
- return EINVAL;
+ return ISCSI_ERR_INVAL;
}
/* 5 for port and 1 for colon and 1 for null */
len = strlen(address) + 7;
server = calloc(1, len);
if (!server)
- return ENOMEM;
+ return ISCSI_ERR_NOMEM;
snprintf(server, len, "%s:%d", address, port);
isns_assign_string(&isns_config.ic_server_name, server);
@@ -136,11 +141,11 @@ int discovery_isns_query(struct discover
isns_config.ic_security = 0;
source = isns_source_create_iscsi(iname);
if (!source)
- return ENOMEM;
+ return ISCSI_ERR_NOMEM;
clnt = isns_create_client(NULL, iname);
if (!clnt) {
- rc = ENOMEM;
+ rc = ISCSI_ERR_NOMEM;
goto free_src;
}
@@ -158,7 +163,7 @@ int discovery_isns_query(struct discover
qry = isns_create_query2(clnt, &key_attrs, source);
if (!qry) {
- rc = ENOMEM;
+ rc = ISCSI_ERR_NOMEM;
goto free_clnt;
}
@@ -177,11 +182,11 @@ int discovery_isns_query(struct discover
break;
case ISNS_SOURCE_UNKNOWN:
/* server requires that we are registered but we are not */
- rc = ENOENT;
+ rc = ISCSI_ERR_ISNS_REG_FAILED;
goto free_query;
default:
log_error("iSNS discovery failed: %s", isns_strerror(status));
- rc = EIO;
+ rc = ISCSI_ERR_ISNS_QUERY;
goto free_query;
}
@@ -189,7 +194,7 @@ int discovery_isns_query(struct discover
if (status) {
log_error("Unable to extract object list from query "
"response: %s\n", isns_strerror(status));
- rc = EIO;
+ rc = ISCSI_ERR;
goto free_query;
}
@@ -239,7 +244,7 @@ int discovery_isns_query(struct discover
rec = calloc(1, sizeof(*rec));
if (!rec) {
- rc = ENOMEM;
+ rc = ISCSI_ERR_NOMEM;
goto destroy_list;
}
@@ -291,11 +296,11 @@ static int discovery_isns_reg_node(const
source = isns_source_create_iscsi(iname);
if (!source)
- return ENOMEM;
+ return ISCSI_ERR_NOMEM;
clnt = isns_create_client(NULL, iname);
if (!clnt) {
- rc = ENOMEM;
+ rc = ISCSI_ERR_NOMEM;
goto free_src;
}
@@ -303,7 +308,7 @@ static int discovery_isns_reg_node(const
ISNS_DEVICE_DEREGISTER,
source, NULL);
if (!reg) {
- rc = ENOMEM;
+ rc = ISCSI_ERR_NOMEM;
goto free_clnt;
}
@@ -318,7 +323,7 @@ static int discovery_isns_reg_node(const
log_error("Could not %s %s with iSNS server: %s.",
reg ? "register" : "deregister", iname,
isns_strerror(status));
- rc = EIO;
+ rc = ISCSI_ERR_ISNS_REG_FAILED;
} else
log_debug(1, "%s %s with iSNS server successful.",
op_reg ? "register" : "deregister", iname);
@@ -339,11 +344,17 @@ int discovery_isns(void *data, struct if
if (iface && strlen(iface->iname))
iname = iface->iname;
else {
- if (request_initiator_name() || initiator_name[0] == '\0') {
+ rc = request_initiator_name();
+ if (rc) {
log_error("Cannot perform discovery. Initiatorname "
"required.");
- return EINVAL;
+ return rc;
+ } else if (initiator_name[0] == '\0') {
+ log_error("Cannot perform discovery. Invalid "
+ "Initiatorname.");
+ return ISCSI_ERR_INVAL;
}
+
iname = initiator_name;
}
@@ -352,7 +363,7 @@ int discovery_isns(void *data, struct if
return rc;
retry:
rc = discovery_isns_query(drec, iname, NULL, rec_list);
- if (!registered && rc == ENOENT) {
+ if (!registered && rc == ISCSI_ERR_ISNS_REG_FAILED) {
rc = discovery_isns_reg_node(iname, 1);
if (!rc) {
registered = 1;
@@ -396,7 +407,7 @@ int discovery_fw(void *data, struct ifac
if (!rec) {
log_error("Could not convert firmware info to "
"node record.\n");
- rc = ENOMEM;
+ rc = ISCSI_ERR_NOMEM;
goto free_targets;
}
rec->disc_type = drec->type;
@@ -428,10 +439,10 @@ int discovery_offload_sendtargets(int ho
/* resolve the DiscoveryAddress to an IP address */
sprintf(default_port, "%d", drec->port);
- if (resolve_address(drec->address, default_port, &ss)) {
- log_error("Cannot resolve host name %s.", drec->address);
- return EIO;
- }
+ rc = resolve_address(drec->address, default_port, &ss);
+ if (rc)
+ return rc;
+
req.u.st.ss = ss;
/*
@@ -447,8 +458,8 @@ int discovery_offload_sendtargets(int ho
if (rc) {
log_error("Could not offload sendtargets to %s.\n",
drec->address);
- iscsid_handle_error(rc);
- return EIO;
+ iscsi_err_print_msg(rc);
+ return rc;
}
return 0;
@@ -490,15 +501,12 @@ request_targets(iscsi_session_t *session
if (!iscsi_add_text(hdr, data, sizeof (data), "SendTargets", "All")) {
log_error("failed to add SendTargets text key");
- exit(1);
+ return 0;
}
text.ttt = ISCSI_RESERVED_TAG;
text.flags = ISCSI_FLAG_CMD_FINAL;
- if (++session->itt == ISCSI_RESERVED_TAG)
- session->itt = 1;
-
if (!iscsi_io_send_pdu(&session->conn[0], hdr, ISCSI_DIGEST_NONE, data,
ISCSI_DIGEST_NONE, session->conn[0].active_timeout)) {
log_error("failed to send SendTargets PDU");
@@ -527,9 +535,6 @@ iterate_targets(iscsi_session_t *session
text.ttt = ttt;
text.flags = ISCSI_FLAG_CMD_FINAL;
- if (++session->itt == ISCSI_RESERVED_TAG)
- session->itt = 1;
-
if (!iscsi_io_send_pdu(&session->conn[0], pdu, ISCSI_DIGEST_NONE, data,
ISCSI_DIGEST_NONE, session->conn[0].active_timeout)) {
log_error("failed to send empty text PDU");
@@ -543,19 +548,13 @@ static int add_portal(struct list_head *
char *targetname, char *address, char *port, char *tag)
{
struct sockaddr_storage ss;
- char host[NI_MAXHOST];
struct node_rec *rec;
- /* resolve the address, in case it was a DNS name */
if (resolve_address(address, port, &ss)) {
log_error("cannot resolve %s", address);
return 0;
}
- /* convert the resolved name to text */
- getnameinfo((struct sockaddr *) &ss, sizeof(ss),
- host, sizeof(host), NULL, 0, NI_NUMERICHOST);
-
rec = calloc(1, sizeof(*rec));
if (!rec)
return 0;
@@ -582,7 +581,7 @@ static int add_portal(struct list_head *
static int
add_target_record(char *name, char *end, discovery_rec_t *drec,
- struct list_head *rec_list, char *default_port)
+ struct list_head *rec_list)
{
char *text = NULL;
char *nul = name;
@@ -625,11 +624,16 @@ add_target_record(char *name, char *end,
log_error("no default address known for target %s",
name);
return 0;
- } else if (!add_portal(rec_list, drec, name, drec->address,
- default_port, NULL)) {
- log_error("failed to add default portal, ignoring "
- "target %s", name);
- return 0;
+ } else {
+ char default_port[NI_MAXSERV];
+
+ sprintf(default_port, "%d", drec->port);
+ if (!add_portal(rec_list, drec, name, drec->address,
+ default_port, NULL)) {
+ log_error("failed to add default portal, "
+ "ignoring target %s", name);
+ return 0;
+ }
}
/* finished adding the default */
return 1;
@@ -681,8 +685,7 @@ add_target_record(char *name, char *end,
static int
process_sendtargets_response(struct str_buffer *sendtargets,
int final, discovery_rec_t *drec,
- struct list_head *rec_list,
- char *default_port)
+ struct list_head *rec_list)
{
char *start = str_buffer_data(sendtargets);
char *text = start;
@@ -733,8 +736,7 @@ process_sendtargets_response(struct str_
* "TargetName=" prefix.
*/
if (!add_target_record(record + 11, text,
- drec, rec_list,
- default_port)) {
+ drec, rec_list)) {
log_error(
"failed to add target record");
str_truncate_buffer(sendtargets, 0);
@@ -762,7 +764,7 @@ process_sendtargets_response(struct str_
"line %s",
record, record);
if (add_target_record (record + 11, text,
- drec, rec_list, default_port)) {
+ drec, rec_list)) {
num_targets++;
record = NULL;
str_truncate_buffer(sendtargets, 0);
@@ -792,110 +794,47 @@ process_sendtargets_response(struct str_
return 1;
}
-static void
-clear_timer(struct timeval *timer)
-{
- memset(timer, 0, sizeof (*timer));
-}
-
-/* set timer to now + seconds */
-static void
-set_timer(struct timeval *timer, int seconds)
-{
- if (timer) {
- memset(timer, 0, sizeof (*timer));
- gettimeofday(timer, NULL);
-
- timer->tv_sec += seconds;
- }
-}
-
-static int
-timer_expired(struct timeval *timer)
-{
- struct timeval now;
-
- /* no timer, can't have expired */
- if ((timer == NULL) || ((timer->tv_sec == 0) && (timer->tv_usec == 0)))
- return 0;
-
- memset(&now, 0, sizeof (now));
- gettimeofday(&now, NULL);
-
- if (now.tv_sec > timer->tv_sec)
- return 1;
- if ((now.tv_sec == timer->tv_sec) && (now.tv_usec >= timer->tv_usec))
- return 1;
- return 0;
-}
-
-static int
-msecs_until(struct timeval *timer)
+static void iscsi_free_session(struct iscsi_session *session)
{
- struct timeval now;
- int msecs;
- long partial;
-
- /* no timer, can't have expired, infinite time til it expires */
- if ((timer == NULL) || ((timer->tv_sec == 0) && (timer->tv_usec == 0)))
- return -1;
-
- memset(&now, 0, sizeof (now));
- gettimeofday(&now, NULL);
-
- /* already expired? */
- if (now.tv_sec > timer->tv_sec)
- return 0;
- if ((now.tv_sec == timer->tv_sec) && (now.tv_usec >= timer->tv_usec))
- return 0;
-
- /* not expired yet, do the math */
- partial = timer->tv_usec - now.tv_usec;
- if (partial < 0) {
- partial += 1000 * 1000;
- msecs = (partial + 500) / 1000;
- msecs += (timer->tv_sec - now.tv_sec - 1) * 1000;
- } else {
- msecs = (partial + 500) / 1000;
- msecs += (timer->tv_sec - now.tv_sec) * 1000;
- }
-
- return msecs;
+ list_del_init(&session->list);
+ free(session);
}
static iscsi_session_t *
-init_new_session(struct iscsi_sendtargets_config *config,
- struct iface_rec *iface)
+iscsi_alloc_session(struct iscsi_sendtargets_config *config,
+ struct iface_rec *iface, int *rc)
{
iscsi_session_t *session;
+ *rc = 0;
+
session = calloc(1, sizeof (*session));
- if (session == NULL)
- goto done;
+ if (session == NULL) {
+ *rc = ISCSI_ERR_NOMEM;
+ return NULL;
+ }
+ session->t = iscsi_sysfs_get_transport_by_name(iface->transport_name);
+ if (!session->t) {
+ log_error("iSCSI driver %s is not loaded. Load the module "
+ "then retry the command.\n", iface->transport_name);
+ *rc = ISCSI_ERR_TRANS_NOT_FOUND;
+ goto fail;
+ }
+
+ INIT_LIST_HEAD(&session->list);
/* initialize the session's leading connection */
+ session->conn[0].id = 0;
session->conn[0].socket_fd = -1;
+ session->conn[0].session = session;
session->conn[0].login_timeout = config->conn_timeo.login_timeout;
session->conn[0].auth_timeout = config->conn_timeo.auth_timeout;
session->conn[0].active_timeout = config->conn_timeo.active_timeout;
- session->conn[0].hdrdgst_en = ISCSI_DIGEST_NONE;
- session->conn[0].datadgst_en = ISCSI_DIGEST_NONE;
-
- session->conn[0].max_recv_dlength =
- config->iscsi.MaxRecvDataSegmentLength;
- if (session->conn[0].max_recv_dlength < ISCSI_MIN_MAX_RECV_SEG_LEN ||
- session->conn[0].max_recv_dlength > ISCSI_MAX_MAX_RECV_SEG_LEN) {
- log_error("Invalid iscsi.MaxRecvDataSegmentLength. Must be "
- "within %u and %u. Setting to %u.",
- ISCSI_MIN_MAX_RECV_SEG_LEN,
- ISCSI_MAX_MAX_RECV_SEG_LEN,
- DEF_INI_DISC_MAX_RECV_SEG_LEN);
- session->conn[0].max_recv_dlength =
- DEF_INI_DISC_MAX_RECV_SEG_LEN;
- }
- session->conn[0].max_xmit_dlength = ISCSI_DEF_MAX_RECV_SEG_LEN;
-
+ session->conn[0].noop_out_timeout = 0;
+ session->conn[0].noop_out_interval = 0;
session->reopen_cnt = config->reopen_max + 1;
+ iscsi_copy_operational_params(&session->conn[0], &config->session_conf,
+ &config->conn_conf);
/* OUI and uniqifying number */
session->isid[0] = DRIVER_ISID_0;
@@ -905,111 +844,41 @@ init_new_session(struct iscsi_sendtarget
session->isid[4] = 0;
session->isid[5] = 0;
- request_initiator_name();
-
if (iface && strlen(iface->iname)) {
strcpy(initiator_name, iface->iname);
/* MNC TODO add iface alias */
} else {
- if (initiator_name[0] == '\0') {
+ *rc = request_initiator_name();
+ if (*rc) {
log_error("Cannot perform discovery. Initiatorname "
"required.");
- free(session);
- return NULL;
+ goto fail;
+ } else if (initiator_name[0] == '\0') {
+ log_error("Cannot perform discovery. Invalid "
+ "Initiatorname.");
+ *rc = ISCSI_ERR_INVAL;
+ goto fail;
}
}
+ iface_copy(&session->nrec.iface, iface);
session->initiator_name = initiator_name;
session->initiator_alias = initiator_alias;
session->portal_group_tag = PORTAL_GROUP_TAG_UNKNOWN;
session->type = ISCSI_SESSION_TYPE_DISCOVERY;
-done:
- return session;
-}
-
+ session->id = -1;
-static int
-setup_authentication(iscsi_session_t *session,
- discovery_rec_t *drec,
- struct iscsi_sendtargets_config *config)
-{
- int rc;
-
- rc = 1;
-
- /* if we have any incoming credentials, we insist on authenticating
- * the target or not logging in at all
- */
- if (config->auth.username_in[0]
- || config->auth.password_in_length) {
- session->bidirectional_auth = 1;
-
- /* sanity check the config */
- if (config->auth.password_length == 0) {
- log_error(
- "discovery process to %s:%d has incoming "
- "authentication credentials but has no outgoing "
- "credentials configured",
- drec->address, drec->port);
- log_error(
- "discovery process to %s:%d exiting, bad "
- "configuration",
- drec->address, drec->port);
- rc = 0;
- goto done;
- }
- } else {
- /* no or 1-way authentication */
- session->bidirectional_auth = 0;
- }
+ /* setup authentication variables for the session*/
+ *rc = iscsi_setup_authentication(session, &config->auth);
+ if (*rc)
+ goto fail;
- /* copy in whatever credentials we have */
- strlcpy(session->username, config->auth.username,
- sizeof (session->username));
- session->username[sizeof (session->username) - 1] = '\0';
- if ((session->password_length = config->auth.password_length))
- memcpy(session->password, config->auth.password,
- session->password_length);
-
- strlcpy(session->username_in, config->auth.username_in,
- sizeof (session->username_in));
- session->username_in[sizeof (session->username_in) - 1] = '\0';
- if ((session->password_in_length =
- config->auth.password_in_length))
- memcpy(session->password_in, config->auth.password_in,
- session->password_in_length);
-
- if (session->password_length || session->password_in_length) {
- /* setup the auth buffers */
- session->auth_buffers[0].address = &session->auth_client_block;
- session->auth_buffers[0].length =
- sizeof (session->auth_client_block);
- session->auth_buffers[1].address =
- &session->auth_recv_string_block;
- session->auth_buffers[1].length =
- sizeof (session->auth_recv_string_block);
-
- session->auth_buffers[2].address =
- &session->auth_send_string_block;
- session->auth_buffers[2].length =
- sizeof (session->auth_send_string_block);
-
- session->auth_buffers[3].address =
- &session->auth_recv_binary_block;
- session->auth_buffers[3].length =
- sizeof (session->auth_recv_binary_block);
-
- session->auth_buffers[4].address =
- &session->auth_send_binary_block;
- session->auth_buffers[4].length =
- sizeof (session->auth_send_binary_block);
+ list_add_tail(&session->list, &session->t->sessions);
+ return session;
- session->num_auth_buffers = 5;
- } else {
- session->num_auth_buffers = 0;
- }
- done:
- return(rc);
+fail:
+ free(session);
+ return NULL;
}
static int
@@ -1018,7 +887,6 @@ process_recvd_pdu(struct iscsi_hdr *pdu,
struct list_head *rec_list,
iscsi_session_t *session,
struct str_buffer *sendtargets,
- char *default_port,
int *active,
int *valid_text,
char *data)
@@ -1063,8 +931,7 @@ process_recvd_pdu(struct iscsi_hdr *pdu,
process_sendtargets_response(sendtargets,
final,
drec,
- rec_list,
- default_port);
+ rec_list);
if (final) {
/* SendTargets exchange is now complete
@@ -1095,12 +962,11 @@ process_recvd_pdu(struct iscsi_hdr *pdu,
return(rc);
}
+#if 0 /* Unused */
/*
- * Make a best effort to logout the session, then disconnect the
- * socket.
+ * Make a best effort to logout the session.
*/
-static void
-iscsi_logout_and_disconnect(iscsi_session_t * session)
+static void iscsi_logout(iscsi_session_t * session)
{
struct iscsi_logout logout_req;
struct iscsi_logout_rsp logout_resp;
@@ -1128,7 +994,7 @@ iscsi_logout_and_disconnect(iscsi_sessio
if (!rc) {
log_error(
"iscsid: iscsi_logout - failed to send logout PDU.");
- goto done;
+ return;
}
/*
@@ -1138,117 +1004,362 @@ iscsi_logout_and_disconnect(iscsi_sessio
rc = iscsi_io_recv_pdu(&session->conn[0],
(struct iscsi_hdr *)&logout_resp, ISCSI_DIGEST_NONE, NULL,
0, ISCSI_DIGEST_NONE, 1);
- if (!rc) {
+ if (rc < 0) {
log_error("iscsid: logout - failed to receive logout resp");
- goto done;
+ return;
}
if (logout_resp.response != ISCSI_LOGOUT_SUCCESS) {
log_error("iscsid: logout failed - response = 0x%x",
logout_resp.response);
}
+}
+#endif /* Unused */
+
+static void iscsi_destroy_session(struct iscsi_session *session)
+{
+ struct iscsi_transport *t = session->t;
+ struct iscsi_conn *conn = &session->conn[0];
+ int rc;
+
+ if (session->id == -1)
+ return;
+
+ if (!(t->caps & CAP_TEXT_NEGO)) {
+ iscsi_io_disconnect(&session->conn[0]);
+ goto done;
+ }
+ log_debug(2, "%s ep disconnect", __FUNCTION__);
+ t->template->ep_disconnect(conn);
+
+ log_debug(2, "stop conn");
+ rc = ipc->stop_conn(session->t->handle, session->id,
+ conn->id, STOP_CONN_TERM);
+ if (rc) {
+ log_error("Could not stop conn %d:%d cleanly (err %d)\n",
+ session->id, conn->id, rc);
+ goto done;
+ }
+
+ log_debug(2, "%s destroy conn", __FUNCTION__);
+ rc = ipc->destroy_conn(session->t->handle, session->id, conn->id);
+ if (rc) {
+ log_error("Could not safely destroy conn %d:%d (err %d)",
+ session->id, conn->id, rc);
+ goto done;
+ }
+
+ log_debug(2, "%s destroy session", __FUNCTION__);
+ rc = ipc->destroy_session(session->t->handle, session->id);
+ if (rc)
+ log_error("Could not safely destroy session %d (err %d)",
+ session->id, rc);
done:
+ if (conn->socket_fd >= 0) {
+ ipc->ctldev_close();
+ conn->socket_fd = -1;
+ }
+ session->id = -1;
+}
+
+static int iscsi_create_leading_conn(struct iscsi_session *session)
+{
+ struct iface_rec *iface = &session->nrec.iface;
+ struct iscsi_transport *t = session->t;
+ struct iscsi_conn *conn = &session->conn[0];
+ uint32_t host_no;
+ int rc, sleep_count = 0;
+
+ if (!(t->caps & CAP_TEXT_NEGO)) {
+ /*
+ * If the LLD does not support TEXT PDUs then we do
+ * discovery in userspace.
+ */
+ session->use_ipc = 0;
+
+ if (!iscsi_io_connect(conn))
+ return ISCSI_ERR_TRANS;
+
+ session->id = 1;
+ return 0;
+ }
+ session->use_ipc = 1;
+
/*
- * Close the socket.
+ * for software this is the tcp socket fd set in iscsi_io_connect
+ * and for offload this is the iscsi netlink socket fd
*/
- iscsi_io_disconnect(&session->conn[0]);
+ conn->socket_fd = ipc->ctldev_open();
+ if (conn->socket_fd < 0) {
+ log_error("Could not open netlink interface (err %d)\n",
+ errno);
+ return ISCSI_ERR_INTERNAL;
+ }
+
+ host_no = iscsi_sysfs_get_host_no_from_hwinfo(iface, &rc);
+ if (!rc) {
+ /*
+ * if the netdev or mac was set, then we are going to want
+ * to want to bind the all the conns/eps to a specific host
+ * if offload is used.
+ */
+ session->conn[0].bind_ep = 1;
+ session->hostno = host_no;
+ }
+
+ rc = iscsi_host_set_net_params(iface, session);
+ if (rc) {
+ log_error("Could not set host net params (err %d)\n",
+ rc);
+ rc = ISCSI_ERR_INTERNAL;
+ goto close_ipc;
+ }
+
+ /* create interconnect endpoint */
+ log_debug(2, "%s discovery ep connect\n", __FUNCTION__);
+ rc = t->template->ep_connect(conn, 1);
+ if (rc < 0) {
+ rc = ISCSI_ERR_TRANS;
+ goto close_ipc;
+ }
+
+ do {
+ rc = t->template->ep_poll(conn, 1);
+ if (rc < 0) {
+ rc = ISCSI_ERR_TRANS;
+ goto disconnect;
+ } else if (rc == 0) {
+ if (sleep_count == conn->login_timeout) {
+ rc = ISCSI_ERR_TRANS_TIMEOUT;
+ goto disconnect;
+ }
+ sleep_count++;
+ sleep(1);
+ } else
+ break;
+ } while (1);
+
+ log_debug(2, "%s discovery create session\n", __FUNCTION__);
+ /* create kernel structs */
+ rc = ipc->create_session(session->t->handle,
+ conn->transport_ep_handle, 1, 32, 1,
+ &session->id, &host_no);
+ if (rc) {
+ log_error("Could not create kernel session (err %d).\n", rc);
+ rc = ISCSI_ERR_INTERNAL;
+ goto disconnect;
+ }
+ log_debug(2, "%s discovery created session %u\n", __FUNCTION__,
+ session->id);
+ session->isid[3] = session->id;
+
+ log_debug(2, "%s discovery create conn\n", __FUNCTION__);
+ rc = ipc->create_conn(t->handle, session->id, conn->id, &conn->id);
+ if (rc) {
+ log_error("Could not create connection (err %d)", rc);
+ rc = ISCSI_ERR_INTERNAL;
+ goto disconnect;
+ }
+
+ log_debug(2, "%s discovery bind conn\n", __FUNCTION__);
+ if (ipc->bind_conn(t->handle, session->id, conn->id,
+ conn->transport_ep_handle, (conn->id == 0), &rc) ||
+ rc) {
+ log_error("Could not bind conn %d:%d to session %d, "
+ "(err %d)", session->id, conn->id,
+ session->id, rc);
+ rc = ISCSI_ERR_INTERNAL;
+ goto disconnect;
+ }
+
+ /* all set */
+ return 0;
+
+disconnect:
+ t->template->ep_disconnect(conn);
+
+ if (session->id != -1 &&
+ iscsi_sysfs_session_has_leadconn(session->id)) {
+ if (ipc->destroy_conn(session->t->handle, session->id,
+ conn->id))
+ log_error("Could not safely destroy connection %d:%d",
+ session->id, conn->id);
+ }
+
+ if (session->id != -1) {
+ if (ipc->destroy_session(session->t->handle, session->id))
+ log_error("Could not safely destroy session %d",
+ session->id);
+ session->id = -1;
+ }
+
+close_ipc:
+ if (conn->socket_fd >= 0) {
+ ipc->ctldev_close();
+ conn->socket_fd = -1;
+ }
+
+ log_error("Connection to discovery portal %s failed: %s",
+ conn->host, iscsi_err_to_str(rc));
+ return rc;
}
-int discovery_sendtargets(void *fndata, struct iface_rec *iface,
- struct list_head *rec_list)
+static struct iscsi_ev_context *
+iscsi_ev_context_get(struct iscsi_conn *conn, int ev_size)
{
- discovery_rec_t *drec = fndata;
- iscsi_session_t *session;
+ log_debug(2, "%s: ev_size %d\n", __FUNCTION__, ev_size);
+
+ ipc_ev_context.data = calloc(1, ev_size);
+ if (!ipc_ev_context.data)
+ return NULL;
+
+ return &ipc_ev_context;
+}
+
+static void iscsi_ev_context_put(struct iscsi_ev_context *ev_context)
+{
+ if (ev_context->data)
+ free(ev_context->data);
+ ev_context->data = NULL;
+}
+
+static int iscsi_sched_ev_context(struct iscsi_ev_context *ev_context,
+ struct iscsi_conn *conn, unsigned long tmo,
+ int event)
+{
+ if (event == EV_CONN_RECV_PDU || event == EV_CONN_LOGIN) {
+ conn->recv_context = ev_context;
+ return 0;
+ }
+
+ return -EIO;
+}
+
+static struct iscsi_ipc_ev_clbk ipc_clbk = {
+ .get_ev_context = iscsi_ev_context_get,
+ .put_ev_context = iscsi_ev_context_put,
+ .sched_ev_context = iscsi_sched_ev_context,
+};
+
+static int iscsi_wait_for_login(struct iscsi_conn *conn)
+{
+ struct iscsi_session *session = conn->session;
+ struct iscsi_transport *t = session->t;
struct pollfd pfd;
- struct iscsi_hdr pdu_buffer;
- struct iscsi_hdr *pdu = &pdu_buffer;
- char *data = NULL;
- int active = 0, valid_text = 0;
struct timeval connection_timer;
- int timeout;
- int rc;
- struct str_buffer sendtargets;
- uint8_t status_class = 0, status_detail = 0;
- unsigned int login_failures = 0, data_len;
- int login_delay = 0;
- struct sockaddr_storage ss;
- char host[NI_MAXHOST], serv[NI_MAXSERV], default_port[NI_MAXSERV];
- struct iscsi_sendtargets_config *config = &drec->u.sendtargets;
+ int timeout, rc;
+ uint32_t conn_state;
+ int status = 0;
- /* initial setup */
- log_debug(1, "starting sendtargets discovery, address %s:%d, ",
- drec->address, drec->port);
- memset(&pdu_buffer, 0, sizeof (pdu_buffer));
- clear_timer(&connection_timer);
+ if (!(t->caps & CAP_LOGIN_OFFLOAD))
+ return 0;
- /* allocate a new session, and initialize default values */
- session = init_new_session(config, iface);
- if (session == NULL) {
- log_error("Discovery process to %s:%d failed to "
- "create a discovery session.",
- drec->address, drec->port);
- return 1;
- }
+ iscsi_timer_set(&connection_timer, conn->active_timeout);
- log_debug(4, "sendtargets discovery to %s:%d using "
- "isid 0x%02x%02x%02x%02x%02x%02x",
- drec->address, drec->port, session->isid[0],
- session->isid[1], session->isid[2], session->isid[3],
- session->isid[4], session->isid[5]);
+ /* prepare to poll */
+ memset(&pfd, 0, sizeof(pfd));
+ pfd.fd = conn->socket_fd;
+ pfd.events = POLLIN | POLLPRI;
- /* allocate data buffers for SendTargets data */
- data = malloc(session->conn[0].max_recv_dlength);
- if (!data) {
- rc = 1;
- goto free_session;
- }
- data_len = session->conn[0].max_recv_dlength;
+ timeout = iscsi_timer_msecs_until(&connection_timer);
- str_init_buffer(&sendtargets, 0);
+login_repoll:
+ log_debug(4, "discovery login process polling fd %d, "
+ "timeout in %f seconds", pfd.fd, timeout / 1000.0);
- sprintf(default_port, "%d", drec->port);
- /* resolve the DiscoveryAddress to an IP address */
- if (resolve_address(drec->address, default_port, &ss)) {
- log_error("cannot resolve host name %s", drec->address);
- rc = 1;
- goto free_sendtargets;
+ pfd.revents = 0;
+ rc = poll(&pfd, 1, timeout);
+
+ log_debug(7, "discovery login process returned from poll, rc %d", rc);
+
+ if (iscsi_timer_expired(&connection_timer)) {
+ log_warning("Discovery login session timed out.");
+ rc = ISCSI_ERR_INTERNAL;
+ goto done;
}
- log_debug(4, "discovery timeouts: login %d, reopen_cnt %d, auth %d.",
- session->conn[0].login_timeout, session->reopen_cnt,
- session->conn[0].auth_timeout);
+ if (rc > 0) {
+ if (pfd.revents & (POLLIN | POLLPRI)) {
+ timeout = iscsi_timer_msecs_until(&connection_timer);
+ status = ipc->recv_conn_state(conn, &conn_state);
+ if (status == -EAGAIN)
+ goto login_repoll;
+ else if (status < 0) {
+ rc = ISCSI_ERR_TRANS;
+ goto done;
+ }
- /* setup authentication variables for the session*/
- rc = setup_authentication(session, drec, config);
- if (rc == 0) {
- rc = 1;
- goto free_sendtargets;
+ if (conn_state != ISCSI_CONN_STATE_LOGGED_IN)
+ rc = ISCSI_ERR_TRANS;
+ else
+ rc = 0;
+ goto done;
+ }
+
+ if (pfd.revents & POLLHUP) {
+ log_warning("discovery session"
+ "terminating after hangup");
+ rc = ISCSI_ERR_TRANS;
+ goto done;
+ }
+
+ if (pfd.revents & POLLNVAL) {
+ log_warning("discovery POLLNVAL");
+ rc = ISCSI_ERR_INTERNAL;
+ goto done;
+ }
+
+ if (pfd.revents & POLLERR) {
+ log_warning("discovery POLLERR");
+ rc = ISCSI_ERR_INTERNAL;
+ goto done;
+ }
+ } else if (rc < 0) {
+ log_error("Login poll error");
+ rc = ISCSI_ERR_INTERNAL;
+ goto done;
}
+done:
+ return rc;
+}
+
+static int iscsi_create_session(struct iscsi_session *session,
+ struct iscsi_sendtargets_config *config,
+ char *data, unsigned int data_len)
+{
+ struct iscsi_conn *conn = &session->conn[0];
+ int login_status, rc = 0, login_delay = 0;
+ uint8_t status_class = 0, status_detail = 0;
+ unsigned int login_failures = 0;
+ char serv[NI_MAXSERV];
+ struct iscsi_transport *t = session->t;
+
set_address:
/*
* copy the saved address to the session,
* undoing any temporary redirect
*/
- session->conn[0].saddr = ss;
+ conn->saddr = conn->failback_saddr;
reconnect:
-
+ /* fix decrement and test */
if (--session->reopen_cnt < 0) {
- log_error("connection login retries (reopen_max %d) exceeded",
+ log_error("connection login retries (reopen_max) %d exceeded",
config->reopen_max);
- rc = 1;
- goto free_sendtargets;
+ goto login_failed;
}
redirect_reconnect:
-
- iscsi_io_disconnect(&session->conn[0]);
-
session->cmdsn = 1;
session->itt = 1;
session->portal_group_tag = PORTAL_GROUP_TAG_UNKNOWN;
+ /*
+ * On reconnect, just destroy the kernel structs and start over.
+ */
+ iscsi_destroy_session(session);
+
/* slowly back off the frequency of login attempts */
if (login_failures == 0)
login_delay = 0;
@@ -1263,47 +1374,47 @@ redirect_reconnect:
else
login_delay = 60; /* after 2 minutes, try once a minute */
+ getnameinfo((struct sockaddr *) &conn->saddr,
+ sizeof(conn->saddr), conn->host,
+ sizeof(conn->host), serv, sizeof(serv),
+ NI_NUMERICHOST|NI_NUMERICSERV);
+
if (login_delay) {
- log_debug(4, "discovery session to %s:%d sleeping for %d "
+ log_debug(4, "discovery session to %s:%s sleeping for %d "
"seconds before next login attempt",
- drec->address, drec->port, login_delay);
+ conn->host, serv, login_delay);
sleep(login_delay);
}
-
- getnameinfo((struct sockaddr *) &session->conn[0].saddr,
- sizeof(session->conn[0].saddr), host,
- sizeof(host), serv, sizeof(serv),
- NI_NUMERICHOST|NI_NUMERICSERV);
-
- if (!iscsi_io_connect(&session->conn[0])) {
- log_error("connection to discovery address %s "
- "failed", host);
-
+ rc = iscsi_create_leading_conn(session);
+ if (rc) {
login_failures++;
- /* If a temporary redirect sent us to something unreachable,
- * we want to go back to the original IP address, so make sure
- * we reset the session's IP.
- */
- goto set_address;
+ goto reconnect;
}
- log_debug(1, "connected to discovery address %s", host);
+ log_debug(1, "connected to discovery address %s", conn->host);
- log_debug(4, "discovery session to %s:%d starting iSCSI login on fd %d",
- drec->address, drec->port, session->conn[0].socket_fd);
+ log_debug(4, "discovery session to %s:%s starting iSCSI login",
+ conn->host, serv);
- /* In case of discovery, we using socket's descriptor as ctrl. */
- session->ctrl_fd = session->conn[0].socket_fd;
- session->conn[0].session = session;
+ /*
+ * Need to re-init settings because a previous login could
+ * have set them to what was negotiated for.
+ */
+ iscsi_copy_operational_params(&session->conn[0], &config->session_conf,
+ &config->conn_conf);
+
+ if ((session->t->caps & CAP_LOGIN_OFFLOAD))
+ goto start_conn;
status_class = 0;
status_detail = 0;
+ rc = ISCSI_ERR_LOGIN;
memset(data, 0, data_len);
- rc = iscsi_login(session, 0, data, data_len,
- &status_class, &status_detail);
+ login_status = iscsi_login(session, 0, data, data_len,
+ &status_class, &status_detail);
- switch (rc) {
+ switch (login_status) {
case LOGIN_OK:
case LOGIN_REDIRECT:
break;
@@ -1311,8 +1422,7 @@ redirect_reconnect:
case LOGIN_IO_ERROR:
case LOGIN_REDIRECTION_FAILED:
/* try again */
- log_warning("retrying discovery login to %s", host);
- iscsi_io_disconnect(&session->conn[0]);
+ log_warning("retrying discovery login to %s", conn->host);
login_failures++;
goto set_address;
@@ -1322,16 +1432,16 @@ redirect_reconnect:
case LOGIN_AUTHENTICATION_FAILED:
case LOGIN_VERSION_MISMATCH:
case LOGIN_INVALID_PDU:
- log_error("discovery login to %s failed, giving up", host);
- iscsi_io_disconnect(&session->conn[0]);
- rc = 1;
- goto free_sendtargets;
+ log_error("discovery login to %s failed, giving up %d",
+ conn->host, login_status);
+ rc = ISCSI_ERR_FATAL_LOGIN;
+ goto login_failed;
}
/* check the login status */
switch (status_class) {
case ISCSI_STATUS_CLS_SUCCESS:
- log_debug(4, "discovery login success to %s", host);
+ log_debug(4, "discovery login success to %s", conn->host);
login_failures = 0;
break;
case ISCSI_STATUS_CLS_REDIRECT:
@@ -1343,14 +1453,16 @@ redirect_reconnect:
case ISCSI_LOGIN_STATUS_TGT_MOVED_TEMP:
log_warning(
"discovery login temporarily redirected to "
- "%s port %s", host, serv);
+ "%s port %s", conn->host, serv);
goto redirect_reconnect;
case ISCSI_LOGIN_STATUS_TGT_MOVED_PERM:
log_warning(
"discovery login permanently redirected to "
- "%s port %s", host, serv);
+ "%s port %s", conn->host, serv);
/* make the new address permanent */
- ss = session->conn[0].saddr;
+ memset(&conn->failback_saddr, 0,
+ sizeof(struct sockaddr_storage));
+ conn->failback_saddr = conn->saddr;
goto redirect_reconnect;
default:
log_error(
@@ -1361,32 +1473,133 @@ redirect_reconnect:
}
break;
case ISCSI_STATUS_CLS_INITIATOR_ERR:
- log_error(
- "discovery login to %s rejected: "
- "initiator error (%02x/%02x), non-retryable, giving up",
- host, status_class, status_detail);
- iscsi_io_disconnect(&session->conn[0]);
- rc = 1;
- goto free_sendtargets;
+ switch (status_detail) {
+ case ISCSI_LOGIN_STATUS_AUTH_FAILED:
+ case ISCSI_LOGIN_STATUS_TGT_FORBIDDEN:
+ log_error("discovery login to %s rejected: "
+ "initiator failed authorization\n",
+ conn->host);
+ rc = ISCSI_ERR_LOGIN_AUTH_FAILED;
+ goto login_failed;
+ default:
+ log_error("discovery login to %s rejected: initiator "
+ "error (%02x/%02x), non-retryable, giving up",
+ conn->host, status_class, status_detail);
+ rc = ISCSI_ERR_FATAL_LOGIN;
+ }
+ goto login_failed;
case ISCSI_STATUS_CLS_TARGET_ERR:
log_error(
"discovery login to %s rejected: "
"target error (%02x/%02x)",
- host, status_class, status_detail);
- iscsi_io_disconnect(&session->conn[0]);
+ conn->host, status_class, status_detail);
login_failures++;
goto reconnect;
default:
log_error(
"discovery login to %s failed, response "
"with unknown status class 0x%x, detail 0x%x",
- host,
+ conn->host,
status_class, status_detail);
- iscsi_io_disconnect(&session->conn[0]);
login_failures++;
goto reconnect;
}
+ if (!(t->caps & CAP_TEXT_NEGO))
+ return 0;
+
+start_conn:
+ log_debug(2, "%s discovery set params\n", __FUNCTION__);
+ rc = iscsi_session_set_params(conn);
+ if (rc) {
+ log_error("Could not set iscsi params for conn %d:%d (err "
+ "%d)\n", session->id, conn->id, rc);
+ rc = ISCSI_ERR_INTERNAL;
+ goto login_failed;
+ }
+
+ log_debug(2, "%s discovery start conn\n", __FUNCTION__);
+ if (ipc->start_conn(t->handle, session->id, conn->id, &rc) || rc) {
+ log_error("Cannot start conn %d:%d (err %d)",
+ session->id, conn->id, rc);
+ rc = ISCSI_ERR_INTERNAL;
+ goto login_failed;
+ }
+
+ rc = iscsi_wait_for_login(conn);
+ if (!rc)
+ return 0;
+
+login_failed:
+ iscsi_destroy_session(session);
+ return rc;
+}
+
+int discovery_sendtargets(void *fndata, struct iface_rec *iface,
+ struct list_head *rec_list)
+{
+ discovery_rec_t *drec = fndata;
+ iscsi_session_t *session;
+ struct pollfd pfd;
+ struct iscsi_hdr pdu_buffer;
+ struct iscsi_hdr *pdu = &pdu_buffer;
+ char *data = NULL;
+ int active = 0, valid_text = 0;
+ struct timeval connection_timer;
+ int timeout;
+ int rc = 0;
+ struct str_buffer sendtargets;
+ unsigned int data_len;
+ struct iscsi_sendtargets_config *config = &drec->u.sendtargets;
+
+ /* initial setup */
+ log_debug(1, "starting sendtargets discovery, address %s:%d, ",
+ drec->address, drec->port);
+ memset(&pdu_buffer, 0, sizeof (pdu_buffer));
+ iscsi_timer_clear(&connection_timer);
+
+ /* allocate a new session, and initialize default values */
+ session = iscsi_alloc_session(config, iface, &rc);
+ if (rc)
+ return rc;
+
+ ipc_ev_context.conn = &session->conn[0];
+ ipc_register_ev_callback(&ipc_clbk);
+
+ log_debug(4, "sendtargets discovery to %s:%d using "
+ "isid 0x%02x%02x%02x%02x%02x%02x",
+ drec->address, drec->port, session->isid[0],
+ session->isid[1], session->isid[2], session->isid[3],
+ session->isid[4], session->isid[5]);
+
+ /* allocate data buffers for SendTargets data */
+ data = malloc(session->conn[0].max_recv_dlength);
+ if (!data) {
+ rc = ISCSI_ERR_NOMEM;
+ goto free_session;
+ }
+ data_len = session->conn[0].max_recv_dlength;
+
+ str_init_buffer(&sendtargets, 0);
+
+ /* resolve the DiscoveryAddress to an IP address */
+ rc = iscsi_setup_portal(&session->conn[0], drec->address,
+ drec->port);
+ if (rc) {
+ log_error("cannot resolve host name %s", drec->address);
+ goto free_sendtargets;
+ }
+
+ log_debug(4, "discovery timeouts: login %d, reopen_cnt %d, auth %d.",
+ session->conn[0].login_timeout, session->reopen_cnt,
+ session->conn[0].auth_timeout);
+
+reconnect:
+ rc = iscsi_create_session(session, &drec->u.sendtargets,
+ data, data_len);
+ if (rc)
+ goto free_sendtargets;
+
/* reinitialize */
str_truncate_buffer(&sendtargets, 0);
@@ -1397,7 +1610,7 @@ redirect_reconnect:
active = 1;
/* set timeouts */
- set_timer(&connection_timer, session->conn[0].active_timeout);
+ iscsi_timer_set(&connection_timer, session->conn[0].active_timeout);
/* prepare to poll */
memset(&pfd, 0, sizeof (pfd));
@@ -1405,7 +1618,7 @@ redirect_reconnect:
pfd.events = POLLIN | POLLPRI;
repoll:
- timeout = msecs_until(&connection_timer);
+ timeout = iscsi_timer_msecs_until(&connection_timer);
/* block until we receive a PDU, a TCP FIN, a TCP RST,
* or a timeout
*/
@@ -1422,31 +1635,30 @@ repoll:
"discovery process to %s:%d returned from poll, rc %d",
drec->address, drec->port, rc);
- if (timer_expired(&connection_timer)) {
- log_warning("discovery session to %s:%d session "
- "logout, connection timer expired",
+ if (iscsi_timer_expired(&connection_timer)) {
+ log_warning("Discovery session to %s:%d timed out.",
drec->address, drec->port);
- iscsi_logout_and_disconnect(session);
- rc = 1;
- goto free_sendtargets;
+ rc = ISCSI_ERR_TRANS_TIMEOUT;
+ goto reconnect;
}
if (rc > 0) {
if (pfd.revents & (POLLIN | POLLPRI)) {
- timeout = msecs_until(&connection_timer);
+ timeout = iscsi_timer_msecs_until(&connection_timer);
- memset(data, 0, data_len);
- if (!iscsi_io_recv_pdu(&session->conn[0],
- pdu, ISCSI_DIGEST_NONE, data,
- data_len, ISCSI_DIGEST_NONE,
- timeout)) {
+ rc = iscsi_io_recv_pdu(&session->conn[0],
+ pdu, ISCSI_DIGEST_NONE, data,
+ data_len, ISCSI_DIGEST_NONE,
+ timeout);
+ if (rc == -EAGAIN)
+ goto repoll;
+ else if (rc < 0) {
log_debug(1, "discovery session to "
"%s:%d failed to recv a PDU "
"response, terminating",
drec->address,
drec->port);
- iscsi_io_disconnect(&session->conn[0]);
- rc = 1;
+ rc = ISCSI_ERR_PDU_TIMEOUT;
goto free_sendtargets;
}
@@ -1455,14 +1667,13 @@ repoll:
*/
rc = process_recvd_pdu(pdu, drec, rec_list,
session, &sendtargets,
- default_port,
&active, &valid_text, data);
if (rc == DISCOVERY_NEED_RECONNECT)
goto reconnect;
/* reset timers after receiving a PDU */
if (active) {
- set_timer(&connection_timer,
+ iscsi_timer_set(&connection_timer,
session->conn[0].active_timeout);
goto repoll;
}
@@ -1472,8 +1683,7 @@ repoll:
log_warning("discovery session to %s:%d "
"terminating after hangup",
drec->address, drec->port);
- iscsi_io_disconnect(&session->conn[0]);
- rc = 1;
+ rc = ISCSI_ERR_TRANS;
goto free_sendtargets;
}
@@ -1489,18 +1699,9 @@ repoll:
goto reconnect;
}
} else if (rc < 0) {
- if (errno == EINTR) {
- /* if we got SIGHUP, reconnect and rediscover */
- if (rediscover) {
- rediscover = 0;
- log_debug(1, "rediscovery requested");
- goto reconnect;
- }
- } else {
- log_error("poll error");
- rc = 1;
- goto free_sendtargets;
- }
+ log_error("poll error");
+ rc = ISCSI_ERR;
+ goto free_sendtargets;
}
log_debug(1, "discovery process to %s:%d exiting",
@@ -1510,8 +1711,9 @@ repoll:
free_sendtargets:
str_free_buffer(&sendtargets);
free(data);
+ iscsi_destroy_session(session);
free_session:
- free(session);
+ iscsi_free_session(session);
return rc;
}
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/discoveryd.c open-iscsi-2.0-872-rc4-bnx2i.work/usr/discoveryd.c
--- open-iscsi-2.0-872-rc4-bnx2i/usr/discoveryd.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/discoveryd.c 2012-03-05 23:02:46.000000000 -0600
@@ -44,6 +44,7 @@
#include "isns.h"
#include "paths.h"
#include "message.h"
+#include "iscsi_err.h"
#define DISC_DEF_POLL_INVL 30
@@ -242,12 +243,12 @@ static int isns_build_objs(isns_portal_i
nportals = isns_get_nr_portals();
log_debug(4, "got %d portals", nportals);
if (!nportals)
- return ENODEV;
+ return ISCSI_ERR_NO_OBJS_FOUND;
iflist = calloc(nportals, sizeof(isns_portal_info_t));
if (!iflist) {
log_error("Unable to allocate %d portals.", nportals);
- return ENOMEM;
+ return ISCSI_ERR_NOMEM;
}
nportals = isns_enumerate_portals(iflist, nportals);
@@ -255,7 +256,7 @@ static int isns_build_objs(isns_portal_i
log_error("Unable to enumerate portals - "
"no usable interfaces found\n");
free(iflist);
- return ENODEV;
+ return ISCSI_ERR_NO_OBJS_FOUND;
}
for (i = 0; i < nportals; ++i) {
iflist[i].addr.sin6_port = portal_info->addr.sin6_port;
@@ -267,7 +268,7 @@ static int isns_build_objs(isns_portal_i
if (!isns_entity_id) {
isns_entity_id = calloc(1, 256);
if (!isns_entity_id)
- return ENOMEM;
+ return ISCSI_ERR_NOMEM;
rc = getnameinfo((struct sockaddr *) &portal_info->addr,
sizeof(portal_info->addr),
@@ -277,14 +278,14 @@ static int isns_build_objs(isns_portal_i
isns_entity_id = NULL;
log_error("Could not get hostname for EID.");
- return EIO;
+ return ISCSI_ERR;
}
}
entity = isns_create_entity(ISNS_ENTITY_PROTOCOL_ISCSI, isns_entity_id);
if (!entity) {
log_error("Could not create iSNS entity.");
- return ENOMEM;
+ return ISCSI_ERR_NOMEM;
}
isns_object_list_append(objs, entity);
@@ -293,14 +294,14 @@ static int isns_build_objs(isns_portal_i
portal = isns_create_portal(portal_info, entity);
if (!portal) {
- rc = ENOMEM;
+ rc = ISCSI_ERR_NOMEM;
goto fail;
}
isns_object_list_append(objs, portal);
if (!isns_object_set_uint32(portal, ISNS_TAG_SCN_PORT,
isns_portal_tcpudp_port(portal_info))) {
- rc = EINVAL;
+ rc = ISCSI_ERR_INVAL;
goto fail;
}
}
@@ -310,7 +311,7 @@ static int isns_build_objs(isns_portal_i
ISNS_ISCSI_INITIATOR_MASK,
NULL);
if (!inode) {
- rc = ENOMEM;
+ rc = ISCSI_ERR_NOMEM;
goto fail;
}
isns_object_list_append(objs, inode);
@@ -366,7 +367,6 @@ static int isns_disc_new_portals(const c
qry_data.targetname = targetname;
qry_data.iname = iname;
-log_error("isns_disc_new_portals");
iface_link_ifaces(&ifaces);
rc = idbm_bind_ifaces_to_nodes(isns_query_node, &qry_data, &ifaces,
&rec_list);
@@ -559,7 +559,7 @@ static int isns_setup_registration_refre
log_error("Unable to extract object list from "
"registration response: %s\n",
isns_strerror(status));
- return EIO;
+ return ISCSI_ERR;
}
for (i = 0; i < objs.iol_count; ++i) {
@@ -578,7 +578,7 @@ static int isns_setup_registration_refre
refresh_data = calloc(1, sizeof(*refresh_data));
if (!refresh_data) {
- rc = ENOMEM;
+ rc = ISCSI_ERR_NOMEM;
goto free_objs;
}
INIT_LIST_HEAD(&refresh_data->list);
@@ -654,7 +654,7 @@ static int isns_register_objs(isns_clien
reg = isns_create_registration(clnt, entity);
if (!reg)
- return ENOMEM;
+ return ISCSI_ERR_NOMEM;
for (i = 0; i < objs->iol_count; ++i)
isns_registration_add_object(reg, objs->iol_data[i]);
@@ -664,7 +664,7 @@ static int isns_register_objs(isns_clien
if (status != ISNS_SUCCESS) {
log_error("Could not register with iSNS server: %s",
isns_strerror(status));
- rc = EIO;
+ rc = ISCSI_ERR;
goto free_reg;
}
log_debug(4, "Registered objs");
@@ -687,7 +687,7 @@ static int isns_register_objs(isns_clien
if (!reg) {
isns_cancel_refresh_timers();
- rc = ENOMEM;
+ rc = ISCSI_ERR_NOMEM;
goto done;
}
@@ -703,7 +703,7 @@ static int isns_register_objs(isns_clien
*/
if (poll_inval < 0) {
isns_cancel_refresh_timers();
- rc = EIO;
+ rc = ISCSI_ERR;
break;
}
}
@@ -727,7 +727,7 @@ static int isns_scn_register(isns_socket
clnt = isns_create_default_client(NULL);
if (!clnt) {
log_error("iSNS setup failed. Could not connect to server.");
- return ENOTCONN;
+ return ISCSI_ERR_TRANS;
}
isns_socket_set_disconnect_fatal(clnt->ic_socket);
@@ -735,7 +735,7 @@ static int isns_scn_register(isns_socket
if (!isns_socket_get_portal_info(svr_sock, &portal_info)) {
log_error("Could not get portal info for iSNS registration.");
- rc = ENODEV;
+ rc = ISCSI_ERR_NO_OBJS_FOUND;
goto destroy_clnt;
}
@@ -797,7 +797,7 @@ static int isns_create_node_list(const c
if (def_iname) {
node = isns_create_node(def_iname);
if (!node) {
- rc = ENOMEM;
+ rc = ISCSI_ERR_NOMEM;
goto fail;
}
list_add_tail(&node->list, &isns_initiators);
@@ -808,7 +808,7 @@ static int isns_create_node_list(const c
!isns_lookup_node(iface->iname)) {
node = isns_create_node(iface->iname);
if (!node) {
- rc = ENOMEM;
+ rc = ISCSI_ERR_NOMEM;
goto fail;
}
list_add_tail(&node->list, &isns_initiators);
@@ -943,7 +943,7 @@ static int isns_eventd(const char *def_i
isns_create_node_list(def_iname);
if (list_empty(&isns_initiators)) {
log_error("iSNS registration failed. Initiatorname not set.");
- return EINVAL;
+ return ISCSI_ERR_INVAL;
}
/* use def_iname or if not set the first iface's iname for the src */
@@ -955,7 +955,7 @@ static int isns_eventd(const char *def_i
isns_config.ic_control_socket = ISNS_EVENTD_CTL;
if (discovery_isns_set_servername(disc_addr, port)) {
- rc = ENOMEM;
+ rc = ISCSI_ERR_NOMEM;
goto fail;
}
@@ -964,13 +964,13 @@ static int isns_eventd(const char *def_i
db = isns_db_open(NULL);
if (!db) {
log_error("iSNS setup failed. Could not create db.");
- rc = ENOMEM;
+ rc = ISCSI_ERR_NOMEM;
goto fail;
}
svr = isns_create_server(node->source, db, &isns_callback_service_ops);
if (!svr) {
log_error("iSNS setup failed. Could not create server.");
- rc = ENOTCONN;
+ rc = ISCSI_ERR_TRANS;
goto fail;
}
isns_server_set_scn_callback(svr, isns_scn_callback);
@@ -978,7 +978,7 @@ static int isns_eventd(const char *def_i
svr_sock = isns_create_server_socket(NULL, NULL, AF_INET6, SOCK_DGRAM);
if (!svr_sock) {
log_error("iSNS setup failed. Could not create server socket.");
- rc = ENOTCONN;
+ rc = ISCSI_ERR_TRANS;
goto fail;
}
@@ -1077,7 +1077,7 @@ static int st_start(void *data, struct d
log_debug(1, "st_start %s:%d %d", drec->address, drec->port,
drec->u.sendtargets.use_discoveryd);
if (!drec->u.sendtargets.use_discoveryd)
- return ENOSYS;
+ return ISCSI_ERR_INVAL;
fork_disc(NULL, drec, drec->u.sendtargets.discoveryd_poll_inval,
do_st_disc_and_login);
@@ -1094,7 +1094,7 @@ static int isns_start(void *data, struct
log_debug(1, "isns_start %s:%d %d", drec->address, drec->port,
drec->u.isns.use_discoveryd);
if (!drec->u.isns.use_discoveryd)
- return ENOSYS;
+ return ISCSI_ERR_INVAL;
fork_disc(data, drec, drec->u.isns.discoveryd_poll_inval, start_isns);
return 0;
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/event_poll.c open-iscsi-2.0-872-rc4-bnx2i.work/usr/event_poll.c
--- open-iscsi-2.0-872-rc4-bnx2i/usr/event_poll.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/event_poll.c 2012-03-05 23:02:46.000000000 -0600
@@ -35,6 +35,7 @@
#include "iscsi_ipc.h"
#include "actor.h"
#include "initiator.h"
+#include "iscsi_err.h"
static int reap_count;
@@ -174,5 +175,5 @@ void event_loop(struct iscsi_ipc *ipc, i
sysfs_cleanup();
}
if (shutdown_qtask)
- mgmt_ipc_write_rsp(shutdown_qtask, MGMT_IPC_OK);
+ mgmt_ipc_write_rsp(shutdown_qtask, ISCSI_SUCCESS);
}
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/host.c open-iscsi-2.0-872-rc4-bnx2i.work/usr/host.c
--- open-iscsi-2.0-872-rc4-bnx2i/usr/host.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/host.c 2012-03-05 23:04:22.000000000 -0600
@@ -33,6 +33,7 @@
#include "transport.h"
#include "initiator.h"
#include "iface.h"
+#include "iscsi_err.h"
static int match_host_to_session(void *data, struct session_info *info)
{
@@ -117,6 +118,92 @@ static int host_info_print_flat(void *da
return 0;
}
+static int print_host_iface(void *data, struct iface_rec *iface)
+{
+ char *prefix = data;
+
+ printf("%s**********\n", prefix);
+ printf("%sInterface:\n", prefix);
+ printf("%s**********\n", prefix);
+
+ printf("%sKernel Name: %s\n", prefix, iface->name);
+
+ if (!strlen(iface->ipaddress))
+ printf("%sIPaddress: %s\n", prefix, UNKNOWN_VALUE);
+ else if (strchr(iface->ipaddress, '.')) {
+ printf("%sIPaddress: %s\n", prefix, iface->ipaddress);
+
+ if (!strlen(iface->gateway))
+ printf("%sGateway: %s\n", prefix, UNKNOWN_VALUE);
+ else
+ printf("%sGateway: %s\n", prefix, iface->gateway);
+ if (!strlen(iface->subnet_mask))
+ printf("%sSubnet: %s\n", prefix, UNKNOWN_VALUE);
+ else
+ printf("%sSubnet: %s\n", prefix, iface->subnet_mask);
+ if (!strlen(iface->bootproto))
+ printf("%sBootProto: %s\n", prefix, UNKNOWN_VALUE);
+ else
+ printf("%sBootProto: %s\n", prefix, iface->bootproto);
+ } else {
+ printf("%sIPaddress: [%s]\n", prefix, iface->ipaddress);
+
+ if (!strlen(iface->ipv6_autocfg))
+ printf("%sIPaddress Autocfg: %s\n", prefix,
+ UNKNOWN_VALUE);
+ else
+ printf("%sIPaddress Autocfg: %s\n", prefix,
+ iface->ipv6_autocfg);
+ if (!strlen(iface->ipv6_linklocal))
+ printf("%sLink Local Address: %s\n", prefix,
+ UNKNOWN_VALUE);
+ else
+ printf("%sLink Local Address: [%s]\n", prefix,
+ iface->ipv6_linklocal);
+ if (!strlen(iface->linklocal_autocfg))
+ printf("%sLink Local Autocfg: %s\n", prefix,
+ UNKNOWN_VALUE);
+ else
+ printf("%sLink Local Autocfg: %s\n", prefix,
+ iface->linklocal_autocfg);
+ if (!strlen(iface->ipv6_router))
+ printf("%sRouter Address: %s\n", prefix,
+ UNKNOWN_VALUE);
+ else
+ printf("%sRouter Address: [%s]\n", prefix,
+ iface->ipv6_router);
+ }
+
+ if (!iface->port)
+ printf("%sPort: %s\n", prefix, UNKNOWN_VALUE);
+ else
+ printf("%sPort: %u\n", prefix, iface->port);
+
+ if (!iface->mtu)
+ printf("%sMTU: %s\n", prefix, UNKNOWN_VALUE);
+ else
+ printf("%sMTU: %u\n", prefix, iface->mtu);
+
+ if (iface->vlan_id == UINT16_MAX)
+ printf("%sVLAN ID: %s\n", prefix, UNKNOWN_VALUE);
+ else
+ printf("%sVLAN ID: %u\n", prefix, iface->vlan_id);
+
+ if (iface->vlan_priority == UINT8_MAX)
+ printf("%sVLAN priority: %s\n", prefix, UNKNOWN_VALUE);
+ else
+ printf("%sVLAN priority: %u\n", prefix, iface->vlan_priority);
+ return 0;
+}
+
+static void print_host_ifaces(struct host_info *hinfo, char *prefix)
+{
+ int nr_found;
+
+ iscsi_sysfs_for_each_iface_on_host(prefix, hinfo->host_no, &nr_found,
+ print_host_iface);
+}
+
static int host_info_print_tree(void *data, struct host_info *hinfo)
{
struct list_head sessions;
@@ -127,6 +214,7 @@ static int host_info_print_tree(void *da
INIT_LIST_HEAD(&sessions);
+
printf("Host Number: %u\n", hinfo->host_no);
if (!iscsi_sysfs_get_host_state(state, hinfo->host_no))
printf("\tState: %s\n", state);
@@ -134,6 +222,8 @@ static int host_info_print_tree(void *da
printf("\tState: Unknown\n");
print_host_info(&hinfo->iface, "\t");
+ print_host_ifaces(hinfo, "\t");
+
if (!session_info_flags)
return 0;
@@ -150,7 +240,7 @@ static int host_info_print_tree(void *da
printf("\tSessions:\n");
printf("\t*********\n");
- session_info_print_tree(&sessions, "\t", session_info_flags);
+ session_info_print_tree(&sessions, "\t", session_info_flags, 0);
session_info_free_list(&sessions);
return 0;
}
@@ -200,13 +290,16 @@ int host_info_print(int info_level, uint
break;
default:
log_error("Invalid info level %d. Try 0 - 4.", info_level);
- return EINVAL;
+ return ISCSI_ERR_INVAL;
}
if (err) {
- log_error("Can not get list of iSCSI hosts (%d)", err);
+ log_error("Can not get list of iSCSI hosts: %s",
+ iscsi_err_to_str(err));
return err;
- } else if (!num_found)
+ } else if (!num_found) {
log_error("No iSCSI hosts.");
+ return ISCSI_ERR_NO_OBJS_FOUND;
+ }
return 0;
}
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/idbm.c open-iscsi-2.0-872-rc4-bnx2i.work/usr/idbm.c
--- open-iscsi-2.0-872-rc4-bnx2i/usr/idbm.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/idbm.c 2012-03-05 23:06:00.000000000 -0600
@@ -40,6 +40,7 @@
#include "iface.h"
#include "sysdeps.h"
#include "fw_context.h"
+#include "iscsi_err.h"
#define IDBM_HIDE 0 /* Hide parameter when print. */
#define IDBM_SHOW 1 /* Show parameter when print. */
@@ -71,6 +72,28 @@ static struct idbm *db;
_n++; \
} while(0)
+#define __recinfo_uint8(_key, _info, _rec, _name, _show, _n, _mod) do { \
+ _info[_n].type = TYPE_UINT8; \
+ strlcpy(_info[_n].name, _key, NAME_MAXVAL); \
+ snprintf(_info[_n].value, VALUE_MAXVAL, "%d", _rec->_name); \
+ _info[_n].data = &_rec->_name; \
+ _info[_n].data_len = sizeof(_rec->_name); \
+ _info[_n].visible = _show; \
+ _info[_n].can_modify = _mod; \
+ _n++; \
+} while (0)
+
+#define __recinfo_uint16(_key, _info, _rec, _name, _show, _n, _mod) do { \
+ _info[_n].type = TYPE_UINT16; \
+ strlcpy(_info[_n].name, _key, NAME_MAXVAL); \
+ snprintf(_info[_n].value, VALUE_MAXVAL, "%d", _rec->_name); \
+ _info[_n].data = &_rec->_name; \
+ _info[_n].data_len = sizeof(_rec->_name); \
+ _info[_n].visible = _show; \
+ _info[_n].can_modify = _mod; \
+ _n++; \
+} while (0)
+
#define __recinfo_int_o2(_key,_info,_rec,_name,_show,_op0,_op1,_n, _mod) do { \
_info[_n].type = TYPE_INT_O; \
strlcpy(_info[_n].name, _key, NAME_MAXVAL); \
@@ -179,7 +202,7 @@ idbm_recinfo_discovery(discovery_rec_t *
u.sendtargets.conn_timeo.active_timeout,
IDBM_SHOW, num, 1);
__recinfo_int(DISC_ST_MAX_RECV_DLEN, ri, r,
- u.sendtargets.iscsi.MaxRecvDataSegmentLength,
+ u.sendtargets.conn_conf.MaxRecvDataSegmentLength,
IDBM_SHOW, num, 1);
break;
case DISCOVERY_TYPE_ISNS:
@@ -208,6 +231,8 @@ idbm_recinfo_node(node_rec_t *r, recinfo
__recinfo_int(NODE_TPGT, ri, r, tpgt, IDBM_SHOW, num, 0);
__recinfo_int_o3(NODE_STARTUP, ri, r, startup,
IDBM_SHOW, "manual", "automatic", "onboot", num, 1);
+ __recinfo_int_o2(NODE_LEADING_LOGIN, ri, r, leading_login, IDBM_SHOW,
+ "No", "Yes", num, 1);
/*
* Note: because we do not add the iface.iscsi_ifacename to
* sysfs iscsiadm does some weird matching. We can change the iface
@@ -230,6 +255,32 @@ idbm_recinfo_node(node_rec_t *r, recinfo
__recinfo_str(IFACE_TRANSPORTNAME, ri, r, iface.transport_name,
IDBM_SHOW, num, 1);
__recinfo_str(IFACE_INAME, ri, r, iface.iname, IDBM_SHOW, num, 1);
+ __recinfo_str(IFACE_BOOT_PROTO, ri, r, iface.bootproto, IDBM_SHOW,
+ num, 1);
+ __recinfo_str(IFACE_SUBNET_MASK, ri, r, iface.subnet_mask,
+ IDBM_SHOW, num, 1);
+ __recinfo_str(IFACE_GATEWAY, ri, r, iface.gateway, IDBM_SHOW, num, 1);
+ __recinfo_str(IFACE_IPV6_AUTOCFG, ri, r, iface.ipv6_autocfg,
+ IDBM_SHOW, num, 1);
+ __recinfo_str(IFACE_LINKLOCAL_AUTOCFG, ri, r, iface.linklocal_autocfg,
+ IDBM_SHOW, num, 1);
+ __recinfo_str(IFACE_ROUTER_AUTOCFG, ri, r, iface.router_autocfg,
+ IDBM_SHOW, num, 1);
+ __recinfo_str(IFACE_LINKLOCAL, ri, r, iface.ipv6_linklocal,
+ IDBM_SHOW, num, 1);
+ __recinfo_str(IFACE_ROUTER, ri, r, iface.ipv6_router, IDBM_SHOW, num,
+ 1);
+ __recinfo_str(IFACE_STATE, ri, r, iface.state, IDBM_SHOW, num, 1);
+ __recinfo_uint16(IFACE_VLAN_ID, ri, r, iface.vlan_id, IDBM_SHOW, num,
+ 1);
+ __recinfo_uint8(IFACE_VLAN_PRIORITY, ri, r, iface.vlan_priority,
+ IDBM_SHOW, num, 1);
+ __recinfo_str(IFACE_VLAN_STATE, ri, r, iface.vlan_state, IDBM_SHOW,
+ num, 1);
+ __recinfo_int(IFACE_NUM, ri, r, iface.iface_num, IDBM_SHOW, num, 1);
+ __recinfo_uint16(IFACE_MTU, ri, r, iface.mtu, IDBM_SHOW, num, 1);
+ __recinfo_uint16(IFACE_PORT, ri, r, iface.port, IDBM_SHOW, num, 1);
+
__recinfo_str(NODE_DISC_ADDR, ri, r, disc_address, IDBM_SHOW,
num, 0);
__recinfo_int(NODE_DISC_PORT, ri, r, disc_port, IDBM_SHOW,
@@ -247,6 +298,8 @@ idbm_recinfo_node(node_rec_t *r, recinfo
session.cmds_max, IDBM_SHOW, num, 1);
__recinfo_int(SESSION_QDEPTH, ri, r,
session.queue_depth, IDBM_SHOW, num, 1);
+ __recinfo_int(SESSION_NR_SESSIONS, ri, r,
+ session.nr_sessions, IDBM_SHOW, num, 1);
__recinfo_int_o2(SESSION_AUTH_METHOD, ri, r, session.auth.authmethod,
IDBM_SHOW, "None", "CHAP", num, 1);
__recinfo_str(SESSION_USERNAME, ri, r,
@@ -369,6 +422,27 @@ void idbm_recinfo_iface(iface_rec_t *r,
__recinfo_str(IFACE_TRANSPORTNAME, ri, r, transport_name,
IDBM_SHOW, num, 1);
__recinfo_str(IFACE_INAME, ri, r, iname, IDBM_SHOW, num, 1);
+ __recinfo_str(IFACE_BOOT_PROTO, ri, r, bootproto, IDBM_SHOW, num, 1);
+ __recinfo_str(IFACE_SUBNET_MASK, ri, r, subnet_mask,
+ IDBM_SHOW, num, 1);
+ __recinfo_str(IFACE_GATEWAY, ri, r, gateway, IDBM_SHOW, num, 1);
+ __recinfo_str(IFACE_IPV6_AUTOCFG, ri, r, ipv6_autocfg,
+ IDBM_SHOW, num, 1);
+ __recinfo_str(IFACE_LINKLOCAL_AUTOCFG, ri, r, linklocal_autocfg,
+ IDBM_SHOW, num, 1);
+ __recinfo_str(IFACE_ROUTER_AUTOCFG, ri, r, router_autocfg,
+ IDBM_SHOW, num, 1);
+ __recinfo_str(IFACE_LINKLOCAL, ri, r, ipv6_linklocal,
+ IDBM_SHOW, num, 1);
+ __recinfo_str(IFACE_ROUTER, ri, r, ipv6_router, IDBM_SHOW, num, 1);
+ __recinfo_str(IFACE_STATE, ri, r, state, IDBM_SHOW, num, 1);
+ __recinfo_uint16(IFACE_VLAN_ID, ri, r, vlan_id, IDBM_SHOW, num, 1);
+ __recinfo_uint8(IFACE_VLAN_PRIORITY, ri, r, vlan_priority,
+ IDBM_SHOW, num, 1);
+ __recinfo_str(IFACE_VLAN_STATE, ri, r, vlan_state, IDBM_SHOW, num, 1);
+ __recinfo_int(IFACE_NUM, ri, r, iface_num, IDBM_SHOW, num, 1);
+ __recinfo_uint16(IFACE_MTU, ri, r, mtu, IDBM_SHOW, num, 1);
+ __recinfo_uint16(IFACE_PORT, ri, r, port, IDBM_SHOW, num, 1);
}
recinfo_t *idbm_recinfo_alloc(int max_keys)
@@ -426,6 +500,31 @@ void idbm_print(int type, void *rec, int
}
static void
+idbm_setup_session_defaults(struct iscsi_session_operational_config *conf)
+{
+ conf->InitialR2T = 0;
+ conf->ImmediateData = 1;
+ conf->FirstBurstLength = DEF_INI_FIRST_BURST_LEN;
+ conf->MaxBurstLength = DEF_INI_MAX_BURST_LEN;
+ conf->DefaultTime2Wait = ISCSI_DEF_TIME2WAIT;
+ conf->DefaultTime2Retain = 0;
+ conf->MaxConnections = 1;
+ conf->MaxOutstandingR2T = 1;
+ conf->ERL = 0;
+ conf->FastAbort = 1;
+}
+
+static void idbm_setup_conn_defaults(struct iscsi_conn_operational_config *conf)
+{
+ conf->MaxXmitDataSegmentLength = 0;
+ conf->MaxRecvDataSegmentLength = DEF_INI_MAX_RECV_SEG_LEN;
+ conf->HeaderDigest = CONFIG_DIGEST_NEVER;
+ conf->DataDigest = CONFIG_DIGEST_NEVER;
+ conf->IFMarker = 0;
+ conf->OFMarker = 0;
+}
+
+static void
idbm_discovery_setup_defaults(discovery_rec_t *rec, discovery_type_e type)
{
memset(rec, 0, sizeof(discovery_rec_t));
@@ -443,7 +542,10 @@ idbm_discovery_setup_defaults(discovery_
rec->u.sendtargets.conn_timeo.login_timeout=15;
rec->u.sendtargets.conn_timeo.auth_timeout = 45;
rec->u.sendtargets.conn_timeo.active_timeout=30;
- rec->u.sendtargets.iscsi.MaxRecvDataSegmentLength =
+ idbm_setup_session_defaults(&rec->u.sendtargets.session_conf);
+ idbm_setup_conn_defaults(&rec->u.sendtargets.conn_conf);
+ /* override def setting */
+ rec->u.sendtargets.conn_conf.MaxRecvDataSegmentLength =
DEF_INI_DISC_MAX_RECV_SEG_LEN;
break;
case DISCOVERY_TYPE_SLP:
@@ -485,6 +587,20 @@ setup_passwd_len:
*(int*)info[i].data =
strtoul(value, NULL, 10);
goto updated;
+ } else if (info[i].type == TYPE_UINT8) {
+ if (!info[i].data)
+ continue;
+
+ *(uint8_t *)info[i].data =
+ strtoul(value, NULL, 10);
+ goto updated;
+ } else if (info[i].type == TYPE_UINT16) {
+ if (!info[i].data)
+ continue;
+
+ *(uint16_t *)info[i].data =
+ strtoul(value, NULL, 10);
+ goto updated;
} else if (info[i].type == TYPE_STR) {
if (!info[i].data)
continue;
@@ -515,7 +631,7 @@ setup_passwd_len:
}
}
- return 1;
+ return ISCSI_ERR_INVAL;
updated:
strlcpy((char*)info[i].value, value, VALUE_MAXVAL);
@@ -556,12 +672,12 @@ int idbm_verify_param(recinfo_t *info, c
else {
log_error("Cannot modify %s. It is used to look up "
"the record and cannot be changed.", name);
- return EINVAL;
+ return ISCSI_ERR_INVAL;
}
}
log_error("Cannot modify %s. Invalid param name.", name);
- return EINVAL;
+ return ISCSI_ERR_INVAL;
}
void idbm_recinfo_config(recinfo_t *info, FILE *f)
@@ -627,7 +743,7 @@ void idbm_recinfo_config(recinfo_t *info
}
*(value+i) = 0;
- (void)idbm_rec_update_param(info, name, value, line_number);
+ idbm_rec_update_param(info, name, value, line_number);
} while (line);
}
@@ -781,19 +897,19 @@ get_params_from_disc_link(char *link, ch
(*target) = link;
*address = strchr(*target, ',');
if (!(*address))
- return EINVAL;
+ return ISCSI_ERR_INVAL;
*(*address)++ = '\0';
*port = strchr(*address, ',');
if (!(*port))
- return EINVAL;
+ return ISCSI_ERR_INVAL;
*(*port)++ = '\0';
*tpgt = strchr(*port, ',');
if (!(*tpgt))
- return EINVAL;
+ return ISCSI_ERR_INVAL;
*(*tpgt)++ = '\0';
*ifaceid = strchr(*tpgt, ',');
if (!(*ifaceid))
- return EINVAL;
+ return ISCSI_ERR_INVAL;
*(*ifaceid)++ = '\0';
return 0;
}
@@ -809,8 +925,9 @@ int idbm_lock(void)
if (access(LOCK_DIR, F_OK) != 0) {
if (mkdir(LOCK_DIR, 0660) != 0) {
- log_error("Could not open %s. Exiting\n", LOCK_DIR);
- return errno;
+ log_error("Could not open %s: %s\n", LOCK_DIR,
+ strerror(errno));
+ return ISCSI_ERR_IDBM;
}
}
@@ -827,7 +944,7 @@ int idbm_lock(void)
log_error("Maybe you are not root?");
log_error("Could not lock discovery DB: %s: %s",
LOCK_WRITE_FILE, strerror(errno));
- return errno;
+ return ISCSI_ERR_IDBM;
} else if (i == 0)
log_debug(2, "Waiting for discovery DB lock");
@@ -880,7 +997,7 @@ static int __idbm_rec_read(node_rec_t *o
info = idbm_recinfo_alloc(MAX_KEYS);
if (!info)
- return ENOMEM;
+ return ISCSI_ERR_NOMEM;
rc = idbm_lock();
if (rc)
@@ -888,8 +1005,9 @@ static int __idbm_rec_read(node_rec_t *o
f = fopen(conf, "r");
if (!f) {
- log_debug(5, "Could not open %s err %d\n", conf, errno);
- rc = errno;
+ log_debug(5, "Could not open %s err %s\n", conf,
+ strerror(errno));
+ rc = ISCSI_ERR_IDBM;
goto unlock;
}
@@ -916,7 +1034,7 @@ idbm_rec_read(node_rec_t *out_rec, char
portal = calloc(1, PATH_MAX);
if (!portal)
- return ENOMEM;
+ return ISCSI_ERR_IDBM;
/* try old style portal as config */
snprintf(portal, PATH_MAX, "%s/%s/%s,%d", NODE_CONFIG_DIR,
@@ -929,14 +1047,14 @@ idbm_rec_read(node_rec_t *out_rec, char
targetname, ip, port, tpgt, iface->name);
log_debug(5, "rec read looking for config file %s.", portal);
if (!strlen(iface->name)) {
- rc = EINVAL;
+ rc = ISCSI_ERR_INVAL;
goto free_portal;
}
if (stat(portal, &statb)) {
- log_debug(5, "Could not stat %s err %d.", portal, errno);
+ log_debug(5, "Could not stat %s: %s.", portal, strerror(errno));
free(portal);
- return errno;
+ return ISCSI_ERR_IDBM;
}
read:
@@ -1073,22 +1191,16 @@ int idbm_for_each_isns_drec(void *data,
static int __idbm_print_all_by_drec(void *data, struct discovery_rec *drec)
{
int info_level = *(int *)data;
- int rc;
if (info_level >= 1) {
printf("DiscoveryAddress: %s,%d\n",
drec->address, drec->port);
- rc = idbm_print_discovered(drec, info_level);
- if (rc)
- return 0;
- else
- return ENODEV;
- } else {
+ idbm_print_discovered(drec, info_level);
+ } else
printf("%s:%d via %s\n", drec->address, drec->port,
drec->type == DISCOVERY_TYPE_ISNS ?
"isns" : "sendtargets");
- return 0;
- }
+ return 0;
}
static int idbm_print_all_st(int info_level)
@@ -1168,11 +1280,23 @@ int idbm_print_all_discovery(int info_le
return found;
}
-/*
- * This iterates over the ifaces in use in the nodes dir.
- * It does not iterate over the ifaces setup in /etc/iscsi/ifaces.
+/**
+ * idbm_for_each_iface - iterate over bound iface recs
+ * @found: nr of recs found so far
+ * @data: data pointer passed to fn
+ * @fn: iterator function ran over each bound iface rec
+ * @targetname: rec's target name
+ * @tpgt: rec's portal group tag
+ * @ip: rec's ip address
+ * @port: rec's port
+ *
+ * This will run fn over all recs with the {targetname,tpgt,ip,port}
+ * id. It does not iterate over the ifaces setup in /etc/iscsi/ifaces.
+ *
+ * fn should return -1 if it skipped the rec, a ISCSI_ERR error code if
+ * the operation failed or 0 if fn was run successfully.
*/
-int idbm_for_each_iface(int *found, void *data,
+static int idbm_for_each_iface(int *found, void *data,
idbm_iface_op_fn *fn,
char *targetname, int tpgt, char *ip, int port)
{
@@ -1185,7 +1309,7 @@ int idbm_for_each_iface(int *found, void
portal = calloc(1, PATH_MAX);
if (!portal)
- return ENOMEM;
+ return ISCSI_ERR_NOMEM;
if (tpgt >= 0)
goto read_iface;
@@ -1195,7 +1319,7 @@ int idbm_for_each_iface(int *found, void
ip, port);
if (stat(portal, &statb)) {
log_error("iface iter could not stat %s.", portal);
- rc = ENODEV;
+ rc = ISCSI_ERR_IDBM;
goto free_portal;
}
@@ -1217,11 +1341,13 @@ read_iface:
iface_dirfd = opendir(portal);
if (!iface_dirfd) {
log_error("iface iter could not read dir %s.", portal);
- rc = errno;
+ rc = ISCSI_ERR_IDBM;
goto free_portal;
}
while ((iface_dent = readdir(iface_dirfd))) {
+ int curr_rc;
+
if (!strcmp(iface_dent->d_name, ".") ||
!strcmp(iface_dent->d_name, ".."))
continue;
@@ -1233,14 +1359,12 @@ read_iface:
if (__idbm_rec_read(&rec, portal))
continue;
+ curr_rc = fn(data, &rec);
/* less than zero means it was not a match */
- rc = fn(data, &rec);
- if (rc > 0)
- break;
- else if (rc == 0)
+ if (curr_rc > 0 && !rc)
+ rc = curr_rc;
+ else if (curr_rc == 0)
(*found)++;
- else
- rc = 0;
}
closedir(iface_dirfd);
@@ -1263,17 +1387,18 @@ int idbm_for_each_portal(int *found, voi
portal = calloc(1, PATH_MAX);
if (!portal)
- return ENOMEM;
+ return ISCSI_ERR_NOMEM;
snprintf(portal, PATH_MAX, "%s/%s", NODE_CONFIG_DIR, targetname);
portal_dirfd = opendir(portal);
if (!portal_dirfd) {
- rc = errno;
+ rc = ISCSI_ERR_IDBM;
goto done;
}
while ((portal_dent = readdir(portal_dirfd))) {
char *tmp_port, *tmp_tpgt;
+ int curr_rc;
if (!strcmp(portal_dent->d_name, ".") ||
!strcmp(portal_dent->d_name, ".."))
@@ -1288,11 +1413,12 @@ int idbm_for_each_portal(int *found, voi
if (tmp_tpgt)
*tmp_tpgt++ = '\0';
- rc = fn(found, data, targetname,
+ curr_rc = fn(found, data, targetname,
tmp_tpgt ? atoi(tmp_tpgt) : -1,
portal_dent->d_name, atoi(tmp_port));
- if (rc)
- break;
+ /* less than zero means it was not a match */
+ if (curr_rc > 0 && !rc)
+ rc = curr_rc;
}
closedir(portal_dirfd);
done:
@@ -1314,14 +1440,17 @@ int idbm_for_each_node(int *found, void
return 0;
while ((node_dent = readdir(node_dirfd))) {
+ int curr_rc;
+
if (!strcmp(node_dent->d_name, ".") ||
!strcmp(node_dent->d_name, ".."))
continue;
log_debug(5, "searching %s\n", node_dent->d_name);
- rc = fn(found, data, node_dent->d_name);
- if (rc)
- break;
+ curr_rc = fn(found, data, node_dent->d_name);
+ /* less than zero means it was not a match */
+ if (curr_rc > 0 && !rc)
+ rc = curr_rc;
}
closedir(node_dirfd);
@@ -1376,17 +1505,17 @@ idbm_discovery_read(discovery_rec_t *out
FILE *f;
if (drec_type > 1)
- return EINVAL;
+ return ISCSI_ERR_INVAL;
memset(out_rec, 0, sizeof(discovery_rec_t));
info = idbm_recinfo_alloc(MAX_KEYS);
if (!info)
- return ENOMEM;
+ return ISCSI_ERR_NOMEM;
portal = malloc(PATH_MAX);
if (!portal) {
- rc = ENOMEM;
+ rc = ISCSI_ERR_NOMEM;
goto free_info;
}
@@ -1402,8 +1531,9 @@ idbm_discovery_read(discovery_rec_t *out
f = idbm_open_rec_r(portal,
disc_type_to_config_vals[drec_type].config_name);
if (!f) {
- log_debug(1, "Could not open %s err %d\n", portal, errno);
- rc = errno;
+ log_debug(1, "Could not open %s: %s\n", portal,
+ strerror(errno));
+ rc = ISCSI_ERR_IDBM;
goto unlock;
}
@@ -1474,14 +1604,15 @@ static int idbm_rec_write(node_rec_t *re
portal = malloc(PATH_MAX);
if (!portal) {
log_error("Could not alloc portal\n");
- return ENOMEM;
+ return ISCSI_ERR_NOMEM;
}
snprintf(portal, PATH_MAX, "%s", NODE_CONFIG_DIR);
if (access(portal, F_OK) != 0) {
if (mkdir(portal, 0660) != 0) {
- log_error("Could not make %s\n", portal);
- rc = errno;
+ log_error("Could not make %s: %s\n", portal,
+ strerror(errno));
+ rc = ISCSI_ERR_IDBM;
goto free_portal;
}
}
@@ -1489,8 +1620,9 @@ static int idbm_rec_write(node_rec_t *re
snprintf(portal, PATH_MAX, "%s/%s", NODE_CONFIG_DIR, rec->name);
if (access(portal, F_OK) != 0) {
if (mkdir(portal, 0660) != 0) {
- log_error("Could not make %s\n", portal);
- rc = errno;
+ log_error("Could not make %s: %s\n", portal,
+ strerror(errno));
+ rc = ISCSI_ERR_IDBM;
goto free_portal;
}
}
@@ -1531,13 +1663,13 @@ static int idbm_rec_write(node_rec_t *re
* Old style portal as a file, but with tpgt. Let's update it.
*/
if (unlink(portal)) {
- log_error("Could not convert %s. err %d\n", portal,
- errno);
- rc = errno;
+ log_error("Could not convert %s: %s\n", portal,
+ strerror(errno));
+ rc = ISCSI_ERR_IDBM;
goto unlock;
}
} else {
- rc = EINVAL;
+ rc = ISCSI_ERR_INVAL;
goto unlock;
}
@@ -1546,9 +1678,9 @@ mkdir_portal:
rec->name, rec->conn[0].address, rec->conn[0].port, rec->tpgt);
if (stat(portal, &statb)) {
if (mkdir(portal, 0660) != 0) {
- log_error("Could not make dir %s err %d\n",
- portal, errno);
- rc = errno;
+ log_error("Could not make dir %s: %s\n",
+ portal, strerror(errno));
+ rc = ISCSI_ERR_IDBM;
goto unlock;
}
}
@@ -1559,8 +1691,8 @@ mkdir_portal:
open_conf:
f = fopen(portal, "w");
if (!f) {
- log_error("Could not open %s err %d\n", portal, errno);
- rc = errno;
+ log_error("Could not open %s: %sd\n", portal, strerror(errno));
+ rc = ISCSI_ERR_IDBM;
goto unlock;
}
@@ -1581,12 +1713,12 @@ idbm_discovery_write(discovery_rec_t *re
int rc = 0;
if (rec->type > 1)
- return EINVAL;
+ return ISCSI_ERR_INVAL;
portal = malloc(PATH_MAX);
if (!portal) {
log_error("Could not alloc portal\n");
- return ENOMEM;
+ return ISCSI_ERR_NOMEM;
}
rc = idbm_lock();
@@ -1597,8 +1729,9 @@ idbm_discovery_write(discovery_rec_t *re
disc_type_to_config_vals[rec->type].config_root);
if (access(portal, F_OK) != 0) {
if (mkdir(portal, 0660) != 0) {
- log_error("Could not make %s\n", portal);
- rc = errno;
+ log_error("Could not make %s: %s\n", portal,
+ strerror(errno));
+ rc = ISCSI_ERR_IDBM;
goto unlock;
}
}
@@ -1610,8 +1743,8 @@ idbm_discovery_write(discovery_rec_t *re
f = idbm_open_rec_w(portal,
disc_type_to_config_vals[rec->type].config_name);
if (!f) {
- log_error("Could not open %s err %d\n", portal, errno);
- rc = errno;
+ log_error("Could not open %s: %s\n", portal, strerror(errno));
+ rc = ISCSI_ERR_IDBM;
goto unlock;
}
@@ -1655,9 +1788,9 @@ static int setup_disc_to_node_link(char
case DISCOVERY_TYPE_FW:
if (access(FW_CONFIG_DIR, F_OK) != 0) {
if (mkdir(FW_CONFIG_DIR, 0660) != 0) {
- log_error("Could not make %s\n",
- FW_CONFIG_DIR);
- rc = errno;
+ log_error("Could not make %s: %s",
+ FW_CONFIG_DIR, strerror(errno));
+ rc = ISCSI_ERR_IDBM;
}
}
@@ -1669,9 +1802,9 @@ static int setup_disc_to_node_link(char
case DISCOVERY_TYPE_STATIC:
if (access(STATIC_CONFIG_DIR, F_OK) != 0) {
if (mkdir(STATIC_CONFIG_DIR, 0660) != 0) {
- log_error("Could not make %s\n",
- STATIC_CONFIG_DIR);
- rc = errno;
+ log_error("Could not make %s; %s",
+ STATIC_CONFIG_DIR, strerror(errno));
+ rc = ISCSI_ERR_IDBM;
}
}
@@ -1683,9 +1816,9 @@ static int setup_disc_to_node_link(char
case DISCOVERY_TYPE_ISNS:
if (access(ISNS_CONFIG_DIR, F_OK) != 0) {
if (mkdir(ISNS_CONFIG_DIR, 0660) != 0) {
- log_error("Could not make %s\n",
- ISNS_CONFIG_DIR);
- rc = errno;
+ log_error("Could not make %s: %s",
+ ISNS_CONFIG_DIR, strerror(errno));
+ rc = ISCSI_ERR_IDBM;
}
}
@@ -1732,7 +1865,7 @@ static int setup_disc_to_node_link(char
break;
case DISCOVERY_TYPE_SLP:
default:
- rc = EINVAL;
+ rc = ISCSI_ERR_INVAL;
}
return rc;
@@ -1773,7 +1906,7 @@ int idbm_add_node(node_rec_t *newrec, di
node_portal = calloc(2, PATH_MAX);
if (!node_portal)
- return ENOMEM;
+ return ISCSI_ERR_NOMEM;
disc_portal = node_portal + PATH_MAX;
snprintf(node_portal, PATH_MAX, "%s/%s/%s,%d,%d", NODE_CONFIG_DIR,
@@ -1795,9 +1928,10 @@ int idbm_add_node(node_rec_t *newrec, di
log_debug(7, "link from %s to %s exists", node_portal,
disc_portal);
else {
- rc = errno;
+ rc = ISCSI_ERR_IDBM;
log_error("Could not make link from disc source %s to "
- "node %s", disc_portal, node_portal);
+ "node %s: %s", disc_portal, node_portal,
+ strerror(errno));
}
}
idbm_unlock();
@@ -1812,10 +1946,12 @@ static int idbm_bind_iface_to_nodes(idbm
{
struct node_rec *rec, *tmp;
struct list_head new_recs;
+ int rc;
INIT_LIST_HEAD(&new_recs);
- if (disc_node_fn(data, iface, &new_recs))
- return ENODEV;
+ rc = disc_node_fn(data, iface, &new_recs);
+ if (rc)
+ return rc;
list_for_each_entry_safe(rec, tmp, &new_recs, list) {
list_del_init(&rec->list);
@@ -1825,6 +1961,20 @@ static int idbm_bind_iface_to_nodes(idbm
return 0;
}
+static int
+discovery_error_fatal(int err)
+{
+ switch (err) {
+ /* No error */
+ case ISCSI_SUCCESS:
+ /* Transport errors or timeouts are not fatal */
+ case ISCSI_ERR_TRANS:
+ case ISCSI_ERR_TRANS_TIMEOUT:
+ return 0;
+ }
+ return 1;
+}
+
int idbm_bind_ifaces_to_nodes(idbm_disc_nodes_fn *disc_node_fn,
void *data, struct list_head *ifaces,
struct list_head *bound_recs)
@@ -1856,7 +2006,7 @@ int idbm_bind_ifaces_to_nodes(idbm_disc_
rc = idbm_bind_iface_to_nodes(disc_node_fn, data, iface,
bound_recs);
free(iface);
- if (rc)
+ if (discovery_error_fatal(rc))
goto fail;
found = 1;
}
@@ -1883,7 +2033,7 @@ int idbm_bind_ifaces_to_nodes(idbm_disc_
rc = idbm_bind_iface_to_nodes(disc_node_fn, data, iface,
bound_recs);
- if (rc)
+ if (discovery_error_fatal(rc))
goto fail;
}
}
@@ -1960,7 +2110,7 @@ int idbm_delete_discovery(discovery_rec_
portal = calloc(1, PATH_MAX);
if (!portal)
- return ENOMEM;
+ return ISCSI_ERR_NOMEM;
snprintf(portal, PATH_MAX, "%s/%s,%d",
disc_type_to_config_vals[drec->type].config_root,
@@ -2017,7 +2167,7 @@ static int idbm_remove_disc_to_node_link
tmprec = malloc(sizeof(*tmprec));
if (!tmprec)
- return ENOMEM;
+ return ISCSI_ERR_NOMEM;
memset(portal, 0, PATH_MAX);
snprintf(portal, PATH_MAX, "%s/%s/%s,%d,%d/%s", NODE_CONFIG_DIR,
@@ -2045,9 +2195,9 @@ static int idbm_remove_disc_to_node_link
if (!stat(portal, &statb)) {
if (unlink(portal)) {
- log_error("Could not remove link %s err %d\n",
- portal, errno);
- rc = errno;
+ log_error("Could not remove link %s: %s\n",
+ portal, strerror(errno));
+ rc = ISCSI_ERR_IDBM;
} else
log_debug(7, "rmd %s", portal);
} else
@@ -2073,7 +2223,7 @@ int idbm_delete_node(node_rec_t *rec)
portal = calloc(1, PATH_MAX);
if (!portal)
- return ENOMEM;
+ return ISCSI_ERR_NOMEM;
rc = idbm_remove_disc_to_node_link(rec, portal);
if (rc)
@@ -2100,15 +2250,15 @@ int idbm_delete_node(node_rec_t *rec)
if (!stat(portal, &statb))
goto rm_conf;
- log_error("Could not stat %s to delete node err %d\n",
- portal, errno);
- rc = errno;
+ log_error("Could not stat %s to delete node: %s\n",
+ portal, strerror(errno));
+ rc = ISCSI_ERR_IDBM;
goto unlock;
rm_conf:
if (unlink(portal)) {
- log_error("Could not remove %s err %d\n", portal, errno);
- rc = errno;
+ log_error("Could not remove %s: %s\n", portal, strerror(errno));
+ rc = ISCSI_ERR_IDBM;
goto unlock;
}
@@ -2170,6 +2320,38 @@ idbm_slp_defaults(struct iscsi_slp_confi
sizeof(struct iscsi_slp_config));
}
+int idbm_parse_param(char *param, struct node_rec *rec)
+{
+ char *name, *value;
+ recinfo_t *info;
+ int rc;
+
+ name = param;
+
+ value = strchr(param, '=');
+ if (!value) {
+ log_error("Invalid --param %s. Missing setting.\n", param);
+ return ISCSI_ERR_INVAL;
+ }
+ *value = '\0';
+ value++;
+
+ info = idbm_recinfo_alloc(MAX_KEYS);
+ if (!info) {
+ log_error("Could not allocate memory to setup params.\n");
+ return ISCSI_ERR_NOMEM;
+ }
+
+ idbm_recinfo_node(rec, info);
+
+ rc = idbm_rec_update_param(info, name, value, 0);
+ if (rc)
+ log_error("Could not set %s to %s. Check that %s is a "
+ "valid parameter.\n", name, value, name);
+ free(info);
+ return rc;
+}
+
int idbm_node_set_param(void *data, node_rec_t *rec)
{
struct db_set_param *param = data;
@@ -2178,7 +2360,7 @@ int idbm_node_set_param(void *data, node
info = idbm_recinfo_alloc(MAX_KEYS);
if (!info)
- return ENOMEM;
+ return ISCSI_ERR_NOMEM;
idbm_recinfo_node(rec, info);
@@ -2207,7 +2389,7 @@ int idbm_discovery_set_param(void *data,
info = idbm_recinfo_alloc(MAX_KEYS);
if (!info)
- return ENOMEM;
+ return ISCSI_ERR_NOMEM;
idbm_recinfo_discovery((discovery_rec_t *)rec, info);
@@ -2242,7 +2424,7 @@ int idbm_init(idbm_get_config_file_fn *f
db = malloc(sizeof(idbm_t));
if (!db) {
log_error("out of memory on idbm allocation");
- return ENOMEM;
+ return ISCSI_ERR_NOMEM;
}
memset(db, 0, sizeof(idbm_t));
db->get_config_file = fn;
@@ -2348,10 +2530,12 @@ void idbm_node_setup_defaults(node_rec_t
rec->tpgt = PORTAL_GROUP_TAG_UNKNOWN;
rec->disc_type = DISCOVERY_TYPE_STATIC;
+ rec->leading_login = 0;
rec->session.cmds_max = CMDS_MAX;
rec->session.xmit_thread_priority = XMIT_THREAD_PRIORITY;
rec->session.initial_cmdsn = 0;
rec->session.queue_depth = QUEUE_DEPTH;
+ rec->session.nr_sessions = 1;
rec->session.initial_login_retry_max = DEF_INITIAL_LOGIN_RETRIES_MAX;
rec->session.reopen_max = 32;
rec->session.auth.authmethod = 0;
@@ -2362,16 +2546,10 @@ void idbm_node_setup_defaults(node_rec_t
rec->session.err_timeo.tgt_reset_timeout = DEF_TGT_RESET_TIMEO;
rec->session.err_timeo.host_reset_timeout = DEF_HOST_RESET_TIMEO;
rec->session.timeo.replacement_timeout = DEF_REPLACEMENT_TIMEO;
- rec->session.iscsi.InitialR2T = 0;
- rec->session.iscsi.ImmediateData = 1;
- rec->session.iscsi.FirstBurstLength = DEF_INI_FIRST_BURST_LEN;
- rec->session.iscsi.MaxBurstLength = DEF_INI_MAX_BURST_LEN;
- rec->session.iscsi.DefaultTime2Wait = ISCSI_DEF_TIME2WAIT;
- rec->session.iscsi.DefaultTime2Retain = 0;
- rec->session.iscsi.MaxConnections = 1;
- rec->session.iscsi.MaxOutstandingR2T = 1;
- rec->session.iscsi.ERL = 0;
- rec->session.iscsi.FastAbort = 1;
+ rec->session.info = NULL;
+ rec->session.sid = 0;
+ rec->session.multiple = 0;
+ idbm_setup_session_defaults(&rec->session.iscsi);
for (i=0; i<ISCSI_CONN_MAX; i++) {
rec->conn[i].startup = ISCSI_STARTUP_MANUAL;
@@ -2385,13 +2563,7 @@ void idbm_node_setup_defaults(node_rec_t
rec->conn[i].timeo.noop_out_interval = DEF_NOOP_OUT_INTERVAL;
rec->conn[i].timeo.noop_out_timeout = DEF_NOOP_OUT_TIMEO;
- rec->conn[i].iscsi.MaxXmitDataSegmentLength = 0;
- rec->conn[i].iscsi.MaxRecvDataSegmentLength =
- DEF_INI_MAX_RECV_SEG_LEN;
- rec->conn[i].iscsi.HeaderDigest = CONFIG_DIGEST_NEVER;
- rec->conn[i].iscsi.DataDigest = CONFIG_DIGEST_NEVER;
- rec->conn[i].iscsi.IFMarker = 0;
- rec->conn[i].iscsi.OFMarker = 0;
+ idbm_setup_conn_defaults(&rec->conn[i].iscsi);
}
iface_setup_defaults(&rec->iface);
@@ -2404,7 +2576,8 @@ idbm_find_rec_in_list(struct list_head *
struct node_rec *rec;
list_for_each_entry(rec, rec_list, list) {
- if (__iscsi_match_session(rec, targetname, addr, port, iface))
+ if (__iscsi_match_session(rec, targetname, addr, port, iface,
+ MATCH_ANY_SID))
return rec;
}
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/idbm_fields.h open-iscsi-2.0-872-rc4-bnx2i.work/usr/idbm_fields.h
--- open-iscsi-2.0-872-rc4-bnx2i/usr/idbm_fields.h 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/idbm_fields.h 2012-03-05 23:02:46.000000000 -0600
@@ -10,6 +10,7 @@
#define NODE_NAME "node.name"
#define NODE_TPGT "node.tpgt"
#define NODE_STARTUP "node.startup"
+#define NODE_LEADING_LOGIN "node.leading_login"
#define NODE_DISC_ADDR "node.discovery_address"
#define NODE_DISC_PORT "node.discovery_port"
#define NODE_DISC_TYPE "node.discovery_type"
@@ -21,6 +22,7 @@
#define SESSION_CMDS_MAX "node.session.cmds_max"
#define SESSION_XMIT_THREAD_PRIORITY "node.session.xmit_thread_priority"
#define SESSION_QDEPTH "node.session.queue_depth"
+#define SESSION_NR_SESSIONS "node.session.nr_sessions"
#define SESSION_AUTH_METHOD "node.session.auth.authmethod"
#define SESSION_USERNAME "node.session.auth.username"
#define SESSION_PASSWORD "node.session.auth.password"
@@ -75,7 +77,18 @@
#define IFACE_GATEWAY "iface.gateway"
#define IFACE_PRIMARY_DNS "iface.primary_dns"
#define IFACE_SEC_DNS "iface.secondary_dns"
-#define IFACE_VLAN "iface.vlan"
+#define IFACE_VLAN_ID "iface.vlan_id"
+#define IFACE_VLAN_PRIORITY "iface.vlan_priority"
+#define IFACE_VLAN_STATE "iface.vlan_state"
+#define IFACE_LINKLOCAL "iface.ipv6_linklocal"
+#define IFACE_ROUTER "iface.ipv6_router"
+#define IFACE_IPV6_AUTOCFG "iface.ipv6_autocfg"
+#define IFACE_LINKLOCAL_AUTOCFG "iface.linklocal_autocfg"
+#define IFACE_ROUTER_AUTOCFG "iface.router_autocfg"
+#define IFACE_STATE "iface.state"
+#define IFACE_NUM "iface.iface_num"
+#define IFACE_MTU "iface.mtu"
+#define IFACE_PORT "iface.port"
/* discovery fields */
#define DISC_STARTUP "discovery.startup"
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/idbm.h open-iscsi-2.0-872-rc4-bnx2i.work/usr/idbm.h
--- open-iscsi-2.0-872-rc4-bnx2i/usr/idbm.h 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/idbm.h 2012-03-05 23:06:00.000000000 -0600
@@ -39,6 +39,8 @@
#define TYPE_INT 0
#define TYPE_INT_O 1
#define TYPE_STR 2
+#define TYPE_UINT8 3
+#define TYPE_UINT16 4
#define MAX_KEYS 256 /* number of keys total(including CNX_MAX) */
#define NAME_MAXVAL 128 /* the maximum length of key name */
#define VALUE_MAXVAL 256 /* the maximum length of 223 bytes in the RFC. */
@@ -93,9 +95,6 @@ struct rec_op_data {
node_rec_t *match_rec;
idbm_iface_op_fn *fn;
};
-extern int idbm_for_each_iface(int *found, void *data,
- idbm_iface_op_fn *fn,
- char *targetname, int tpgt, char *ip, int port);
extern int idbm_for_each_portal(int *found, void *data,
idbm_portal_op_fn *fn, char *targetname);
extern int idbm_for_each_node(int *found, void *data,
@@ -140,6 +139,7 @@ extern int idbm_discovery_read(discovery
extern int idbm_rec_read(node_rec_t *out_rec, char *target_name,
int tpgt, char *addr, int port,
struct iface_rec *iface);
+extern int idbm_parse_param(char *param, struct node_rec *rec);
extern int idbm_node_set_param(void *data, node_rec_t *rec);
extern int idbm_discovery_set_param(void *data, discovery_rec_t *rec);
extern void idbm_node_setup_defaults(node_rec_t *rec);
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/iface.c open-iscsi-2.0-872-rc4-bnx2i.work/usr/iface.c
--- open-iscsi-2.0-872-rc4-bnx2i/usr/iface.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/iface.c 2012-03-05 23:05:52.000000000 -0600
@@ -26,6 +26,7 @@
#include <unistd.h>
#include <sys/types.h>
#include <sys/stat.h>
+#include <arpa/inet.h>
#include "log.h"
#include "list.h"
@@ -39,6 +40,8 @@
#include "host.h"
#include "fw_context.h"
#include "sysdeps.h"
+#include "iscsi_err.h"
+#include "iscsi_netlink.h"
/*
* Default ifaces for use with transports that do not bind to hardware
@@ -101,13 +104,13 @@ struct iface_rec *iface_alloc(char *ifna
struct iface_rec *iface;
if (!strlen(ifname) || strlen(ifname) + 1 > ISCSI_MAX_IFACE_LEN) {
- *err = EINVAL;
+ *err = ISCSI_ERR_INVAL;
return NULL;
}
iface = calloc(1, sizeof(*iface));
if (!iface) {
- *err = ENOMEM;
+ *err = ISCSI_ERR_NOMEM;
return NULL;
}
@@ -125,11 +128,11 @@ static int __iface_conf_read(struct ifac
iface_conf = calloc(1, PATH_MAX);
if (!iface_conf)
- return ENOMEM;
+ return ISCSI_ERR_NOMEM;
info = idbm_recinfo_alloc(MAX_KEYS);
if (!info) {
- rc = ENOMEM;
+ rc = ISCSI_ERR_NOMEM;
goto free_conf;
}
@@ -147,7 +150,7 @@ static int __iface_conf_read(struct ifac
iface_setup_defaults(iface);
rc = 0;
} else
- rc = errno;
+ rc = ISCSI_ERR_IDBM;
goto free_info;
}
@@ -213,12 +216,12 @@ int iface_conf_delete(struct iface_rec *
if (def_iface) {
log_error("iface %s is a special interface and "
"cannot be deleted.\n", iface->name);
- return EINVAL;
+ return ISCSI_ERR_INVAL;
}
iface_conf = calloc(1, PATH_MAX);
if (!iface_conf)
- return ENOMEM;
+ return ISCSI_ERR_NOMEM;
sprintf(iface_conf, "%s/%s", IFACE_CONFIG_DIR, iface->name);
rc = idbm_lock();
@@ -226,7 +229,7 @@ int iface_conf_delete(struct iface_rec *
goto free_conf;
if (unlink(iface_conf))
- rc = errno;
+ rc = ISCSI_ERR_IDBM;
idbm_unlock();
free_conf:
@@ -246,17 +249,17 @@ int iface_conf_write(struct iface_rec *i
log_error("iface %s is a special interface and "
"is not stored in %s.\n", iface->name,
IFACE_CONFIG_DIR);
- return EINVAL;
+ return ISCSI_ERR_INVAL;
}
iface_conf = calloc(1, PATH_MAX);
if (!iface_conf)
- return ENOMEM;
+ return ISCSI_ERR_NOMEM;
sprintf(iface_conf, "%s/%s", IFACE_CONFIG_DIR, iface->name);
f = fopen(iface_conf, "w");
if (!f) {
- rc = errno;
+ rc = ISCSI_ERR_IDBM;
goto free_conf;
}
@@ -285,12 +288,12 @@ int iface_conf_update(struct db_set_para
if (def_iface) {
log_error("iface %s is a special interface and "
"cannot be modified.\n", iface->name);
- return EINVAL;
+ return ISCSI_ERR_INVAL;
}
info = idbm_recinfo_alloc(MAX_KEYS);
if (!info)
- return ENOMEM;
+ return ISCSI_ERR_NOMEM;
idbm_recinfo_iface(iface, info);
rc = idbm_verify_param(info, param->name);
@@ -298,10 +301,8 @@ int iface_conf_update(struct db_set_para
goto free_info;
rc = idbm_rec_update_param(info, param->name, param->value, 0);
- if (rc) {
- rc = EIO;
+ if (rc)
goto free_info;
- }
rc = iface_conf_write(iface);
free_info:
@@ -309,6 +310,7 @@ free_info:
return rc;
}
+#if 0 /* Unused */
static int iface_get_next_id(void)
{
struct stat statb;
@@ -346,6 +348,7 @@ static int iface_get_next_id(void)
free(iface_conf);
return rc;
}
+#endif /* Unused */
struct iface_search {
struct iface_rec *pattern;
@@ -362,7 +365,8 @@ static int __iface_get_by_net_binding(vo
}
if (iface_is_bound_by_hwaddr(search->pattern)) {
- if (!strcmp(iface->hwaddress, search->pattern->hwaddress)) {
+ if (!strcasecmp(iface->hwaddress,
+ search->pattern->hwaddress)) {
iface_copy(search->found, iface);
return 1;
} else
@@ -418,15 +422,64 @@ int iface_get_by_net_binding(struct ifac
__iface_get_by_net_binding);
if (rc == 1)
return 0;
- return ENODEV;
+ return ISCSI_ERR_NO_OBJS_FOUND;
+}
+
+static int iface_get_iptype(struct iface_rec *iface)
+{
+ if (strcmp(iface->bootproto, "dhcp") && !strstr(iface->ipaddress, "."))
+ return ISCSI_IFACE_TYPE_IPV6;
+ else
+ return ISCSI_IFACE_TYPE_IPV4;
+}
+
+static int iface_setup_binding_from_kern_iface(void *data,
+ struct iface_rec *kern_iface)
+{
+ struct host_info *hinfo = data;
+ struct iface_rec iface;
+
+ if (!strlen(hinfo->iface.hwaddress)) {
+ log_error("Invalid offload iSCSI host %u. Missing "
+ "hwaddress. Try upgrading %s driver.\n",
+ hinfo->host_no, hinfo->iface.transport_name);
+ return 0;
+ }
+
+ memset(&iface, 0, sizeof(struct iface_rec));
+ strcpy(iface.hwaddress, hinfo->iface.hwaddress);
+ strcpy(iface.transport_name, hinfo->iface.transport_name);
+
+ if (kern_iface) {
+ iface.iface_num = kern_iface->iface_num;
+
+ snprintf(iface.name, sizeof(iface.name), "%s.%s.%s.%u",
+ kern_iface->transport_name,
+ kern_iface->hwaddress,
+ iface_get_iptype(kern_iface) == ISCSI_IFACE_TYPE_IPV4 ?
+ "ipv4" : "ipv6", kern_iface->iface_num);
+ } else {
+ snprintf(iface.name, sizeof(iface.name), "%s.%s",
+ hinfo->iface.transport_name, hinfo->iface.hwaddress);
+ }
+
+ if (iface_conf_read(&iface)) {
+ /* not found so create it */
+ if (iface_conf_write(&iface)) {
+ log_error("Could not create default iface conf %s.",
+ iface.name);
+ /* fall through - will not be persistent */
+ }
+ }
+
+ return 0;
}
static int __iface_setup_host_bindings(void *data, struct host_info *hinfo)
{
struct iface_rec *def_iface;
- struct iface_rec iface;
struct iscsi_transport *t;
- int i = 0;
+ int i = 0, nr_found;
t = iscsi_sysfs_get_transport_by_hba(hinfo->host_no);
if (!t)
@@ -438,25 +491,12 @@ static int __iface_setup_host_bindings(v
return 0;
}
- if (iface_get_by_net_binding(&hinfo->iface, &iface) == ENODEV) {
- /* Must be a new port */
- if (!strlen(hinfo->iface.hwaddress)) {
- log_error("Invalid offload iSCSI host %u. Missing "
- "hwaddress. Try upgrading %s driver.\n",
- hinfo->host_no, t->name);
- return 0;
- }
-
- memset(&iface, 0, sizeof(struct iface_rec));
- strcpy(iface.hwaddress, hinfo->iface.hwaddress);
- strcpy(iface.transport_name, hinfo->iface.transport_name);
- snprintf(iface.name, sizeof(iface.name), "%s.%s",
- t->name, hinfo->iface.hwaddress);
- if (iface_conf_write(&iface))
- log_error("Could not create default iface conf %s.",
- iface.name);
- /* fall through - will not be persistent */
- }
+ nr_found = 0;
+ iscsi_sysfs_for_each_iface_on_host(hinfo, hinfo->host_no,
+ &nr_found,
+ iface_setup_binding_from_kern_iface);
+ if (!nr_found)
+ iface_setup_binding_from_kern_iface(hinfo, NULL);
return 0;
}
@@ -492,10 +532,40 @@ void iface_copy(struct iface_rec *dst, s
{
if (strlen(src->name))
strcpy(dst->name, src->name);
+ if (src->iface_num)
+ dst->iface_num = src->iface_num;
if (strlen(src->netdev))
strcpy(dst->netdev, src->netdev);
if (strlen(src->ipaddress))
strcpy(dst->ipaddress, src->ipaddress);
+ if (strlen(src->subnet_mask))
+ strcpy(dst->subnet_mask, src->subnet_mask);
+ if (strlen(src->gateway))
+ strcpy(dst->gateway, src->gateway);
+ if (strlen(src->bootproto))
+ strcpy(dst->bootproto, src->bootproto);
+ if (strlen(src->ipv6_linklocal))
+ strcpy(dst->ipv6_linklocal, src->ipv6_linklocal);
+ if (strlen(src->ipv6_router))
+ strcpy(dst->ipv6_router, src->ipv6_router);
+ if (strlen(src->ipv6_autocfg))
+ strcpy(dst->ipv6_autocfg, src->ipv6_autocfg);
+ if (strlen(src->linklocal_autocfg))
+ strcpy(dst->linklocal_autocfg, src->linklocal_autocfg);
+ if (strlen(src->router_autocfg))
+ strcpy(dst->router_autocfg, src->router_autocfg);
+ if (src->vlan_id)
+ dst->vlan_id = src->vlan_id;
+ if (src->vlan_priority)
+ dst->vlan_priority = src->vlan_priority;
+ if (strlen(src->vlan_state))
+ strcpy(dst->vlan_state, src->vlan_state);
+ if (strlen(src->state))
+ strcpy(dst->state, src->state);
+ if (src->mtu)
+ dst->mtu = src->mtu;
+ if (src->port)
+ dst->port = src->port;
if (strlen(src->hwaddress))
strcpy(dst->hwaddress, src->hwaddress);
if (strlen(src->transport_name))
@@ -704,7 +774,7 @@ int iface_for_each_iface(void *data, int
iface_dent->d_name);
iface = iface_alloc(iface_dent->d_name, &err);
if (!iface || err) {
- if (err == EINVAL)
+ if (err == ISCSI_ERR_INVAL)
log_error("Invalid iface name %s. Must be "
"from 1 to %d characters.",
iface_dent->d_name,
@@ -756,7 +826,7 @@ static int iface_link(void *data, struct
iface_copy = calloc(1, sizeof(*iface_copy));
if (!iface_copy)
- return ENOMEM;
+ return ISCSI_ERR_NOMEM;
memcpy(iface_copy, iface, sizeof(*iface_copy));
INIT_LIST_HEAD(&iface_copy->list);
@@ -788,46 +858,57 @@ void iface_link_ifaces(struct list_head
int iface_setup_from_boot_context(struct iface_rec *iface,
struct boot_context *context)
{
+ struct iscsi_transport *t;
+ uint32_t hostno;
+
if (strlen(context->initiatorname))
strlcpy(iface->iname, context->initiatorname,
sizeof(iface->iname));
if (strlen(context->scsi_host_name)) {
- struct iscsi_transport *t;
- uint32_t hostno;
-
if (sscanf(context->scsi_host_name, "iscsi_boot%u", &hostno) != 1) {
log_error("Could not parse %s's host no.",
context->scsi_host_name);
return 0;
}
- t = iscsi_sysfs_get_transport_by_hba(hostno);
- if (!t) {
- log_error("Could not get transport for %s. "
- "Make sure the iSCSI driver is loaded.",
- context->scsi_host_name);
+ } else if (strlen(context->iface)) {
+/* this ifdef is only temp until distros and firmwares are updated */
+#ifdef OFFLOAD_BOOT_SUPPORTED
+ hostno = iscsi_sysfs_get_host_no_from_hwaddress(context->mac,
+ &rc);
+ if (rc) {
+ /*
+ * If the MAC in the boot info does not match a iscsi
+ * host then the MAC must be for network card, so boot
+ * is not going to be offloaded.
+ */
+ log_debug(3, "Could not match %s to host\n",
+ context->mac);
return 0;
}
- log_debug(3, "boot context has %s transport %s",
- context->scsi_host_name, t->name);
- strcpy(iface->transport_name, t->name);
- } else if (strlen(context->iface) &&
- (!net_get_transport_name_from_netdev(context->iface,
- iface->transport_name))) {
- log_debug(3, "boot context has netdev %s",
- context->iface);
- strlcpy(iface->netdev, context->iface,
- sizeof(iface->netdev));
+ strlcpy(iface->netdev, context->iface, sizeof(iface->netdev));
+#else
+ return 0;
+#endif
} else
return 0;
+
/*
* set up for access through a offload card.
*/
+ t = iscsi_sysfs_get_transport_by_hba(hostno);
+ if (!t) {
+ log_error("Could not get transport for host%u. "
+ "Make sure the iSCSI driver is loaded.",
+ hostno);
+ return 0;
+ }
+ strcpy(iface->transport_name, t->name);
+
memset(iface->name, 0, sizeof(iface->name));
snprintf(iface->name, sizeof(iface->name), "%s.%s",
iface->transport_name, context->mac);
-
strlcpy(iface->hwaddress, context->mac,
sizeof(iface->hwaddress));
strlcpy(iface->ipaddress, context->ipaddr,
@@ -885,3 +966,841 @@ fail:
}
return rc;
}
+
+struct iface_param_count {
+ struct iface_rec *primary;
+ int count;
+};
+
+/**
+ * __iface_get_param_count - Gets netconfig parameter count for given iface
+ * @data: iface_param_count structure
+ * @iface: iface to setup
+ */
+static int __iface_get_param_count(void *data, struct iface_rec *iface)
+{
+ struct iface_param_count *iface_params = data;
+ int iptype = ISCSI_IFACE_TYPE_IPV4;
+ int count = 0;
+
+ if (strcmp(iface_params->primary->hwaddress, iface->hwaddress))
+ return 0;
+
+ iptype = iface_get_iptype(iface);
+ if (iptype == ISCSI_IFACE_TYPE_IPV4) {
+
+ if (strcmp(iface->state, "disable")) {
+ if (strstr(iface->bootproto, "dhcp"))
+ /* DHCP enabled */
+ count++;
+ else {
+ /* DHCP disabled */
+ count++;
+
+ if (strstr(iface->ipaddress, ".")) {
+ /* User configured IPv4 Address */
+ count++;
+
+ if (strstr(iface->subnet_mask, "."))
+ /* User configured Subnet */
+ count++;
+
+ if (strstr(iface->gateway, "."))
+ /* User configured Gateway */
+ count++;
+ } else
+ /*
+ * IPv4 Address not valid, decrement
+ * count of DHCP
+ */
+ count--;
+ }
+
+ /*
+ * If IPv4 configuration in iface file is valid,
+ * enable state and other parameters (if any)
+ */
+ if (count) {
+ /* iface state */
+ count++;
+
+ if (strcmp(iface->vlan_state, "disable")) {
+ /* vlan_state enabled */
+ count++;
+
+ if (iface->vlan_id)
+ /* For vlan value */
+ count++;
+ } else
+ /* vlan_state disabled */
+ count++;
+
+ if (iface->mtu)
+ count++;
+
+ if (iface->port)
+ count++;
+ }
+ } else
+ /* IPv4 is disabled, iface state */
+ count++;
+
+ } else if (iptype == ISCSI_IFACE_TYPE_IPV6) {
+
+ if (strcmp(iface->state, "disable")) {
+
+ /* IPv6 Address */
+ if (strstr(iface->ipv6_autocfg, "nd") ||
+ strstr(iface->ipv6_autocfg, "dhcpv6"))
+ /* Autocfg enabled */
+ count++;
+ else {
+ /* Autocfg disabled */
+ count++;
+
+ if (strstr(iface->ipaddress, ":"))
+ /* User configured IPv6 Address */
+ count++;
+ else
+ /*
+ * IPv6 Address not valid, decrement
+ * count of IPv6 Autocfg
+ */
+ count--;
+ }
+
+ /* IPv6 LinkLocal Address */
+ if (strstr(iface->linklocal_autocfg, "auto"))
+ /* Autocfg enabled */
+ count++;
+ else {
+ /* Autocfg disabled */
+ count++;
+
+ if (strstr(iface->ipv6_linklocal, ":"))
+ /* User configured LinkLocal Address */
+ count++;
+ else
+ /*
+ * LinkLocal Address not valid,
+ * decrement count of LinkLocal Autocfg
+ */
+ count--;
+ }
+
+ /* IPv6 Router Address */
+ if (strstr(iface->router_autocfg, "auto"))
+ /* Autocfg enabled */
+ count++;
+ else {
+ /* Autocfg disabled */
+ count++;
+
+ if (strstr(iface->ipv6_router, ":"))
+ /* User configured Router Address */
+ count++;
+ else
+ /*
+ * Router Address not valid,
+ * decrement count of Router Autocfg
+ */
+ count--;
+ }
+
+ /*
+ * If IPv6 configuration in iface file is valid,
+ * enable state and other parameters (if any)
+ */
+ if (count) {
+ /* iface state */
+ count++;
+
+ if (strcmp(iface->vlan_state, "disable")) {
+ /* vlan_state enabled */
+ count++;
+
+ if (iface->vlan_id)
+ /* For vlan value */
+ count++;
+ } else
+ /* vlan_state disabled */
+ count++;
+
+ if (iface->mtu)
+ count++;
+
+ if (iface->port)
+ count++;
+ }
+ } else
+ /* IPv6 is disabled, iface state */
+ count++;
+ }
+
+ iface_params->count += count;
+ return 0;
+}
+
+/**
+ * iface_get_param_count - Gets netconfig parameter count from iface
+ * @iface: iface to setup
+ * @iface_all: Flag for number of ifaces to traverse (1 for all)
+ *
+ * Returns netconfig parameter count.
+ */
+int iface_get_param_count(struct iface_rec *iface, int iface_all)
+{
+ int num_found = 0, rc;
+ struct iface_param_count iface_params;
+
+ log_debug(8, "In iface_get_param_count\n");
+
+ iface_params.primary = iface;
+ iface_params.count = 0;
+
+ if (iface_all)
+ rc = iface_for_each_iface(&iface_params, 0, &num_found,
+ __iface_get_param_count);
+ else
+ rc = __iface_get_param_count(&iface_params, iface);
+
+ log_debug(8, "iface_get_param_count: rc = %d, count = %d\n",
+ rc, iface_params.count);
+ return iface_params.count;
+}
+
+/* IPv4/IPv6 Port: 3260 or User defined */
+static int iface_fill_port(struct iovec *iov, struct iface_rec *iface,
+ uint32_t iface_type)
+{
+ int len;
+ struct iscsi_iface_param_info *net_param;
+ uint16_t port = 3260;
+ struct nlattr *attr;
+
+ len = sizeof(struct iscsi_iface_param_info) + sizeof(port);
+ iov->iov_base = iscsi_nla_alloc(ISCSI_NET_PARAM_PORT, len);
+ if (!iov->iov_base)
+ return 1;
+ attr = iov->iov_base;
+ iov->iov_len = NLA_ALIGN(attr->nla_len);
+
+ net_param = (struct iscsi_iface_param_info *)ISCSI_NLA_DATA(attr);
+ net_param->param = ISCSI_NET_PARAM_PORT;
+ net_param->iface_type = iface_type;
+ net_param->iface_num = iface->iface_num;
+ net_param->param_type = ISCSI_NET_PARAM;
+ net_param->len = 2;
+ if (iface->port)
+ port = iface->port;
+ memcpy(net_param->value, &port, net_param->len);
+ return 0;
+}
+
+static int iface_fill_mtu(struct iovec *iov, struct iface_rec *iface,
+ uint32_t iface_type)
+{
+ int len;
+ struct iscsi_iface_param_info *net_param;
+ uint16_t mtu = 0;
+ struct nlattr *attr;
+
+ len = sizeof(struct iscsi_iface_param_info) + 2;
+ iov->iov_base = iscsi_nla_alloc(ISCSI_NET_PARAM_MTU, len);
+ if (!(iov->iov_base))
+ return 1;
+ attr = iov->iov_base;
+ iov->iov_len = NLA_ALIGN(attr->nla_len);
+
+ net_param = (struct iscsi_iface_param_info *)ISCSI_NLA_DATA(attr);
+ net_param->param = ISCSI_NET_PARAM_MTU;
+ net_param->iface_type = iface_type;
+ net_param->iface_num = iface->iface_num;
+ net_param->param_type = ISCSI_NET_PARAM;
+ net_param->len = 2;
+ mtu = iface->mtu;
+ memcpy(net_param->value, &mtu, net_param->len);
+ return 0;
+}
+
+/* IPv4/IPv6 VLAN_ID: decimal value <= 4095 */
+static int iface_fill_vlan_id(struct iovec *iov, struct iface_rec *iface,
+ uint32_t iface_type)
+{
+ int len;
+ struct iscsi_iface_param_info *net_param;
+ uint16_t vlan = 0;
+ struct nlattr *attr;
+
+ len = sizeof(struct iscsi_iface_param_info) + 2;
+ iov->iov_base = iscsi_nla_alloc(ISCSI_NET_PARAM_VLAN_TAG, len);
+ if (!(iov->iov_base))
+ return 1;
+
+ attr = iov->iov_base;
+ iov->iov_len = NLA_ALIGN(attr->nla_len);
+ net_param = (struct iscsi_iface_param_info *)ISCSI_NLA_DATA(attr);
+ net_param->param = ISCSI_NET_PARAM_VLAN_TAG;
+ net_param->iface_type = iface_type;
+ net_param->iface_num = iface->iface_num;
+ net_param->param_type = ISCSI_NET_PARAM;
+ net_param->len = 2;
+ if (iface->vlan_id <= ISCSI_MAX_VLAN_ID &&
+ iface->vlan_priority <= ISCSI_MAX_VLAN_PRIORITY)
+ /*
+ * Bit 15-13: User Priority of VLAN
+ * Bit 11-00: VLAN ID
+ */
+ vlan = (iface->vlan_priority << 13) |
+ (iface->vlan_id & ISCSI_MAX_VLAN_ID);
+ memcpy(net_param->value, &vlan, net_param->len);
+ return 0;
+}
+
+/* IPv4/IPv6 VLAN state: disable/enable */
+static int iface_fill_vlan_state(struct iovec *iov, struct iface_rec *iface,
+ uint32_t iface_type)
+{
+ int len;
+ struct iscsi_iface_param_info *net_param;
+ struct nlattr *attr;
+
+ len = sizeof(struct iscsi_iface_param_info) + 1;
+ iov->iov_base = iscsi_nla_alloc(ISCSI_NET_PARAM_VLAN_ENABLED, len);
+ if (!(iov->iov_base))
+ return 1;
+
+ attr = iov->iov_base;
+ iov->iov_len = NLA_ALIGN(attr->nla_len);
+ net_param = (struct iscsi_iface_param_info *)ISCSI_NLA_DATA(attr);
+ net_param->param = ISCSI_NET_PARAM_VLAN_ENABLED;
+ net_param->iface_type = iface_type;
+ net_param->iface_num = iface->iface_num;
+ net_param->param_type = ISCSI_NET_PARAM;
+ net_param->len = 1;
+ if (strcmp(iface->vlan_state, "disable") && iface->vlan_id)
+ net_param->value[0] = ISCSI_VLAN_ENABLE;
+ else /* Assume disabled */
+ net_param->value[0] = ISCSI_VLAN_DISABLE;
+ return 0;
+}
+
+/* IPv4/IPv6 Network state: disable/enable */
+static int iface_fill_net_state(struct iovec *iov, struct iface_rec *iface,
+ uint32_t iface_type)
+{
+ int len;
+ struct iscsi_iface_param_info *net_param;
+ struct nlattr *attr;
+
+ len = sizeof(struct iscsi_iface_param_info) + 1;
+ iov->iov_base = iscsi_nla_alloc(ISCSI_NET_PARAM_IFACE_ENABLE, len);
+ if (!(iov->iov_base))
+ return 1;
+
+ attr = iov->iov_base;
+ iov->iov_len = NLA_ALIGN(attr->nla_len);
+ net_param = (struct iscsi_iface_param_info *)ISCSI_NLA_DATA(attr);
+ net_param->param = ISCSI_NET_PARAM_IFACE_ENABLE;
+ net_param->iface_type = iface_type;
+ net_param->iface_num = iface->iface_num;
+ net_param->param_type = ISCSI_NET_PARAM;
+ net_param->len = 1;
+ if (!strcmp(iface->state, "disable"))
+ net_param->value[0] = ISCSI_IFACE_DISABLE;
+ else /* Assume enabled */
+ net_param->value[0] = ISCSI_IFACE_ENABLE;
+ return 0;
+}
+
+/* IPv4 Bootproto: DHCP/static */
+static int iface_fill_net_bootproto(struct iovec *iov, struct iface_rec *iface)
+{
+ int len;
+ struct iscsi_iface_param_info *net_param;
+ struct nlattr *attr;
+
+ len = sizeof(struct iscsi_iface_param_info) + 1;
+ iov->iov_base = iscsi_nla_alloc(ISCSI_NET_PARAM_IPV4_BOOTPROTO, len);
+ if (!(iov->iov_base))
+ return 1;
+
+ attr = iov->iov_base;
+ iov->iov_len = NLA_ALIGN(attr->nla_len);
+ net_param = (struct iscsi_iface_param_info *)ISCSI_NLA_DATA(attr);
+ net_param->param = ISCSI_NET_PARAM_IPV4_BOOTPROTO;
+ net_param->iface_type = ISCSI_IFACE_TYPE_IPV4;
+ net_param->iface_num = iface->iface_num;
+ net_param->param_type = ISCSI_NET_PARAM;
+ net_param->len = 1;
+ if (!strcmp(iface->bootproto, "dhcp"))
+ net_param->value[0] = ISCSI_BOOTPROTO_DHCP;
+ else
+ net_param->value[0] = ISCSI_BOOTPROTO_STATIC;
+ return 0;
+}
+
+/* IPv6 IPAddress Autocfg: nd/dhcpv6/disable */
+static int iface_fill_net_autocfg(struct iovec *iov, struct iface_rec *iface)
+{
+ int len;
+ struct iscsi_iface_param_info *net_param;
+ struct nlattr *attr;
+
+ len = sizeof(struct iscsi_iface_param_info) + 1;
+ iov->iov_base = iscsi_nla_alloc(ISCSI_NET_PARAM_IPV6_ADDR_AUTOCFG, len);
+ if (!(iov->iov_base))
+ return 1;
+
+ attr = iov->iov_base;
+ iov->iov_len = NLA_ALIGN(attr->nla_len);
+ net_param = (struct iscsi_iface_param_info *)ISCSI_NLA_DATA(attr);
+ net_param->param = ISCSI_NET_PARAM_IPV6_ADDR_AUTOCFG;
+ net_param->iface_type = ISCSI_IFACE_TYPE_IPV6;
+ net_param->param_type = ISCSI_NET_PARAM;
+ net_param->len = 1;
+
+ if (!strcmp(iface->ipv6_autocfg, "nd"))
+ net_param->value[0] = ISCSI_IPV6_AUTOCFG_ND_ENABLE;
+ else if (!strcmp(iface->ipv6_autocfg, "dhcpv6"))
+ net_param->value[0] = ISCSI_IPV6_AUTOCFG_DHCPV6_ENABLE;
+ else
+ net_param->value[0] = ISCSI_IPV6_AUTOCFG_DISABLE;
+
+ return 0;
+}
+
+/* IPv6 LinkLocal Autocfg: enable/disable */
+static int iface_fill_linklocal_autocfg(struct iovec *iov,
+ struct iface_rec *iface)
+{
+ int len;
+ struct iscsi_iface_param_info *net_param;
+ struct nlattr *attr;
+
+ len = sizeof(struct iscsi_iface_param_info) + 1;
+ iov->iov_base = iscsi_nla_alloc(ISCSI_NET_PARAM_IPV6_LINKLOCAL_AUTOCFG,
+ len);
+ if (!(iov->iov_base))
+ return 1;
+
+ attr = iov->iov_base;
+ iov->iov_len = NLA_ALIGN(attr->nla_len);
+ net_param = (struct iscsi_iface_param_info *)ISCSI_NLA_DATA(attr);
+ net_param->param = ISCSI_NET_PARAM_IPV6_LINKLOCAL_AUTOCFG;
+ net_param->iface_type = ISCSI_IFACE_TYPE_IPV6;
+ net_param->param_type = ISCSI_NET_PARAM;
+ net_param->len = 1;
+
+ if (strstr(iface->linklocal_autocfg, "auto"))
+ net_param->value[0] = ISCSI_IPV6_LINKLOCAL_AUTOCFG_ENABLE;
+ else
+ net_param->value[0] = ISCSI_IPV6_LINKLOCAL_AUTOCFG_DISABLE;
+
+ return 0;
+}
+
+/* IPv6 Router Autocfg: enable/disable */
+static int iface_fill_router_autocfg(struct iovec *iov, struct iface_rec *iface)
+{
+ int len;
+ struct iscsi_iface_param_info *net_param;
+ struct nlattr *attr;
+
+ len = sizeof(struct iscsi_iface_param_info) + 1;
+ iov->iov_base = iscsi_nla_alloc(ISCSI_NET_PARAM_IPV6_ROUTER_AUTOCFG,
+ len);
+ if (!(iov->iov_base))
+ return 1;
+
+ attr = iov->iov_base;
+ iov->iov_len = NLA_ALIGN(attr->nla_len);
+ net_param = (struct iscsi_iface_param_info *)ISCSI_NLA_DATA(attr);
+ net_param->param = ISCSI_NET_PARAM_IPV6_ROUTER_AUTOCFG;
+ net_param->iface_type = ISCSI_IFACE_TYPE_IPV6;
+ net_param->param_type = ISCSI_NET_PARAM;
+ net_param->len = 1;
+
+ if (strstr(iface->router_autocfg, "auto"))
+ net_param->value[0] = ISCSI_IPV6_ROUTER_AUTOCFG_ENABLE;
+ else
+ net_param->value[0] = ISCSI_IPV6_ROUTER_AUTOCFG_DISABLE;
+
+ return 0;
+}
+
+/* IPv4 IPAddress/Subnet Mask/Gateway: 4 bytes */
+static int iface_fill_net_ipv4_addr(struct iovec *iov, struct iface_rec *iface,
+ uint32_t param)
+{
+ int rc = 1;
+ int len;
+ struct iscsi_iface_param_info *net_param;
+ struct nlattr *attr;
+
+ len = sizeof(struct iscsi_iface_param_info) + 4;
+ iov->iov_base = iscsi_nla_alloc(param, len);
+ if (!(iov->iov_base))
+ return 1;
+
+ attr = iov->iov_base;
+ iov->iov_len = NLA_ALIGN(attr->nla_len);
+ net_param = (struct iscsi_iface_param_info *)ISCSI_NLA_DATA(attr);
+ net_param->param = param;
+ net_param->iface_type = ISCSI_IFACE_TYPE_IPV4;
+ net_param->iface_num = iface->iface_num;
+ net_param->len = 4;
+ net_param->param_type = ISCSI_NET_PARAM;
+
+ switch (param) {
+ case ISCSI_NET_PARAM_IPV4_ADDR:
+ rc = inet_pton(AF_INET, iface->ipaddress, net_param->value);
+ if (rc <= 0)
+ goto free;
+ break;
+ case ISCSI_NET_PARAM_IPV4_SUBNET:
+ rc = inet_pton(AF_INET, iface->subnet_mask, net_param->value);
+ if (rc <= 0)
+ goto free;
+ break;
+ case ISCSI_NET_PARAM_IPV4_GW:
+ rc = inet_pton(AF_INET, iface->gateway, net_param->value);
+ if (rc <= 0)
+ goto free;
+ break;
+ default:
+ goto free;
+ }
+
+ /* validate */
+ if (!net_param->value[0] && !net_param->value[1] &&
+ !net_param->value[2] && !net_param->value[3])
+ goto free;
+
+ return 0;
+free:
+ free(iov->iov_base);
+ iov->iov_base = NULL;
+ iov->iov_len = 0;
+ return 1;
+}
+
+/* IPv6 IPAddress/LinkLocal/Router: 16 bytes */
+static int iface_fill_net_ipv6_addr(struct iovec *iov, struct iface_rec *iface,
+ uint32_t param)
+{
+ int rc;
+ int len;
+ struct iscsi_iface_param_info *net_param;
+ struct nlattr *attr;
+
+ len = sizeof(struct iscsi_iface_param_info) + 16;
+ iov->iov_base = iscsi_nla_alloc(param, len);
+ if (!(iov->iov_base))
+ return 1;
+
+ attr = iov->iov_base;
+ iov->iov_len = NLA_ALIGN(attr->nla_len);
+ net_param = (struct iscsi_iface_param_info *)ISCSI_NLA_DATA(attr);
+ net_param->param = param;
+ net_param->iface_type = ISCSI_IFACE_TYPE_IPV6;
+ net_param->iface_num = iface->iface_num;
+ net_param->param_type = ISCSI_NET_PARAM;
+ net_param->len = 16;
+
+ switch (param) {
+ case ISCSI_NET_PARAM_IPV6_ADDR:
+ rc = inet_pton(AF_INET6, iface->ipaddress, net_param->value);
+ if (rc <= 0)
+ goto free;
+ break;
+ case ISCSI_NET_PARAM_IPV6_LINKLOCAL:
+ rc = inet_pton(AF_INET6, iface->ipv6_linklocal,
+ net_param->value);
+ if (rc <= 0)
+ goto free;
+ break;
+ case ISCSI_NET_PARAM_IPV6_ROUTER:
+ rc = inet_pton(AF_INET6, iface->ipv6_router, net_param->value);
+ if (rc <= 0)
+ goto free;
+ break;
+ default:
+ goto free;
+ }
+
+ return 0;
+free:
+ free(iov->iov_base);
+ iov->iov_base = NULL;
+ iov->iov_len = 0;
+ return 1;
+}
+
+struct iface_net_config {
+ struct iface_rec *primary;
+ struct iovec *iovs;
+ int count;
+};
+
+static int __iface_build_net_config(void *data, struct iface_rec *iface)
+{
+ struct iface_net_config *net_config = data;
+ struct iovec *iov;
+ int iptype = ISCSI_IFACE_TYPE_IPV4;
+ int count = 0;
+
+ if (strcmp(net_config->primary->hwaddress, iface->hwaddress))
+ return 0;
+
+ /* start at 2, because 0 is for nlmsghdr and 1 for event */
+ iov = net_config->iovs + 2;
+
+ iptype = iface_get_iptype(iface);
+ if (iptype == ISCSI_IFACE_TYPE_IPV4) {
+ if (!strcmp(iface->state, "disable")) {
+ if (!iface_fill_net_state(&iov[net_config->count],
+ iface,
+ ISCSI_IFACE_TYPE_IPV4)) {
+ net_config->count++;
+ count++;
+ }
+
+ return 0;
+ }
+
+ if (strstr(iface->bootproto, "dhcp")) {
+ if (!iface_fill_net_bootproto(&iov[net_config->count],
+ iface)) {
+ net_config->count++;
+ count++;
+ }
+ } else if (strstr(iface->ipaddress, ".")) {
+ if (!iface_fill_net_bootproto(&iov[net_config->count],
+ iface)) {
+ net_config->count++;
+ count++;
+ }
+ if (!iface_fill_net_ipv4_addr(&iov[net_config->count],
+ iface,
+ ISCSI_NET_PARAM_IPV4_ADDR)) {
+ net_config->count++;
+ count++;
+ }
+ if (strstr(iface->subnet_mask, ".")) {
+ if (!iface_fill_net_ipv4_addr(
+ &iov[net_config->count], iface,
+ ISCSI_NET_PARAM_IPV4_SUBNET)) {
+ net_config->count++;
+ count++;
+ }
+ }
+ if (strstr(iface->gateway, ".")) {
+ if (!iface_fill_net_ipv4_addr(
+ &iov[net_config->count], iface,
+ ISCSI_NET_PARAM_IPV4_GW)) {
+ net_config->count++;
+ count++;
+ }
+ }
+ }
+
+ /*
+ * If IPv4 configuration in iface file is valid,
+ * fill state and other parameters (if any)
+ */
+ if (count) {
+ if (!iface_fill_net_state(&iov[net_config->count],
+ iface,
+ ISCSI_IFACE_TYPE_IPV4)) {
+ net_config->count++;
+ count++;
+ }
+ if (!iface_fill_vlan_state(&iov[net_config->count],
+ iface,
+ ISCSI_IFACE_TYPE_IPV4)) {
+ net_config->count++;
+ count++;
+ }
+ if (strcmp(iface->vlan_state, "disable") &&
+ iface->vlan_id) {
+ if (!iface_fill_vlan_id(&iov[net_config->count],
+ iface, ISCSI_IFACE_TYPE_IPV4)) {
+ net_config->count++;
+ count++;
+ }
+ }
+ if (iface->mtu) {
+ if (!iface_fill_mtu(&iov[net_config->count],
+ iface,
+ ISCSI_IFACE_TYPE_IPV4)) {
+ net_config->count++;
+ count++;
+ }
+ }
+ if (iface->port) {
+ if (!iface_fill_port(&iov[net_config->count],
+ iface,
+ ISCSI_IFACE_TYPE_IPV4)) {
+ net_config->count++;
+ count++;
+ }
+ }
+ }
+ } else if (iptype == ISCSI_IFACE_TYPE_IPV6) {
+ if (!strcmp(iface->state, "disable")) {
+ if (!iface_fill_net_state(&iov[net_config->count],
+ iface,
+ ISCSI_IFACE_TYPE_IPV6)) {
+ net_config->count++;
+ count++;
+ }
+ return 0;
+ }
+
+ /* For IPv6 Address */
+ if (strstr(iface->ipv6_autocfg, "nd") ||
+ strstr(iface->ipv6_autocfg, "dhcpv6")) {
+ if (!iface_fill_net_autocfg(&iov[net_config->count],
+ iface)) {
+ net_config->count++;
+ count++;
+ }
+ } else if (strstr(iface->ipaddress, ":")) {
+ if (!iface_fill_net_autocfg(&iov[net_config->count],
+ iface)) {
+ net_config->count++;
+ count++;
+ }
+ /* User provided IPv6 Address */
+ if (!iface_fill_net_ipv6_addr(&iov[net_config->count],
+ iface,
+ ISCSI_NET_PARAM_IPV6_ADDR)) {
+ net_config->count++;
+ count++;
+ }
+ }
+
+ /* For LinkLocal Address */
+ if (strstr(iface->linklocal_autocfg, "auto")) {
+ if (!iface_fill_linklocal_autocfg(
+ &iov[net_config->count],
+ iface)) {
+ net_config->count++;
+ count++;
+ }
+ } else if (strstr(iface->ipv6_linklocal, ":")) {
+ if (!iface_fill_linklocal_autocfg(
+ &iov[net_config->count],
+ iface)) {
+ net_config->count++;
+ count++;
+ }
+ /* User provided Link Local Address */
+ if (!iface_fill_net_ipv6_addr(&iov[net_config->count],
+ iface,
+ ISCSI_NET_PARAM_IPV6_LINKLOCAL)) {
+ net_config->count++;
+ count++;
+ }
+ }
+
+ /* For Router Address */
+ if (strstr(iface->router_autocfg, "auto")) {
+ if (!iface_fill_router_autocfg(&iov[net_config->count],
+ iface)) {
+ net_config->count++;
+ count++;
+ }
+ } else if (strstr(iface->ipv6_router, ":")) {
+ if (!iface_fill_router_autocfg(&iov[net_config->count],
+ iface)) {
+ net_config->count++;
+ count++;
+ }
+ /* User provided Router Address */
+ if (!iface_fill_net_ipv6_addr(&iov[net_config->count],
+ iface,
+ ISCSI_NET_PARAM_IPV6_ROUTER)) {
+ net_config->count++;
+ count++;
+ }
+ }
+
+ /*
+ * If IPv6 configuration in iface file is valid,
+ * fill state and other parameters
+ */
+ if (count) {
+ if (!iface_fill_net_state(&iov[net_config->count],
+ iface,
+ ISCSI_IFACE_TYPE_IPV6)) {
+ net_config->count++;
+ count++;
+ }
+ if (!iface_fill_vlan_state(&iov[net_config->count],
+ iface,
+ ISCSI_IFACE_TYPE_IPV6)) {
+ net_config->count++;
+ count++;
+ }
+ if (strcmp(iface->vlan_state, "disable") &&
+ iface->vlan_id) {
+ if (!iface_fill_vlan_id(&iov[net_config->count],
+ iface,
+ ISCSI_IFACE_TYPE_IPV6)) {
+ net_config->count++;
+ count++;
+ }
+ }
+ if (iface->mtu) {
+ if (!iface_fill_mtu(&iov[net_config->count],
+ iface,
+ ISCSI_IFACE_TYPE_IPV6)) {
+ net_config->count++;
+ count++;
+ }
+ }
+ if (iface->port) {
+ if (!iface_fill_port(&iov[net_config->count],
+ iface,
+ ISCSI_IFACE_TYPE_IPV6)) {
+ net_config->count++;
+ count++;
+ }
+ }
+ }
+ }
+ return 0;
+}
+
+/**
+ * iface_build_net_config - Setup neconfig parameter buffers
+ * @iface: iface to setup
+ * @iface_all: Flag for number of ifaces to traverse (1 for all)
+ * @iovs: iovec buffer for netconfig parameters
+ *
+ * Returns total number of netconfig parameter buffers used.
+ */
+int iface_build_net_config(struct iface_rec *iface, int iface_all,
+ struct iovec *iovs)
+{
+ int num_found = 0, rc;
+ struct iface_net_config net_config;
+
+ log_debug(8, "In iface_build_net_config\n");
+
+ net_config.primary = iface;
+ net_config.iovs = iovs;
+ net_config.count = 0;
+
+ if (iface_all)
+ rc = iface_for_each_iface(&net_config, 0, &num_found,
+ __iface_build_net_config);
+ else
+ rc = __iface_build_net_config(&net_config, iface);
+
+ log_debug(8, "iface_build_net_config: rc = %d, count = %d\n",
+ rc, net_config.count);
+ return net_config.count;
+}
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/iface.h open-iscsi-2.0-872-rc4-bnx2i.work/usr/iface.h
--- open-iscsi-2.0-872-rc4-bnx2i/usr/iface.h 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/iface.h 2012-03-05 23:02:46.000000000 -0600
@@ -54,6 +54,10 @@ extern int iface_setup_from_boot_context
struct boot_context *context);
extern int iface_create_ifaces_from_boot_contexts(struct list_head *ifaces,
struct list_head *targets);
+extern int iface_get_param_count(struct iface_rec *iface_primary,
+ int iface_all);
+extern int iface_build_net_config(struct iface_rec *iface_primary,
+ int iface_all, struct iovec *iovs);
#define iface_fmt "[hw=%s,ip=%s,net_if=%s,iscsi_if=%s]"
#define iface_str(_iface) \
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/initiator.c open-iscsi-2.0-872-rc4-bnx2i.work/usr/initiator.c
--- open-iscsi-2.0-872-rc4-bnx2i/usr/initiator.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/initiator.c 2012-03-05 23:05:40.000000000 -0600
@@ -46,6 +46,8 @@
#include "iscsi_settings.h"
#include "iface.h"
#include "sysdeps.h"
+#include "iscsi_err.h"
+#include "kern_err_table.h"
#define ISCSI_CONN_ERR_REOPEN_DELAY 3
#define ISCSI_INTERNAL_ERR_REOPEN_DELAY 5
@@ -53,31 +55,17 @@
#define PROC_DIR "/proc"
static void iscsi_login_timedout(void *data);
+static int iscsi_sched_ev_context(struct iscsi_ev_context *ev_context,
+ struct iscsi_conn *conn, unsigned long tmo,
+ int event);
-/*
- * calculate parameter's padding
- */
-static unsigned int
-__padding(unsigned int param)
-{
- int pad;
-
- pad = param & 3;
- if (pad) {
- pad = 4 - pad;
- log_debug(1, "parameter's value %d padded to %d bytes\n",
- param, param + pad);
- }
- return param + pad;
-}
-
-static int iscsi_conn_context_alloc(iscsi_conn_t *conn)
+static int iscsi_ev_context_alloc(iscsi_conn_t *conn)
{
int i;
for (i = 0; i < CONTEXT_POOL_MAX; i++) {
conn->context_pool[i] = calloc(1,
- sizeof(struct iscsi_conn_context) +
+ sizeof(struct iscsi_ev_context) +
ipc->ctldev_bufmax);
if (!conn->context_pool[i]) {
int j;
@@ -91,7 +79,7 @@ static int iscsi_conn_context_alloc(iscs
return 0;
}
-static void iscsi_conn_context_free(iscsi_conn_t *conn)
+static void iscsi_ev_context_free(iscsi_conn_t *conn)
{
int i;
@@ -107,10 +95,10 @@ static void iscsi_conn_context_free(iscs
}
}
-struct iscsi_conn_context *iscsi_conn_context_get(iscsi_conn_t *conn,
- int ev_size)
+static struct iscsi_ev_context *
+iscsi_ev_context_get(iscsi_conn_t *conn, int ev_size)
{
- struct iscsi_conn_context *conn_context;
+ struct iscsi_ev_context *ev_context;
int i;
if (ev_size > ipc->ctldev_bufmax)
@@ -121,26 +109,26 @@ struct iscsi_conn_context *iscsi_conn_co
continue;
if (!conn->context_pool[i]->allocated) {
- conn_context = conn->context_pool[i];
+ ev_context = conn->context_pool[i];
- memset(&conn_context->actor, 0,
+ memset(&ev_context->actor, 0,
sizeof(struct actor));
- conn_context->allocated = 1;
+ ev_context->allocated = 1;
/* some callers abuse this pointer */
- conn_context->data = (void *)conn_context +
- sizeof(struct iscsi_conn_context);
- log_debug(7, "get conn context %p",
- &conn_context->actor);
- return conn_context;
+ ev_context->data = (void *)ev_context +
+ sizeof(struct iscsi_ev_context);
+ log_debug(7, "get ev context %p",
+ &ev_context->actor);
+ return ev_context;
}
}
return NULL;
}
-void iscsi_conn_context_put(struct iscsi_conn_context *conn_context)
+static void iscsi_ev_context_put(struct iscsi_ev_context *ev_context)
{
- log_debug(7, "put conn context %p", &conn_context->actor);
- conn_context->allocated = 0;
+ log_debug(7, "put ev context %p", &ev_context->actor);
+ ev_context->allocated = 0;
}
static void session_online_devs(int host_no, int sid)
@@ -205,11 +193,11 @@ __check_iscsi_status_class(iscsi_session
log_error("session %d login rejected: Initiator "
"failed authentication with target",
session->id);
- return CONN_LOGIN_FAILED;
+ return CONN_LOGIN_AUTH_FAILED;
case ISCSI_LOGIN_STATUS_TGT_FORBIDDEN:
log_error("conn %d login rejected: initiator "
"failed authorization with target", conn->id);
- return CONN_LOGIN_FAILED;
+ return CONN_LOGIN_AUTH_FAILED;
case ISCSI_LOGIN_STATUS_TGT_NOT_FOUND:
log_error("conn %d login rejected: initiator "
"error - target not found (%02x/%02x)",
@@ -250,183 +238,6 @@ __check_iscsi_status_class(iscsi_session
return CONN_LOGIN_FAILED;
}
-static void
-__setup_authentication(iscsi_session_t *session,
- struct iscsi_auth_config *auth_cfg)
-{
- /* if we have any incoming credentials, we insist on authenticating
- * the target or not logging in at all
- */
- if (auth_cfg->username_in[0]
- || auth_cfg->password_in_length) {
- /* sanity check the config */
- if (auth_cfg->password_length == 0) {
- log_debug(1,
- "node record has incoming "
- "authentication credentials but has no outgoing "
- "credentials configured, exiting");
- return;
- }
- session->bidirectional_auth = 1;
- } else {
- /* no or 1-way authentication */
- session->bidirectional_auth = 0;
- }
-
- /* copy in whatever credentials we have */
- strlcpy(session->username, auth_cfg->username,
- sizeof (session->username));
- session->username[sizeof (session->username) - 1] = '\0';
- if ((session->password_length = auth_cfg->password_length))
- memcpy(session->password, auth_cfg->password,
- session->password_length);
-
- strlcpy(session->username_in, auth_cfg->username_in,
- sizeof (session->username_in));
- session->username_in[sizeof (session->username_in) - 1] = '\0';
- if ((session->password_in_length =
- auth_cfg->password_in_length))
- memcpy(session->password_in, auth_cfg->password_in,
- session->password_in_length);
-
- if (session->password_length || session->password_in_length) {
- /* setup the auth buffers */
- session->auth_buffers[0].address = &session->auth_client_block;
- session->auth_buffers[0].length =
- sizeof (session->auth_client_block);
- session->auth_buffers[1].address =
- &session->auth_recv_string_block;
- session->auth_buffers[1].length =
- sizeof (session->auth_recv_string_block);
-
- session->auth_buffers[2].address =
- &session->auth_send_string_block;
- session->auth_buffers[2].length =
- sizeof (session->auth_send_string_block);
-
- session->auth_buffers[3].address =
- &session->auth_recv_binary_block;
- session->auth_buffers[3].length =
- sizeof (session->auth_recv_binary_block);
-
- session->auth_buffers[4].address =
- &session->auth_send_binary_block;
- session->auth_buffers[4].length =
- sizeof (session->auth_send_binary_block);
-
- session->num_auth_buffers = 5;
- log_debug(6, "authentication setup complete...");
- } else {
- session->num_auth_buffers = 0;
- log_debug(6, "no authentication configured...");
- }
-}
-
-static int
-setup_portal(iscsi_conn_t *conn, conn_rec_t *conn_rec)
-{
- char port[NI_MAXSERV];
-
- sprintf(port, "%d", conn_rec->port);
- if (resolve_address(conn_rec->address, port, &conn->saddr)) {
- log_error("cannot resolve host name %s",
- conn_rec->address);
- return EINVAL;
- }
- conn->failback_saddr = conn->saddr;
-
- getnameinfo((struct sockaddr *)&conn->saddr, sizeof(conn->saddr),
- conn->host, sizeof(conn->host), NULL, 0, NI_NUMERICHOST);
- log_debug(4, "resolved %s to %s", conn_rec->address, conn->host);
- return 0;
-}
-
-static void
-iscsi_copy_operational_params(iscsi_conn_t *conn)
-{
- iscsi_session_t *session = conn->session;
- conn_rec_t *conn_rec = &session->nrec.conn[conn->id];
- node_rec_t *rec = &session->nrec;
-
- conn->hdrdgst_en = conn_rec->iscsi.HeaderDigest;
- conn->datadgst_en = conn_rec->iscsi.DataDigest;
-
- conn->max_recv_dlength =
- __padding(conn_rec->iscsi.MaxRecvDataSegmentLength);
- if (conn->max_recv_dlength < ISCSI_MIN_MAX_RECV_SEG_LEN ||
- conn->max_recv_dlength > ISCSI_MAX_MAX_RECV_SEG_LEN) {
- log_error("Invalid iscsi.MaxRecvDataSegmentLength. Must be "
- "within %u and %u. Setting to %u\n",
- ISCSI_MIN_MAX_RECV_SEG_LEN,
- ISCSI_MAX_MAX_RECV_SEG_LEN,
- DEF_INI_MAX_RECV_SEG_LEN);
- conn_rec->iscsi.MaxRecvDataSegmentLength =
- DEF_INI_MAX_RECV_SEG_LEN;
- conn->max_recv_dlength = DEF_INI_MAX_RECV_SEG_LEN;
- }
-
- /* zero indicates to use the target's value */
- conn->max_xmit_dlength =
- __padding(conn_rec->iscsi.MaxXmitDataSegmentLength);
- if (conn->max_xmit_dlength == 0)
- conn->max_xmit_dlength = ISCSI_DEF_MAX_RECV_SEG_LEN;
- if (conn->max_xmit_dlength < ISCSI_MIN_MAX_RECV_SEG_LEN ||
- conn->max_xmit_dlength > ISCSI_MAX_MAX_RECV_SEG_LEN) {
- log_error("Invalid iscsi.MaxXmitDataSegmentLength. Must be "
- "within %u and %u. Setting to %u\n",
- ISCSI_MIN_MAX_RECV_SEG_LEN,
- ISCSI_MAX_MAX_RECV_SEG_LEN,
- DEF_INI_MAX_RECV_SEG_LEN);
- conn_rec->iscsi.MaxXmitDataSegmentLength =
- DEF_INI_MAX_RECV_SEG_LEN;
- conn->max_xmit_dlength = DEF_INI_MAX_RECV_SEG_LEN;
- }
-
- /* session's operational parameters */
- session->initial_r2t_en = rec->session.iscsi.InitialR2T;
- session->imm_data_en = rec->session.iscsi.ImmediateData;
- session->first_burst = __padding(rec->session.iscsi.FirstBurstLength);
- /*
- * some targets like netapp fail the login if sent bad first_burst
- * and max_burst lens, even when immediate data=no and
- * initial r2t = Yes, so we always check the user values.
- */
- if (session->first_burst < ISCSI_MIN_FIRST_BURST_LEN ||
- session->first_burst > ISCSI_MAX_FIRST_BURST_LEN) {
- log_error("Invalid iscsi.FirstBurstLength of %u. Must be "
- "within %u and %u. Setting to %u\n",
- session->first_burst,
- ISCSI_MIN_FIRST_BURST_LEN,
- ISCSI_MAX_FIRST_BURST_LEN,
- DEF_INI_FIRST_BURST_LEN);
- rec->session.iscsi.FirstBurstLength = DEF_INI_FIRST_BURST_LEN;
- session->first_burst = DEF_INI_FIRST_BURST_LEN;
- }
-
- session->max_burst = __padding(rec->session.iscsi.MaxBurstLength);
- if (session->max_burst < ISCSI_MIN_MAX_BURST_LEN ||
- session->max_burst > ISCSI_MAX_MAX_BURST_LEN) {
- log_error("Invalid iscsi.MaxBurstLength of %u. Must be "
- "within %u and %u. Setting to %u\n",
- session->max_burst, ISCSI_MIN_MAX_BURST_LEN,
- ISCSI_MAX_MAX_BURST_LEN, DEF_INI_MAX_BURST_LEN);
- rec->session.iscsi.MaxBurstLength = DEF_INI_MAX_BURST_LEN;
- session->max_burst = DEF_INI_MAX_BURST_LEN;
- }
-
- if (session->first_burst > session->max_burst) {
- log_error("Invalid iscsi.FirstBurstLength of %u. Must be "
- "less than iscsi.MaxBurstLength. Setting to %u\n",
- session->first_burst, session->max_burst);
- rec->session.iscsi.FirstBurstLength = session->max_burst;
- session->first_burst = session->max_burst;
- }
-
- session->def_time2wait = rec->session.iscsi.DefaultTime2Wait;
- session->def_time2retain = rec->session.iscsi.DefaultTime2Retain;
- session->erl = rec->session.iscsi.ERL;
-}
-
static int
__session_conn_create(iscsi_session_t *session, int cid)
{
@@ -434,12 +245,12 @@ __session_conn_create(iscsi_session_t *s
conn_rec_t *conn_rec = &session->nrec.conn[cid];
int err;
- if (iscsi_conn_context_alloc(conn)) {
+ if (iscsi_ev_context_alloc(conn)) {
log_error("cannot allocate context_pool for conn cid %d", cid);
- return ENOMEM;
+ return ISCSI_ERR_NOMEM;
}
- conn->state = STATE_FREE;
+ conn->state = ISCSI_CONN_STATE_FREE;
conn->session = session;
/*
* TODO: we must export the socket_fd/transport_eph from sysfs
@@ -486,14 +297,15 @@ __session_conn_create(iscsi_session_t *s
conn->noop_out_interval = DEF_NOOP_OUT_INTERVAL;
}
- iscsi_copy_operational_params(conn);
+ iscsi_copy_operational_params(conn, &session->nrec.session.iscsi,
+ &conn_rec->iscsi);
/* TCP options */
conn->tcp_window_size = conn_rec->tcp.window_size;
/* FIXME: type_of_service */
/* resolve the string address to an IP address */
- err = setup_portal(conn, conn_rec);
+ err = iscsi_setup_portal(conn, conn_rec->address, conn_rec->port);
if (err)
return err;
return 0;
@@ -506,7 +318,7 @@ session_release(iscsi_session_t *session
if (session->target_alias)
free(session->target_alias);
- iscsi_conn_context_free(&session->conn[0]);
+ iscsi_ev_context_free(&session->conn[0]);
free(session);
}
@@ -524,11 +336,10 @@ __session_create(node_rec_t *rec, struct
log_debug(2, "Allocted session %p", session);
INIT_LIST_HEAD(&session->list);
- /* opened at daemon load time (iscsid.c) */
- session->ctrl_fd = control_fd;
session->t = t;
session->reopen_qtask.mgmt_ipc_fd = -1;
session->id = -1;
+ session->use_ipc = 1;
/* save node record. we might need it for redirection */
memcpy(&session->nrec, rec, sizeof(node_rec_t));
@@ -570,7 +381,7 @@ __session_create(node_rec_t *rec, struct
session->isid[5] = 0;
/* setup authentication variables for the session*/
- __setup_authentication(session, &rec->session.auth);
+ iscsi_setup_authentication(session, &rec->session.auth);
session->param_mask = ~0ULL;
if (!(t->caps & CAP_MULTI_R2T))
@@ -601,18 +412,18 @@ __session_create(node_rec_t *rec, struct
static void iscsi_flush_context_pool(struct iscsi_session *session)
{
- struct iscsi_conn_context *conn_context;
+ struct iscsi_ev_context *ev_context;
struct iscsi_conn *conn = &session->conn[0];
int i;
for (i = 0; i < CONTEXT_POOL_MAX; i++) {
- conn_context = conn->context_pool[i];
- if (!conn_context)
+ ev_context = conn->context_pool[i];
+ if (!ev_context)
continue;
- if (conn_context->allocated) {
+ if (ev_context->allocated) {
actor_delete(&(conn->context_pool[i]->actor));
- iscsi_conn_context_put(conn_context);
+ iscsi_ev_context_put(ev_context);
}
}
}
@@ -633,15 +444,16 @@ conn_delete_timers(iscsi_conn_t *conn)
actor_delete(&conn->nop_out_timer);
}
-static mgmt_ipc_err_e
+static int
session_conn_shutdown(iscsi_conn_t *conn, queue_task_t *qtask,
- mgmt_ipc_err_e err)
+ int err)
{
iscsi_session_t *session = conn->session;
log_debug(2, "disconnect conn");
/* this will check for a valid interconnect connection */
- conn->session->t->template->ep_disconnect(conn);
+ if (session->t->template->ep_disconnect)
+ session->t->template->ep_disconnect(conn);
if (session->id == -1)
goto cleanup;
@@ -649,15 +461,15 @@ session_conn_shutdown(iscsi_conn_t *conn
if (!iscsi_sysfs_session_has_leadconn(session->id))
goto cleanup;
- if (conn->state == STATE_IN_LOGIN ||
- conn->state == STATE_IN_LOGOUT ||
- conn->state == STATE_LOGGED_IN) {
+ if (conn->state == ISCSI_CONN_STATE_IN_LOGIN ||
+ conn->state == ISCSI_CONN_STATE_IN_LOGOUT ||
+ conn->state == ISCSI_CONN_STATE_LOGGED_IN) {
log_debug(2, "stop conn (conn state %d)", conn->state);
if (ipc->stop_conn(session->t->handle, session->id,
conn->id, STOP_CONN_TERM)) {
log_error("can't stop connection %d:%d (%d)",
session->id, conn->id, errno);
- return MGMT_IPC_ERR_INTERNAL;
+ return ISCSI_ERR_INTERNAL;
}
}
@@ -665,16 +477,17 @@ session_conn_shutdown(iscsi_conn_t *conn
if (ipc->destroy_conn(session->t->handle, session->id,
conn->id)) {
log_error("can not safely destroy connection %d", conn->id);
- return MGMT_IPC_ERR_INTERNAL;
+ return ISCSI_ERR_INTERNAL;
}
cleanup:
if (session->id != -1) {
log_debug(2, "kdestroy session %u", session->id);
+ session->r_stage = R_STAGE_SESSION_DESTOYED;
if (ipc->destroy_session(session->t->handle, session->id)) {
log_error("can not safely destroy session %d",
session->id);
- return MGMT_IPC_ERR_INTERNAL;
+ return ISCSI_ERR_INTERNAL;
}
}
@@ -688,7 +501,7 @@ cleanup:
mgmt_ipc_write_rsp(qtask, err);
conn_delete_timers(conn);
__session_destroy(session);
- return MGMT_IPC_OK;
+ return ISCSI_SUCCESS;
}
static void
@@ -709,17 +522,17 @@ queue_delayed_reopen(queue_task_t *qtask
static int iscsi_conn_connect(struct iscsi_conn *conn, queue_task_t *qtask)
{
- struct iscsi_conn_context *conn_context;
+ struct iscsi_ev_context *ev_context;
int rc;
- conn_context = iscsi_conn_context_get(conn, 0);
- if (!conn_context) {
+ ev_context = iscsi_ev_context_get(conn, 0);
+ if (!ev_context) {
/* while reopening the recv pool should be full */
log_error("BUG: __session_conn_reopen could not get conn "
"context for recv.");
return ENOMEM;
}
- conn_context->data = qtask;
+ ev_context->data = qtask;
rc = conn->session->t->template->ep_connect(conn, 1);
if (rc < 0 && errno != EINPROGRESS) {
@@ -732,11 +545,11 @@ static int iscsi_conn_connect(struct isc
log_error("cannot make a connection to %s:%s (%d,%d)",
conn->host, serv, rc, errno);
- iscsi_conn_context_put(conn_context);
+ iscsi_ev_context_put(ev_context);
return ENOTCONN;
}
- iscsi_sched_conn_context(conn_context, conn, 0, EV_CONN_POLL);
+ iscsi_sched_ev_context(ev_context, conn, 0, EV_CONN_POLL);
log_debug(3, "Setting login timer %p timeout %d", &conn->login_timer,
conn->login_timeout);
actor_timer(&conn->login_timer, conn->login_timeout * 1000,
@@ -759,11 +572,11 @@ __session_conn_reopen(iscsi_conn_t *conn
/* flush stale polls or errors queued */
iscsi_flush_context_pool(session);
conn_delete_timers(conn);
- conn->state = STATE_XPT_WAIT;
+ conn->state = ISCSI_CONN_STATE_XPT_WAIT;
conn->session->t->template->ep_disconnect(conn);
if (do_stop) {
- /* state: STATE_CLEANUP_WAIT */
+ /* state: ISCSI_CONN_STATE_CLEANUP_WAIT */
if (ipc->stop_conn(session->t->handle, session->id,
conn->id, do_stop)) {
log_error("can't stop connection %d:%d (%d)",
@@ -844,8 +657,16 @@ static int iscsi_retry_initial_login(str
return 1;
}
+static int iscsi_login_is_fatal_err(int err)
+{
+ if (err == ISCSI_ERR_LOGIN_AUTH_FAILED ||
+ err == ISCSI_ERR_FATAL_LOGIN)
+ return 1;
+ return 0;
+}
+
static void iscsi_login_eh(struct iscsi_conn *conn, struct queue_task *qtask,
- mgmt_ipc_err_e err)
+ int err)
{
struct iscsi_session *session = conn->session;
@@ -856,14 +677,14 @@ static void iscsi_login_eh(struct iscsi_
iscsi_flush_context_pool(conn->session);
switch (conn->state) {
- case STATE_XPT_WAIT:
+ case ISCSI_CONN_STATE_XPT_WAIT:
switch (session->r_stage) {
case R_STAGE_NO_CHANGE:
- log_debug(6, "login failed STATE_XPT_WAIT/"
+ log_debug(6, "login failed ISCSI_CONN_STATE_XPT_WAIT/"
"R_STAGE_NO_CHANGE");
/* timeout during initial connect.
* clean connection. write ipc rsp or retry */
- if (err == MGMT_IPC_ERR_FATAL_LOGIN_FAILURE ||
+ if (iscsi_login_is_fatal_err(err) ||
!iscsi_retry_initial_login(conn))
session_conn_shutdown(conn, qtask, err);
else {
@@ -875,18 +696,18 @@ static void iscsi_login_eh(struct iscsi_
}
break;
case R_STAGE_SESSION_REDIRECT:
- log_debug(6, "login failed STATE_XPT_WAIT/"
+ log_debug(6, "login failed ISCSI_CONN_STATE_XPT_WAIT/"
"R_STAGE_SESSION_REDIRECT");
/* timeout during initial redirect connect
* clean connection. write ipc rsp or retry */
- if (err == MGMT_IPC_ERR_FATAL_LOGIN_FAILURE ||
+ if (iscsi_login_is_fatal_err(err) ||
!iscsi_retry_initial_login(conn))
session_conn_shutdown(conn, qtask, err);
else
session_conn_reopen(conn, qtask, 0);
break;
case R_STAGE_SESSION_REOPEN:
- log_debug(6, "login failed STATE_XPT_WAIT/"
+ log_debug(6, "login failed ISCSI_CONN_STATE_XPT_WAIT/"
"R_STAGE_SESSION_REOPEN %d",
session->reopen_cnt);
/* timeout during reopen connect. try again */
@@ -900,11 +721,11 @@ static void iscsi_login_eh(struct iscsi_
}
break;
- case STATE_IN_LOGIN:
+ case ISCSI_CONN_STATE_IN_LOGIN:
switch (session->r_stage) {
case R_STAGE_NO_CHANGE:
case R_STAGE_SESSION_REDIRECT:
- log_debug(6, "login failed STATE_IN_LOGIN/"
+ log_debug(6, "login failed ISCSI_CONN_STATE_IN_LOGIN/"
"R_STAGE_NO_CHANGE %d",
session->reopen_cnt);
/*
@@ -912,7 +733,7 @@ static void iscsi_login_eh(struct iscsi_
* initial redirected connect. Clean connection
* and write rsp or retry.
*/
- if (err == MGMT_IPC_ERR_FATAL_LOGIN_FAILURE ||
+ if (iscsi_login_is_fatal_err(err) ||
!iscsi_retry_initial_login(conn))
session_conn_shutdown(conn, qtask, err);
else
@@ -920,14 +741,14 @@ static void iscsi_login_eh(struct iscsi_
STOP_CONN_RECOVER);
break;
case R_STAGE_SESSION_REOPEN:
- log_debug(6, "login failed STATE_IN_LOGIN/"
+ log_debug(6, "login failed ISCSI_CONN_STATE_IN_LOGIN/"
"R_STAGE_SESSION_REOPEN %d",
session->reopen_cnt);
session_conn_reopen(conn, qtask, STOP_CONN_RECOVER);
break;
case R_STAGE_SESSION_CLEANUP:
session_conn_shutdown(conn, qtask,
- MGMT_IPC_ERR_PDU_TIMEOUT);
+ ISCSI_ERR_PDU_TIMEOUT);
break;
default:
break;
@@ -951,23 +772,23 @@ __conn_error_handle(iscsi_session_t *ses
* just cleanup and return to the user.
*/
if (conn->logout_qtask) {
- session_conn_shutdown(conn, conn->logout_qtask, MGMT_IPC_OK);
+ session_conn_shutdown(conn, conn->logout_qtask, ISCSI_SUCCESS);
return;
}
switch (conn->state) {
- case STATE_IN_LOGOUT:
+ case ISCSI_CONN_STATE_IN_LOGOUT:
/* logout was from eh - fall down to cleanup */
- case STATE_LOGGED_IN:
+ case ISCSI_CONN_STATE_LOGGED_IN:
/* mark failed connection */
- conn->state = STATE_CLEANUP_WAIT;
+ conn->state = ISCSI_CONN_STATE_CLEANUP_WAIT;
if (session->erl > 0) {
/* check if we still have some logged in connections */
for (i=0; i<ISCSI_CONN_MAX; i++) {
- if (session->conn[i].state == STATE_LOGGED_IN) {
+ if (session->conn[i].state ==
+ ISCSI_CONN_STATE_LOGGED_IN)
break;
- }
}
if (i != ISCSI_CONN_MAX) {
/* FIXME: re-assign leading connection
@@ -979,30 +800,32 @@ __conn_error_handle(iscsi_session_t *ses
/* mark all connections as failed */
for (i=0; i<ISCSI_CONN_MAX; i++) {
- if (session->conn[i].state == STATE_LOGGED_IN)
- session->conn[i].state = STATE_CLEANUP_WAIT;
+ if (session->conn[i].state ==
+ ISCSI_CONN_STATE_LOGGED_IN)
+ session->conn[i].state =
+ ISCSI_CONN_STATE_CLEANUP_WAIT;
}
session->r_stage = R_STAGE_SESSION_REOPEN;
break;
- case STATE_IN_LOGIN:
+ case ISCSI_CONN_STATE_IN_LOGIN:
if (session->r_stage == R_STAGE_SESSION_REOPEN) {
queue_task_t *qtask;
- if (session->sync_qtask)
- qtask = session->sync_qtask;
+ if (session->notify_qtask)
+ qtask = session->notify_qtask;
else
qtask = &session->reopen_qtask;
- iscsi_login_eh(conn, qtask, MGMT_IPC_ERR_TRANS_FAILURE);
+ iscsi_login_eh(conn, qtask, ISCSI_ERR_TRANS);
return;
}
log_debug(1, "ignoring conn error in login. "
"let it timeout");
return;
- case STATE_XPT_WAIT:
+ case ISCSI_CONN_STATE_XPT_WAIT:
log_debug(1, "ignoring conn error in XPT_WAIT. "
"let connection fail on its own");
return;
- case STATE_CLEANUP_WAIT:
+ case ISCSI_CONN_STATE_CLEANUP_WAIT:
log_debug(1, "ignoring conn error in CLEANUP_WAIT. "
"let connection stop");
return;
@@ -1020,19 +843,20 @@ __conn_error_handle(iscsi_session_t *ses
static void session_conn_error(void *data)
{
- struct iscsi_conn_context *conn_context = data;
- enum iscsi_err error = *(enum iscsi_err *)conn_context->data;
- iscsi_conn_t *conn = conn_context->conn;
+ struct iscsi_ev_context *ev_context = data;
+ enum iscsi_err error = *(enum iscsi_err *)ev_context->data;
+ iscsi_conn_t *conn = ev_context->conn;
iscsi_session_t *session = conn->session;
- log_warning("Kernel reported iSCSI connection %d:%d error (%d) "
+ log_warning("Kernel reported iSCSI connection %d:%d error (%d - %s) "
"state (%d)", session->id, conn->id, error,
- conn->state);
- iscsi_conn_context_put(conn_context);
+ kern_err_code_to_string(error), conn->state);
+
+ iscsi_ev_context_put(ev_context);
switch (error) {
case ISCSI_ERR_INVALID_HOST:
- if (session_conn_shutdown(conn, NULL, MGMT_IPC_OK))
+ if (session_conn_shutdown(conn, NULL, ISCSI_SUCCESS))
log_error("BUG: Could not shutdown session.");
break;
default:
@@ -1046,14 +870,14 @@ static void iscsi_login_timedout(void *d
struct iscsi_conn *conn = qtask->conn;
switch (conn->state) {
- case STATE_XPT_WAIT:
- iscsi_login_eh(conn, qtask, MGMT_IPC_ERR_TRANS_TIMEOUT);
+ case ISCSI_CONN_STATE_XPT_WAIT:
+ iscsi_login_eh(conn, qtask, ISCSI_ERR_TRANS_TIMEOUT);
break;
- case STATE_IN_LOGIN:
- iscsi_login_eh(conn, qtask, MGMT_IPC_ERR_PDU_TIMEOUT);
+ case ISCSI_CONN_STATE_IN_LOGIN:
+ iscsi_login_eh(conn, qtask, ISCSI_ERR_PDU_TIMEOUT);
break;
default:
- iscsi_login_eh(conn, qtask, MGMT_IPC_ERR_INTERNAL);
+ iscsi_login_eh(conn, qtask, ISCSI_ERR_INTERNAL);
break;
}
}
@@ -1125,7 +949,7 @@ static void conn_send_nop_out(void *data
* we cannot start new request during logout and the logout timer
* will figure things out.
*/
- if (conn->state == STATE_IN_LOGOUT)
+ if (conn->state == ISCSI_CONN_STATE_IN_LOGOUT)
return;
__send_nopout(conn);
@@ -1136,17 +960,6 @@ static void conn_send_nop_out(void *data
&conn->nop_out_timer, conn->noop_out_timeout);
}
-static void
-print_param_value(enum iscsi_param param, void *value, int type)
-{
- log_debug(3, "set operational parameter %d to:", param);
-
- if (type == ISCSI_STRING)
- log_debug(3, "%s", value ? (char *)value : "NULL");
- else
- log_debug(3, "%u", *(uint32_t *)value);
-}
-
void free_initiator(void)
{
struct iscsi_transport *t;
@@ -1170,7 +983,7 @@ static void session_scan_host(struct isc
pid = iscsi_sysfs_scan_host(hostno, 1);
if (pid == 0) {
- mgmt_ipc_write_rsp(qtask, MGMT_IPC_OK);
+ mgmt_ipc_write_rsp(qtask, ISCSI_SUCCESS);
if (session)
iscsi_sysfs_for_each_device(
@@ -1185,306 +998,37 @@ static void session_scan_host(struct isc
free(qtask);
}
} else
- mgmt_ipc_write_rsp(qtask, MGMT_IPC_ERR_INTERNAL);
-}
-
-static int __iscsi_host_set_param(struct iscsi_transport *t,
- int host_no, int param, char *value,
- int type)
-{
- int rc;
-
- rc = ipc->set_host_param(t->handle, host_no, param, value, type);
- /* 2.6.20 and below returns EINVAL */
- if (rc && rc != -ENOSYS && rc != -EINVAL) {
- log_error("can't set operational parameter %d for "
- "host %d, retcode %d (%d)", param, host_no,
- rc, errno);
- return rc;
- }
- return 0;
-}
-
-mgmt_ipc_err_e iscsi_host_set_param(int host_no, int param, char *value)
-{
- struct iscsi_transport *t;
-
- t = iscsi_sysfs_get_transport_by_hba(host_no);
- if (!t)
- return MGMT_IPC_ERR_TRANS_FAILURE;
- if (__iscsi_host_set_param(t, host_no, param, value, ISCSI_STRING))
- return MGMT_IPC_ERR;
- return MGMT_IPC_OK;
+ mgmt_ipc_write_rsp(qtask, ISCSI_ERR_INTERNAL);
}
-#define MAX_SESSION_PARAMS 32
-#define MAX_HOST_PARAMS 3
-
static void
setup_full_feature_phase(iscsi_conn_t *conn)
{
iscsi_session_t *session = conn->session;
iscsi_login_context_t *c = &conn->login_context;
- int i, rc;
- uint32_t one = 1, zero = 0;
- struct hostparam {
- int param;
- int type;
- void *value;
- int set;
- } hosttbl[MAX_HOST_PARAMS] = {
- {
- .param = ISCSI_HOST_PARAM_NETDEV_NAME,
- .value = session->nrec.iface.netdev,
- .type = ISCSI_STRING,
- .set = 1,
- }, {
- .param = ISCSI_HOST_PARAM_HWADDRESS,
- .value = session->nrec.iface.hwaddress,
- .type = ISCSI_STRING,
- .set = 1,
- }, {
- .param = ISCSI_HOST_PARAM_INITIATOR_NAME,
- .value = session->initiator_name,
- .type = ISCSI_STRING,
- .set = 0,
- },
- };
- struct connparam {
- int param;
- int type;
- void *value;
- int conn_only;
- } conntbl[MAX_SESSION_PARAMS] = {
- {
- .param = ISCSI_PARAM_MAX_RECV_DLENGTH,
- .value = &conn->max_recv_dlength,
- .type = ISCSI_INT,
- .conn_only = 0,
- }, {
- .param = ISCSI_PARAM_MAX_XMIT_DLENGTH,
- .value = &conn->max_xmit_dlength,
- .type = ISCSI_INT,
- .conn_only = 0,
- }, {
- .param = ISCSI_PARAM_HDRDGST_EN,
- .value = &conn->hdrdgst_en,
- .type = ISCSI_INT,
- .conn_only = 0,
- }, {
- .param = ISCSI_PARAM_DATADGST_EN,
- .value = &conn->datadgst_en,
- .type = ISCSI_INT,
- .conn_only = 1,
- }, {
- .param = ISCSI_PARAM_INITIAL_R2T_EN,
- .value = &session->initial_r2t_en,
- .type = ISCSI_INT,
- .conn_only = 0,
- }, {
- .param = ISCSI_PARAM_MAX_R2T,
- .value = &one, /* FIXME: session->max_r2t */
- .type = ISCSI_INT,
- .conn_only = 0,
- }, {
- .param = ISCSI_PARAM_IMM_DATA_EN,
- .value = &session->imm_data_en,
- .type = ISCSI_INT,
- .conn_only = 0,
- }, {
- .param = ISCSI_PARAM_FIRST_BURST,
- .value = &session->first_burst,
- .type = ISCSI_INT,
- .conn_only = 0,
- }, {
- .param = ISCSI_PARAM_MAX_BURST,
- .value = &session->max_burst,
- .type = ISCSI_INT,
- .conn_only = 0,
- }, {
- .param = ISCSI_PARAM_PDU_INORDER_EN,
- .value = &session->pdu_inorder_en,
- .type = ISCSI_INT,
- .conn_only = 0,
- }, {
- .param =ISCSI_PARAM_DATASEQ_INORDER_EN,
- .value = &session->dataseq_inorder_en,
- .type = ISCSI_INT,
- .conn_only = 0,
- }, {
- .param = ISCSI_PARAM_ERL,
- .value = &zero, /* FIXME: session->erl */
- .type = ISCSI_INT,
- .conn_only = 0,
- }, {
- .param = ISCSI_PARAM_IFMARKER_EN,
- .value = &zero,/* FIXME: session->ifmarker_en */
- .type = ISCSI_INT,
- .conn_only = 0,
- }, {
- .param = ISCSI_PARAM_OFMARKER_EN,
- .value = &zero,/* FIXME: session->ofmarker_en */
- .type = ISCSI_INT,
- .conn_only = 0,
- }, {
- .param = ISCSI_PARAM_EXP_STATSN,
- .value = &conn->exp_statsn,
- .type = ISCSI_INT,
- .conn_only = 1,
- }, {
- .param = ISCSI_PARAM_TARGET_NAME,
- .conn_only = 0,
- .type = ISCSI_STRING,
- .value = session->target_name,
- }, {
- .param = ISCSI_PARAM_TPGT,
- .value = &session->portal_group_tag,
- .type = ISCSI_INT,
- .conn_only = 0,
- }, {
- .param = ISCSI_PARAM_PERSISTENT_ADDRESS,
- .value = session->nrec.conn[conn->id].address,
- .type = ISCSI_STRING,
- .conn_only = 1,
- }, {
- .param = ISCSI_PARAM_PERSISTENT_PORT,
- .value = &session->nrec.conn[conn->id].port,
- .type = ISCSI_INT,
- .conn_only = 1,
- }, {
- .param = ISCSI_PARAM_SESS_RECOVERY_TMO,
- .value = &session->replacement_timeout,
- .type = ISCSI_INT,
- .conn_only = 0,
- }, {
- .param = ISCSI_PARAM_USERNAME,
- .value = session->username,
- .type = ISCSI_STRING,
- .conn_only = 0,
- }, {
- .param = ISCSI_PARAM_USERNAME_IN,
- .value = session->username_in,
- .type = ISCSI_STRING,
- .conn_only = 0,
- }, {
- .param = ISCSI_PARAM_PASSWORD,
- .value = session->password,
- .type = ISCSI_STRING,
- .conn_only = 0,
- }, {
- .param = ISCSI_PARAM_PASSWORD_IN,
- .value = session->password_in,
- .type = ISCSI_STRING,
- .conn_only = 0,
- }, {
- .param = ISCSI_PARAM_FAST_ABORT,
- .value = &session->fast_abort,
- .type = ISCSI_INT,
- .conn_only = 0,
- }, {
- .param = ISCSI_PARAM_ABORT_TMO,
- .value = &session->abort_timeout,
- .type = ISCSI_INT,
- .conn_only = 0,
- }, {
- .param = ISCSI_PARAM_LU_RESET_TMO,
- .value = &session->lu_reset_timeout,
- .type = ISCSI_INT,
- .conn_only = 0,
- }, {
- .param = ISCSI_PARAM_TGT_RESET_TMO,
- .value = &session->tgt_reset_timeout,
- .type = ISCSI_INT,
- .conn_only = 0,
- }, {
- .param = ISCSI_PARAM_PING_TMO,
- .value = &conn->noop_out_timeout,
- .type = ISCSI_INT,
- .conn_only = 1,
- }, {
- .param = ISCSI_PARAM_RECV_TMO,
- .value = &conn->noop_out_interval,
- .type = ISCSI_INT,
- .conn_only = 1,
- }, {
- .param = ISCSI_PARAM_IFACE_NAME,
- .value = session->nrec.iface.name,
- .type = ISCSI_STRING,
- }, {
- .param = ISCSI_PARAM_INITIATOR_NAME,
- .value = session->initiator_name,
- .type = ISCSI_STRING,
- },
- };
+ int rc;
actor_delete(&conn->login_timer);
- /* Entered full-feature phase! */
- for (i = 0; i < MAX_SESSION_PARAMS; i++) {
- if (conn->id != 0 && !conntbl[i].conn_only)
- continue;
-
- if (!(session->param_mask & (1ULL << conntbl[i].param)))
- continue;
-
- rc = ipc->set_param(session->t->handle, session->id,
- conn->id, conntbl[i].param, conntbl[i].value,
- conntbl[i].type);
- if (rc && rc != -ENOSYS) {
- log_error("can't set operational parameter %d for "
- "connection %d:%d, retcode %d (%d)",
- conntbl[i].param, session->id, conn->id,
- rc, errno);
-
- iscsi_login_eh(conn, c->qtask,
- MGMT_IPC_ERR_LOGIN_FAILURE);
- return;
- }
- if (rc == -ENOSYS) {
- switch (conntbl[i].param) {
- case ISCSI_PARAM_PING_TMO:
- /*
- * older kernels may not support nops
- * in kernel
- */
- conn->userspace_nop = 1;
- break;
- case ISCSI_PARAM_INITIATOR_NAME:
- /* use host level one instead */
- hosttbl[ISCSI_HOST_PARAM_INITIATOR_NAME].set = 1;
- break;
- }
- }
-
- print_param_value(conntbl[i].param, conntbl[i].value,
- conntbl[i].type);
+ if (iscsi_session_set_params(conn)) {
+ iscsi_login_eh(conn, c->qtask, ISCSI_ERR_LOGIN);
+ return;
}
- for (i = 0; i < MAX_HOST_PARAMS; i++) {
- if (!hosttbl[i].set)
- continue;
-
- if (__iscsi_host_set_param(session->t, session->hostno,
- hosttbl[i].param, hosttbl[i].value,
- hosttbl[i].type)) {
- iscsi_login_eh(conn, c->qtask,
- MGMT_IPC_ERR_LOGIN_FAILURE);
- return;
- }
-
- print_param_value(hosttbl[i].param, hosttbl[i].value,
- hosttbl[i].type);
+ if (iscsi_host_set_params(session)) {
+ iscsi_login_eh(conn, c->qtask, ISCSI_ERR_LOGIN);
+ return;
}
if (ipc->start_conn(session->t->handle, session->id, conn->id,
&rc) || rc) {
log_error("can't start connection %d:%d retcode %d (%d)",
session->id, conn->id, rc, errno);
- iscsi_login_eh(conn, c->qtask, MGMT_IPC_ERR_INTERNAL);
+ iscsi_login_eh(conn, c->qtask, ISCSI_ERR_INTERNAL);
return;
}
- conn->state = STATE_LOGGED_IN;
+ conn->state = ISCSI_CONN_STATE_LOGGED_IN;
if (session->r_stage == R_STAGE_NO_CHANGE ||
session->r_stage == R_STAGE_SESSION_REDIRECT) {
/*
@@ -1501,10 +1045,10 @@ setup_full_feature_phase(iscsi_conn_t *c
session->nrec.conn[conn->id].port,
session->nrec.iface.name);
} else {
- session->sync_qtask = NULL;
+ session->notify_qtask = NULL;
session_online_devs(session->hostno, session->id);
- mgmt_ipc_write_rsp(c->qtask, MGMT_IPC_OK);
+ mgmt_ipc_write_rsp(c->qtask, ISCSI_SUCCESS);
log_warning("connection%d:%d is operational after recovery "
"(%d attempts)", session->id, conn->id,
session->reopen_cnt);
@@ -1527,12 +1071,12 @@ setup_full_feature_phase(iscsi_conn_t *c
static void iscsi_logout_timedout(void *data)
{
- struct iscsi_conn_context *conn_context = data;
- struct iscsi_conn *conn = conn_context->conn;
+ struct iscsi_ev_context *ev_context = data;
+ struct iscsi_conn *conn = ev_context->conn;
- iscsi_conn_context_put(conn_context);
+ iscsi_ev_context_put(ev_context);
/*
- * assume we were in STATE_IN_LOGOUT or there
+ * assume we were in ISCSI_CONN_STATE_IN_LOGOUT or there
* was some nasty error
*/
log_debug(3, "logout timeout, dropping conn...\n");
@@ -1542,9 +1086,9 @@ static void iscsi_logout_timedout(void *
static int iscsi_send_logout(iscsi_conn_t *conn)
{
struct iscsi_logout hdr;
- struct iscsi_conn_context *conn_context;
+ struct iscsi_ev_context *ev_context;
- if (conn->state != STATE_LOGGED_IN)
+ if (conn->state != ISCSI_CONN_STATE_LOGGED_IN)
return EINVAL;
memset(&hdr, 0, sizeof(struct iscsi_logout));
@@ -1556,14 +1100,14 @@ static int iscsi_send_logout(iscsi_conn_
if (!iscsi_io_send_pdu(conn, (struct iscsi_hdr*)&hdr,
ISCSI_DIGEST_NONE, NULL, ISCSI_DIGEST_NONE, 0))
return EIO;
- conn->state = STATE_IN_LOGOUT;
+ conn->state = ISCSI_CONN_STATE_IN_LOGOUT;
- conn_context = iscsi_conn_context_get(conn, 0);
- if (!conn_context)
+ ev_context = iscsi_ev_context_get(conn, 0);
+ if (!ev_context)
/* unbounded logout */
log_warning("Could not allocate conn context for logout.");
else {
- iscsi_sched_conn_context(conn_context, conn,
+ iscsi_sched_ev_context(ev_context, conn,
conn->logout_timeout,
EV_CONN_LOGOUT_TIMER);
log_debug(3, "logout timeout timer %u\n",
@@ -1575,16 +1119,18 @@ static int iscsi_send_logout(iscsi_conn_
static void iscsi_stop(void *data)
{
- struct iscsi_conn_context *conn_context = data;
- struct iscsi_conn *conn = conn_context->conn;
+ struct iscsi_ev_context *ev_context = data;
+ struct iscsi_conn *conn = ev_context->conn;
int rc = 0;
- iscsi_conn_context_put(conn_context);
+ iscsi_ev_context_put(ev_context);
- if (!iscsi_send_logout(conn))
- return;
+ if (!(conn->session->t->caps & CAP_LOGIN_OFFLOAD)) {
+ if (!iscsi_send_logout(conn))
+ return;
+ }
- rc = session_conn_shutdown(conn, conn->logout_qtask, MGMT_IPC_OK);
+ rc = session_conn_shutdown(conn, conn->logout_qtask, ISCSI_SUCCESS);
if (rc)
log_error("BUG: Could not shutdown session.");
}
@@ -1683,6 +1229,7 @@ static void iscsi_recv_login_rsp(struct
{
struct iscsi_session *session = conn->session;
iscsi_login_context_t *c = &conn->login_context;
+ int err = ISCSI_ERR_FATAL_LOGIN;
if (iscsi_login_rsp(session, c)) {
log_debug(1, "login_rsp ret (%d)", c->ret);
@@ -1703,6 +1250,9 @@ static void iscsi_recv_login_rsp(struct
switch (__check_iscsi_status_class(session, conn->id,
c->status_class,
c->status_detail)) {
+ case CONN_LOGIN_AUTH_FAILED:
+ err = ISCSI_ERR_LOGIN_AUTH_FAILED;
+ goto failed;
case CONN_LOGIN_FAILED:
goto failed;
case CONN_LOGIN_IMM_REDIRECT_RETRY:
@@ -1718,10 +1268,9 @@ static void iscsi_recv_login_rsp(struct
if (conn->current_stage != ISCSI_FULL_FEATURE_PHASE) {
/* more nego. needed! */
- conn->state = STATE_IN_LOGIN;
+ conn->state = ISCSI_CONN_STATE_IN_LOGIN;
if (iscsi_login_req(session, c)) {
- iscsi_login_eh(conn, c->qtask,
- MGMT_IPC_ERR_LOGIN_FAILURE);
+ iscsi_login_eh(conn, c->qtask, ISCSI_ERR_LOGIN);
return;
}
} else
@@ -1730,36 +1279,35 @@ static void iscsi_recv_login_rsp(struct
return;
retry:
/* retry if not initial login or initial login has not timed out */
- iscsi_login_eh(conn, c->qtask, MGMT_IPC_ERR_LOGIN_FAILURE);
+ iscsi_login_eh(conn, c->qtask, ISCSI_ERR_LOGIN);
return;
failed:
/* force failure if initial login */
session->reopen_cnt = session->nrec.session.initial_login_retry_max;
- iscsi_login_eh(conn, c->qtask, MGMT_IPC_ERR_FATAL_LOGIN_FAILURE);
+ iscsi_login_eh(conn, c->qtask, err);
return;
}
static void session_conn_recv_pdu(void *data)
{
- struct iscsi_conn_context *conn_context = data;
- iscsi_conn_t *conn = conn_context->conn;
+ struct iscsi_ev_context *ev_context = data;
+ iscsi_conn_t *conn = ev_context->conn;
struct iscsi_hdr hdr;
- conn->recv_context = conn_context;
+ conn->recv_context = ev_context;
switch (conn->state) {
- case STATE_IN_LOGIN:
+ case ISCSI_CONN_STATE_IN_LOGIN:
iscsi_recv_login_rsp(conn);
break;
- case STATE_LOGGED_IN:
- case STATE_IN_LOGOUT:
- case STATE_LOGOUT_REQUESTED:
+ case ISCSI_CONN_STATE_LOGGED_IN:
+ case ISCSI_CONN_STATE_IN_LOGOUT:
+ case ISCSI_CONN_STATE_LOGOUT_REQUESTED:
/* read incoming PDU */
- if (!iscsi_io_recv_pdu(conn, &hdr, ISCSI_DIGEST_NONE,
- conn->data, ISCSI_DEF_MAX_RECV_SEG_LEN,
- ISCSI_DIGEST_NONE, 0)) {
+ if (iscsi_io_recv_pdu(conn, &hdr, ISCSI_DIGEST_NONE,
+ conn->data, ISCSI_DEF_MAX_RECV_SEG_LEN,
+ ISCSI_DIGEST_NONE, 0) < 0)
return;
- }
switch (hdr.opcode & ISCSI_OPCODE_MASK) {
case ISCSI_OP_NOOP_IN:
@@ -1776,18 +1324,18 @@ static void session_conn_recv_pdu(void *
break;
}
break;
- case STATE_XPT_WAIT:
- iscsi_conn_context_put(conn_context);
+ case ISCSI_CONN_STATE_XPT_WAIT:
+ iscsi_ev_context_put(ev_context);
log_debug(1, "ignoring incoming PDU in XPT_WAIT. "
"let connection re-establish or fail");
break;
- case STATE_CLEANUP_WAIT:
- iscsi_conn_context_put(conn_context);
+ case ISCSI_CONN_STATE_CLEANUP_WAIT:
+ iscsi_ev_context_put(ev_context);
log_debug(1, "ignoring incoming PDU in XPT_WAIT. "
"let connection cleanup");
break;
default:
- iscsi_conn_context_put(conn_context);
+ iscsi_ev_context_put(ev_context);
log_error("Invalid state. Dropping PDU.\n");
}
}
@@ -1908,35 +1456,72 @@ retry_create:
return err;
}
+static void setup_offload_login_phase(iscsi_conn_t *conn)
+{
+ iscsi_session_t *session = conn->session;
+ iscsi_login_context_t *c = &conn->login_context;
+ int rc;
+
+ actor_delete(&conn->login_timer);
+
+ if (iscsi_session_set_params(conn)) {
+ iscsi_login_eh(conn, c->qtask, ISCSI_ERR_LOGIN);
+ return;
+ }
+
+ if (iscsi_host_set_params(session)) {
+ iscsi_login_eh(conn, c->qtask, ISCSI_ERR_LOGIN);
+ return;
+ }
+
+ conn->state = ISCSI_CONN_STATE_IN_LOGIN;
+ if (ipc->start_conn(session->t->handle, session->id, conn->id,
+ &rc) || rc) {
+ if (rc == -EEXIST) {
+ log_error("Session already exists.");
+ session_conn_shutdown(conn, c->qtask,
+ ISCSI_ERR_SESS_EXISTS);
+ } else {
+ log_error("can't start connection %d:%d retcode (%d)",
+ session->id, conn->id, rc);
+ iscsi_login_eh(conn, c->qtask, ISCSI_ERR_INTERNAL);
+ }
+ return;
+ }
+
+ session->notify_qtask = c->qtask;
+}
+
+
static void session_conn_poll(void *data)
{
- struct iscsi_conn_context *conn_context = data;
- iscsi_conn_t *conn = conn_context->conn;
+ struct iscsi_ev_context *ev_context = data;
+ iscsi_conn_t *conn = ev_context->conn;
struct iscsi_session *session = conn->session;
- mgmt_ipc_err_e err = MGMT_IPC_OK;
- queue_task_t *qtask = conn_context->data;
+ int err = ISCSI_SUCCESS;
+ queue_task_t *qtask = ev_context->data;
iscsi_login_context_t *c = &conn->login_context;
int rc;
- iscsi_conn_context_put(conn_context);
+ iscsi_ev_context_put(ev_context);
- if (conn->state != STATE_XPT_WAIT)
+ if (conn->state != ISCSI_CONN_STATE_XPT_WAIT)
return;
rc = session->t->template->ep_poll(conn, 1);
if (rc == 0) {
log_debug(4, "poll not connected %d", rc);
/* timedout: Poll again. */
- conn_context = iscsi_conn_context_get(conn, 0);
- if (!conn_context) {
+ ev_context = iscsi_ev_context_get(conn, 0);
+ if (!ev_context) {
/* while polling the recv pool should be full */
log_error("BUG: session_conn_poll could not get conn "
"context.");
- iscsi_login_eh(conn, qtask, MGMT_IPC_ERR_INTERNAL);
+ iscsi_login_eh(conn, qtask, ISCSI_ERR_INTERNAL);
return;
}
- conn_context->data = qtask;
- iscsi_sched_conn_context(conn_context, conn, 0, EV_CONN_POLL);
+ ev_context->data = qtask;
+ iscsi_sched_ev_context(ev_context, conn, 0, EV_CONN_POLL);
} else if (rc > 0) {
/* connected! */
memset(c, 0, sizeof(iscsi_login_context_t));
@@ -1945,26 +1530,26 @@ static void session_conn_poll(void *data
if (session->id == -1) {
if (conn->id == 0 && session_ipc_create(session)) {
log_error("Can't create session.");
- err = MGMT_IPC_ERR_INTERNAL;
+ err = ISCSI_ERR_INTERNAL;
goto cleanup;
}
log_debug(3, "created new iSCSI session sid %d host "
"no %u", session->id, session->hostno);
- if (ipc->create_conn(session->t->handle,
- session->id, conn->id, &conn->id)) {
+ err = ipc->create_conn(session->t->handle,
+ session->id, conn->id, &conn->id);
+ if (err) {
log_error("Can't create connection.");
- err = MGMT_IPC_ERR_INTERNAL;
+ err = ISCSI_ERR_INTERNAL;
goto cleanup;
}
log_debug(3, "created new iSCSI connection "
"%d:%d", session->id, conn->id);
}
- iscsi_copy_operational_params(conn);
-
- if (session->t->template->create_conn)
- session->t->template->create_conn(conn);
+ iscsi_copy_operational_params(conn,
+ &session->nrec.session.iscsi,
+ &session->nrec.conn[conn->id].iscsi);
/*
* TODO: use the iface number or some other value
* so this will be persistent
@@ -1977,7 +1562,7 @@ static void session_conn_poll(void *data
log_error("can't bind conn %d:%d to session %d, "
"retcode %d (%d)", session->id, conn->id,
session->id, rc, errno);
- iscsi_login_eh(conn, qtask, MGMT_IPC_ERR_LOGIN_FAILURE);
+ iscsi_login_eh(conn, qtask, ISCSI_ERR_LOGIN);
return;
}
log_debug(3, "bound iSCSI connection %d:%d to session %d",
@@ -1990,14 +1575,19 @@ static void session_conn_poll(void *data
conn->exp_statsn = iscsi_sysfs_get_exp_statsn(session->id);
+ if (session->t->caps & CAP_LOGIN_OFFLOAD) {
+ setup_offload_login_phase(conn);
+ return;
+ }
+
if (iscsi_login_begin(session, c)) {
- iscsi_login_eh(conn, qtask, MGMT_IPC_ERR_LOGIN_FAILURE);
+ iscsi_login_eh(conn, qtask, ISCSI_ERR_LOGIN);
return;
}
- conn->state = STATE_IN_LOGIN;
+ conn->state = ISCSI_CONN_STATE_IN_LOGIN;
if (iscsi_login_req(session, c)) {
- iscsi_login_eh(conn, qtask, MGMT_IPC_ERR_LOGIN_FAILURE);
+ iscsi_login_eh(conn, qtask, ISCSI_ERR_LOGIN);
return;
}
} else {
@@ -2011,70 +1601,126 @@ cleanup:
session_conn_shutdown(conn, qtask, err);
}
-void iscsi_sched_conn_context(struct iscsi_conn_context *conn_context,
- struct iscsi_conn *conn, unsigned long tmo,
- int event)
+static void session_conn_process_login(void *data)
+{
+ struct iscsi_ev_context *ev_context = data;
+ enum iscsi_conn_state state = *(enum iscsi_conn_state *)
+ ev_context->data;
+ struct iscsi_conn *conn = ev_context->conn;
+ struct iscsi_session *session = conn->session;
+ iscsi_login_context_t *c = &conn->login_context;
+ queue_task_t *qtask;
+
+ iscsi_ev_context_put(ev_context);
+ if (!(session->t->caps & CAP_LOGIN_OFFLOAD))
+ return;
+
+ if (state == ISCSI_CONN_STATE_FREE)
+ goto failed_login;
+
+ conn->state = ISCSI_CONN_STATE_LOGGED_IN;
+ /*
+ * ok we were in_login and now we got the notification that we are
+ * logged in
+ */
+ log_debug(3, "session created sid %u host no %d", session->id,
+ session->hostno);
+
+ if (session->r_stage == R_STAGE_NO_CHANGE ||
+ session->r_stage == R_STAGE_SESSION_REDIRECT) {
+ /*
+ * scan host is one-time deal. We
+ * don't want to re-scan it on recovery.
+ */
+ session_scan_host(session, session->hostno,
+ c->qtask);
+ session->notify_qtask = NULL;
+
+ log_warning("Connection%d:%d to [target: %s, portal: %s,%d] "
+ "through [iface: %s] is operational now",
+ session->id, conn->id, session->nrec.name,
+ session->nrec.conn[conn->id].address,
+ session->nrec.conn[conn->id].port,
+ session->nrec.iface.name);
+ } else {
+ session->notify_qtask = NULL;
+ mgmt_ipc_write_rsp(c->qtask, ISCSI_SUCCESS);
+ }
+
+ /*
+ * reset ERL=0 reopen counter
+ */
+ session->reopen_cnt = 0;
+ session->r_stage = R_STAGE_NO_CHANGE;
+
+ return;
+
+failed_login:
+ qtask = session->notify_qtask;
+ session->notify_qtask = NULL;
+ mgmt_ipc_write_rsp(qtask, ISCSI_ERR_LOGIN);
+ if (ipc->destroy_conn(session->t->handle, session->id, conn->id))
+ log_error("can not safely destroy connection %d", conn->id);
+ if (ipc->destroy_session(session->t->handle, session->id))
+ log_error("can not safely destroy session %d", session->id);
+ __session_destroy(session);
+
+}
+
+static int iscsi_sched_ev_context(struct iscsi_ev_context *ev_context,
+ struct iscsi_conn *conn, unsigned long tmo,
+ int event)
{
enum iscsi_err error;
log_debug(7, "sched conn context %p event %d, tmo %lu",
- &conn_context->actor, event, tmo);
+ &ev_context->actor, event, tmo);
- conn_context->conn = conn;
+ ev_context->conn = conn;
switch (event) {
case EV_CONN_RECV_PDU:
- actor_new(&conn_context->actor, session_conn_recv_pdu,
- conn_context);
- actor_schedule(&conn_context->actor);
+ actor_new(&ev_context->actor, session_conn_recv_pdu,
+ ev_context);
+ actor_schedule(&ev_context->actor);
break;
case EV_CONN_ERROR:
- error = *(enum iscsi_err *)conn_context->data;
+ error = *(enum iscsi_err *)ev_context->data;
- actor_new(&conn_context->actor, session_conn_error,
- conn_context);
+ actor_new(&ev_context->actor, session_conn_error,
+ ev_context);
/*
* We handle invalid host, by killing the session.
* It must go at the head of the queue, so we do not
* initiate error handling or logout or some other op.
*/
if (error == ISCSI_ERR_INVALID_HOST)
- actor_schedule_head(&conn_context->actor);
+ actor_schedule_head(&ev_context->actor);
else
- actor_schedule(&conn_context->actor);
+ actor_schedule(&ev_context->actor);
+ break;
+ case EV_CONN_LOGIN:
+ actor_new(&ev_context->actor, session_conn_process_login,
+ ev_context);
+ actor_schedule(&ev_context->actor);
break;
case EV_CONN_POLL:
- actor_new(&conn_context->actor, session_conn_poll,
- conn_context);
- actor_schedule(&conn_context->actor);
+ actor_new(&ev_context->actor, session_conn_poll,
+ ev_context);
+ actor_schedule(&ev_context->actor);
break;
case EV_CONN_LOGOUT_TIMER:
- actor_timer(&conn_context->actor, tmo * 1000,
- iscsi_logout_timedout, conn_context);
+ actor_timer(&ev_context->actor, tmo * 1000,
+ iscsi_logout_timedout, ev_context);
break;
case EV_CONN_STOP:
- actor_new(&conn_context->actor, iscsi_stop,
- conn_context);
- actor_schedule(&conn_context->actor);
+ actor_new(&ev_context->actor, iscsi_stop,
+ ev_context);
+ actor_schedule(&ev_context->actor);
break;
default:
log_error("Invalid event type %d.", event);
- return;
}
-}
-
-iscsi_session_t*
-session_find_by_sid(int sid)
-{
- struct iscsi_transport *t;
- iscsi_session_t *session;
-
- list_for_each_entry(t, &transports, list) {
- list_for_each_entry(session, &t->sessions, list) {
- if (session->id == sid)
- return session;
- }
- }
- return NULL;
+ return 0;
}
static iscsi_session_t* session_find_by_rec(node_rec_t *rec)
@@ -2087,7 +1733,8 @@ static iscsi_session_t* session_find_by_
if (__iscsi_match_session(rec, session->nrec.name,
session->nrec.conn[0].address,
session->nrec.conn[0].port,
- &session->nrec.iface))
+ &session->nrec.iface,
+ MATCH_ANY_SID))
return session;
}
}
@@ -2111,65 +1758,24 @@ static int session_is_running(node_rec_t
return 0;
}
-static int iface_set_param(struct iscsi_transport *t, struct iface_rec *iface,
- struct iscsi_session *session)
-{
- int rc = 0;
-
- log_debug(3, "setting iface %s, dev %s, set ip %s, hw %s, "
- "transport %s.\n",
- iface->name, iface->netdev, iface->ipaddress,
- iface->hwaddress, iface->transport_name);
-
- if (!t->template->set_host_ip)
- return 0;
-
- /* if we need to set the ip addr then set all the iface net settings */
- if (!iface_is_bound_by_ipaddr(iface)) {
- log_warning("Please set the iface.ipaddress for iface %s, "
- "then retry the login command.\n", iface->name);
- return EINVAL;
- }
-
- rc = __iscsi_host_set_param(t, session->hostno,
- ISCSI_HOST_PARAM_IPADDRESS,
- iface->ipaddress, ISCSI_STRING);
- if (rc)
- return rc;
-
- if (iface_is_bound_by_netdev(iface)) {
- rc = __iscsi_host_set_param(t, session->hostno,
- ISCSI_HOST_PARAM_NETDEV_NAME,
- iface->netdev, ISCSI_STRING);
- if (rc)
- return rc;
- }
-
- if (iface_is_bound_by_hwaddr(iface)) {
- rc = __iscsi_host_set_param(t, session->hostno,
- ISCSI_HOST_PARAM_HWADDRESS,
- iface->hwaddress, ISCSI_STRING);
- if (rc)
- return rc;
- }
- return 0;
-}
-
int
session_login_task(node_rec_t *rec, queue_task_t *qtask)
{
iscsi_session_t *session;
iscsi_conn_t *conn;
struct iscsi_transport *t;
+ int rc;
- if (session_is_running(rec))
- return MGMT_IPC_ERR_EXISTS;
+ if (session_is_running(rec)) {
+ if (rec->session.multiple)
+ log_debug(2, "Adding a copy of an existing session");
+ else
+ return ISCSI_ERR_SESS_EXISTS;
+ }
t = iscsi_sysfs_get_transport_by_name(rec->iface.transport_name);
if (!t)
- return MGMT_IPC_ERR_TRANS_NOT_FOUND;
- if (set_transport_template(t))
- return MGMT_IPC_ERR_TRANS_NOT_FOUND;
+ return ISCSI_ERR_TRANS_NOT_FOUND;
if ((!(t->caps & CAP_RECOVERY_L0) &&
rec->session.iscsi.ERL != 0) ||
@@ -2222,27 +1828,22 @@ session_login_task(node_rec_t *rec, queu
session = __session_create(rec, t);
if (!session)
- return MGMT_IPC_ERR_LOGIN_FAILURE;
+ return ISCSI_ERR_LOGIN;
/* FIXME: login all connections! marked as "automatic" */
/* create leading connection */
- if (__session_conn_create(session, 0)) {
+ rc = __session_conn_create(session, 0);
+ if (rc) {
__session_destroy(session);
- return MGMT_IPC_ERR_LOGIN_FAILURE;
+ return rc;
}
conn = &session->conn[0];
qtask->conn = conn;
- if (iface_set_param(t, &rec->iface, session)) {
+ if (iscsi_host_set_net_params(&rec->iface, session)) {
__session_destroy(session);
- return MGMT_IPC_ERR_LOGIN_FAILURE;
- }
-
- conn->state = STATE_XPT_WAIT;
- if (iscsi_conn_connect(conn, qtask)) {
- __session_destroy(session);
- return MGMT_IPC_ERR_TRANS_FAILURE;
+ return ISCSI_ERR_LOGIN;
}
if (gettimeofday(&conn->initial_connect_time, NULL))
@@ -2250,26 +1851,37 @@ session_login_task(node_rec_t *rec, queu
"login errors iscsid may give up the initial "
"login early. You should manually login.");
+ conn->state = ISCSI_CONN_STATE_XPT_WAIT;
qtask->rsp.command = MGMT_IPC_SESSION_LOGIN;
- qtask->rsp.err = MGMT_IPC_OK;
- return MGMT_IPC_OK;
+ qtask->rsp.err = ISCSI_SUCCESS;
+
+ if (iscsi_conn_connect(conn, qtask)) {
+ log_debug(4, "Initial connect failed. Waiting %u seconds "
+ "before trying to reconnect.\n",
+ ISCSI_CONN_ERR_REOPEN_DELAY);
+ queue_delayed_reopen(qtask, ISCSI_CONN_ERR_REOPEN_DELAY);
+ }
+
+ return ISCSI_SUCCESS;
}
static int
sync_conn(iscsi_session_t *session, uint32_t cid)
{
iscsi_conn_t *conn;
+ int rc;
- if (__session_conn_create(session, cid))
- return ENOMEM;
+ rc = __session_conn_create(session, cid);
+ if (rc)
+ return rc;
conn = &session->conn[cid];
/* TODO: must export via sysfs so we can pick this up */
- conn->state = STATE_CLEANUP_WAIT;
+ conn->state = ISCSI_CONN_STATE_CLEANUP_WAIT;
return 0;
}
-mgmt_ipc_err_e
+int
iscsi_sync_session(node_rec_t *rec, queue_task_t *qtask, uint32_t sid)
{
iscsi_session_t *session;
@@ -2278,38 +1890,32 @@ iscsi_sync_session(node_rec_t *rec, queu
t = iscsi_sysfs_get_transport_by_name(rec->iface.transport_name);
if (!t)
- return MGMT_IPC_ERR_TRANS_NOT_FOUND;
- if (set_transport_template(t))
- return MGMT_IPC_ERR_TRANS_NOT_FOUND;
+ return ISCSI_ERR_TRANS_NOT_FOUND;
session = __session_create(rec, t);
if (!session)
- return MGMT_IPC_ERR_LOGIN_FAILURE;
+ return ISCSI_ERR_LOGIN;
session->id = sid;
session->hostno = iscsi_sysfs_get_host_no_from_sid(sid, &err);
if (err) {
log_error("Could not get hostno for session %d\n", sid);
- err = MGMT_IPC_ERR_NOT_FOUND;
goto destroy_session;
}
session->r_stage = R_STAGE_SESSION_REOPEN;
err = sync_conn(session, 0);
- if (err) {
- if (err == ENOMEM)
- err = MGMT_IPC_ERR_NOMEM;
- else
- err = MGMT_IPC_ERR_INVAL;
+ if (err)
goto destroy_session;
- }
- session->sync_qtask = qtask;
qtask->rsp.command = MGMT_IPC_SESSION_SYNC;
- session_conn_reopen(&session->conn[0], qtask, STOP_CONN_RECOVER);
log_debug(3, "Started sync iSCSI session %d", session->id);
+ session->notify_qtask = qtask;
+ session_conn_reopen(&session->conn[0], qtask,
+ STOP_CONN_RECOVER);
+
return 0;
destroy_session:
@@ -2329,37 +1935,35 @@ static int session_unbind(struct iscsi_s
return err;
}
-int
-session_logout_task(int sid, queue_task_t *qtask)
+int session_logout_task(int sid, queue_task_t *qtask)
{
iscsi_session_t *session;
iscsi_conn_t *conn;
- mgmt_ipc_err_e rc = MGMT_IPC_OK;
+ int rc = ISCSI_SUCCESS;
session = session_find_by_sid(sid);
if (!session) {
log_debug(1, "session sid %d not found.\n", sid);
- return MGMT_IPC_ERR_NOT_FOUND;
+ return ISCSI_ERR_SESS_NOT_FOUND;
}
conn = &session->conn[0];
/*
* If syncing up or if this is the initial login and mgmt_ipc
* has not been notified of that result fail the logout request
*/
- if (session->sync_qtask ||
- ((conn->state == STATE_XPT_WAIT ||
- conn->state == STATE_IN_LOGIN) &&
+ if (session->notify_qtask ||
+ ((conn->state == ISCSI_CONN_STATE_XPT_WAIT ||
+ conn->state == ISCSI_CONN_STATE_IN_LOGIN) &&
(session->r_stage == R_STAGE_NO_CHANGE ||
session->r_stage == R_STAGE_SESSION_REDIRECT))) {
invalid_state:
log_error("session in invalid state for logout. "
"Try again later\n");
- return MGMT_IPC_ERR_INTERNAL;
+ return ISCSI_ERR_INTERNAL;
}
/* FIXME: logout all active connections */
conn = &session->conn[0];
- /* FIXME: implement Logout Request */
if (conn->logout_qtask)
goto invalid_state;
@@ -2368,41 +1972,45 @@ invalid_state:
conn->logout_qtask = qtask;
switch (conn->state) {
- case STATE_LOGGED_IN:
+ case ISCSI_CONN_STATE_LOGGED_IN:
if (!session_unbind(session))
- return MGMT_IPC_OK;
+ return ISCSI_SUCCESS;
+
+ /* LLDs that offload login also offload logout */
+ if (!(session->t->caps & CAP_LOGIN_OFFLOAD)) {
+ /* unbind is not supported so just do old logout */
+ if (!iscsi_send_logout(conn))
+ return ISCSI_SUCCESS;
+ }
- /* unbind is not supported so just do old logout */
- if (!iscsi_send_logout(conn))
- return MGMT_IPC_OK;
log_error("Could not send logout pdu. Dropping session\n");
/* fallthrough */
default:
- rc = session_conn_shutdown(conn, qtask, MGMT_IPC_OK);
+ rc = session_conn_shutdown(conn, qtask, ISCSI_SUCCESS);
break;
}
return rc;
}
-mgmt_ipc_err_e
+int
iscsi_host_send_targets(queue_task_t *qtask, int host_no, int do_login,
struct sockaddr_storage *ss)
{
struct iscsi_transport *t;
t = iscsi_sysfs_get_transport_by_hba(host_no);
- if (!t || set_transport_template(t)) {
+ if (!t) {
log_error("Invalid host no %d for sendtargets\n", host_no);
- return MGMT_IPC_ERR_TRANS_FAILURE;
+ return ISCSI_ERR_TRANS_NOT_FOUND;
}
if (!(t->caps & CAP_SENDTARGETS_OFFLOAD))
- return MGMT_IPC_ERR_TRANS_CAPS;
+ return ISCSI_ERR_TRANS_CAPS;
if (ipc->sendtargets(t->handle, host_no, (struct sockaddr *)ss))
- return MGMT_IPC_ERR;
+ return ISCSI_ERR;
- return MGMT_IPC_OK;
+ return ISCSI_SUCCESS;
}
/*
@@ -2412,7 +2020,7 @@ iscsi_host_send_targets(queue_task_t *qt
* the card will have sessions preset in the FLASH and will log into them
* automaotically then send us notification that a session is setup.
*/
-void iscsi_async_session_creation(uint32_t host_no, uint32_t sid)
+static void iscsi_async_session_creation(uint32_t host_no, uint32_t sid)
{
struct iscsi_transport *transport;
@@ -2428,7 +2036,20 @@ void iscsi_async_session_creation(uint32
session_scan_host(NULL, host_no, NULL);
}
-void iscsi_async_session_destruction(uint32_t host_no, uint32_t sid)
+static void iscsi_async_session_destruction(uint32_t host_no, uint32_t sid)
{
log_debug(3, "session destroyed sid %u host no %d", sid, host_no);
}
+
+static struct iscsi_ipc_ev_clbk ipc_clbk = {
+ .create_session = iscsi_async_session_creation,
+ .destroy_session = iscsi_async_session_destruction,
+ .get_ev_context = iscsi_ev_context_get,
+ .put_ev_context = iscsi_ev_context_put,
+ .sched_ev_context = iscsi_sched_ev_context,
+};
+
+void iscsi_initiator_init(void)
+{
+ ipc_register_ev_callback(&ipc_clbk);
+}
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/initiator_common.c open-iscsi-2.0-872-rc4-bnx2i.work/usr/initiator_common.c
--- open-iscsi-2.0-872-rc4-bnx2i/usr/initiator_common.c 1969-12-31 18:00:00.000000000 -0600
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/initiator_common.c 2012-03-05 23:02:46.000000000 -0600
@@ -0,0 +1,607 @@
+/*
+ * Common code for setting up discovery and normal sessions.
+ *
+ * Copyright (C) 2004 Dmitry Yusupov, Alex Aizman
+ * Copyright (C) 2006 - 2009 Mike Christie
+ * Copyright (C) 2006 - 2009 Red Hat, Inc. All rights reserved.
+ * maintained by open-iscsi@googlegroups.com
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published
+ * by the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * General Public License for more details.
+ *
+ * See the file COPYING included with this distribution for more details.
+ */
+
+#include <string.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <errno.h>
+
+#include "initiator.h"
+#include "transport.h"
+#include "iscsid.h"
+#include "iscsi_ipc.h"
+#include "log.h"
+#include "iscsi_sysfs.h"
+#include "iscsi_settings.h"
+#include "iface.h"
+#include "host.h"
+#include "sysdeps.h"
+#include "iscsi_err.h"
+
+struct iscsi_session *session_find_by_sid(uint32_t sid)
+{
+ struct iscsi_transport *t;
+ struct iscsi_session *session;
+
+ list_for_each_entry(t, &transports, list) {
+ list_for_each_entry(session, &t->sessions, list) {
+ if (session->id == sid)
+ return session;
+ }
+ }
+ return NULL;
+}
+
+/*
+ * calculate parameter's padding
+ */
+static unsigned int
+__padding(unsigned int param)
+{
+ int pad;
+
+ pad = param & 3;
+ if (pad) {
+ pad = 4 - pad;
+ log_debug(1, "parameter's value %d padded to %d bytes\n",
+ param, param + pad);
+ }
+ return param + pad;
+}
+
+int iscsi_setup_authentication(struct iscsi_session *session,
+ struct iscsi_auth_config *auth_cfg)
+{
+ /* if we have any incoming credentials, we insist on authenticating
+ * the target or not logging in at all
+ */
+ if (auth_cfg->username_in[0] || auth_cfg->password_in_length) {
+ /* sanity check the config */
+ if (auth_cfg->password_length == 0) {
+ log_warning("CHAP configuratoin has incoming "
+ "authentication credentials but has no "
+ "outgoing credentials configured.");
+ return EINVAL;
+ }
+ session->bidirectional_auth = 1;
+ } else {
+ /* no or 1-way authentication */
+ session->bidirectional_auth = 0;
+ }
+
+ /* copy in whatever credentials we have */
+ strlcpy(session->username, auth_cfg->username,
+ sizeof (session->username));
+ session->username[sizeof (session->username) - 1] = '\0';
+ if ((session->password_length = auth_cfg->password_length))
+ memcpy(session->password, auth_cfg->password,
+ session->password_length);
+
+ strlcpy(session->username_in, auth_cfg->username_in,
+ sizeof (session->username_in));
+ session->username_in[sizeof (session->username_in) - 1] = '\0';
+ if ((session->password_in_length =
+ auth_cfg->password_in_length))
+ memcpy(session->password_in, auth_cfg->password_in,
+ session->password_in_length);
+
+ if (session->password_length || session->password_in_length) {
+ /* setup the auth buffers */
+ session->auth_buffers[0].address = &session->auth_client_block;
+ session->auth_buffers[0].length =
+ sizeof (session->auth_client_block);
+ session->auth_buffers[1].address =
+ &session->auth_recv_string_block;
+ session->auth_buffers[1].length =
+ sizeof (session->auth_recv_string_block);
+
+ session->auth_buffers[2].address =
+ &session->auth_send_string_block;
+ session->auth_buffers[2].length =
+ sizeof (session->auth_send_string_block);
+
+ session->auth_buffers[3].address =
+ &session->auth_recv_binary_block;
+ session->auth_buffers[3].length =
+ sizeof (session->auth_recv_binary_block);
+
+ session->auth_buffers[4].address =
+ &session->auth_send_binary_block;
+ session->auth_buffers[4].length =
+ sizeof (session->auth_send_binary_block);
+
+ session->num_auth_buffers = 5;
+ log_debug(6, "authentication setup complete...");
+ } else {
+ session->num_auth_buffers = 0;
+ log_debug(6, "no authentication configured...");
+ }
+
+ return 0;
+}
+
+void
+iscsi_copy_operational_params(struct iscsi_conn *conn,
+ struct iscsi_session_operational_config *session_conf,
+ struct iscsi_conn_operational_config *conn_conf)
+{
+ struct iscsi_session *session = conn->session;
+ struct iscsi_transport *t = session->t;
+
+ conn->hdrdgst_en = conn_conf->HeaderDigest;
+ conn->datadgst_en = conn_conf->DataDigest;
+
+ conn->max_recv_dlength =
+ __padding(conn_conf->MaxRecvDataSegmentLength);
+ if (conn->max_recv_dlength < ISCSI_MIN_MAX_RECV_SEG_LEN ||
+ conn->max_recv_dlength > ISCSI_MAX_MAX_RECV_SEG_LEN) {
+ log_error("Invalid iscsi.MaxRecvDataSegmentLength. Must be "
+ "within %u and %u. Setting to %u\n",
+ ISCSI_MIN_MAX_RECV_SEG_LEN,
+ ISCSI_MAX_MAX_RECV_SEG_LEN,
+ DEF_INI_MAX_RECV_SEG_LEN);
+ conn_conf->MaxRecvDataSegmentLength =
+ DEF_INI_MAX_RECV_SEG_LEN;
+ conn->max_recv_dlength = DEF_INI_MAX_RECV_SEG_LEN;
+ }
+
+ /* zero indicates to use the target's value */
+ conn->max_xmit_dlength =
+ __padding(conn_conf->MaxXmitDataSegmentLength);
+ if (conn->max_xmit_dlength == 0)
+ conn->max_xmit_dlength = ISCSI_DEF_MAX_RECV_SEG_LEN;
+ if (conn->max_xmit_dlength < ISCSI_MIN_MAX_RECV_SEG_LEN ||
+ conn->max_xmit_dlength > ISCSI_MAX_MAX_RECV_SEG_LEN) {
+ log_error("Invalid iscsi.MaxXmitDataSegmentLength. Must be "
+ "within %u and %u. Setting to %u\n",
+ ISCSI_MIN_MAX_RECV_SEG_LEN,
+ ISCSI_MAX_MAX_RECV_SEG_LEN,
+ DEF_INI_MAX_RECV_SEG_LEN);
+ conn_conf->MaxXmitDataSegmentLength =
+ DEF_INI_MAX_RECV_SEG_LEN;
+ conn->max_xmit_dlength = DEF_INI_MAX_RECV_SEG_LEN;
+ }
+
+ /* session's operational parameters */
+ session->initial_r2t_en = session_conf->InitialR2T;
+ session->imm_data_en = session_conf->ImmediateData;
+ session->first_burst = __padding(session_conf->FirstBurstLength);
+ /*
+ * some targets like netapp fail the login if sent bad first_burst
+ * and max_burst lens, even when immediate data=no and
+ * initial r2t = Yes, so we always check the user values.
+ */
+ if (session->first_burst < ISCSI_MIN_FIRST_BURST_LEN ||
+ session->first_burst > ISCSI_MAX_FIRST_BURST_LEN) {
+ log_error("Invalid iscsi.FirstBurstLength of %u. Must be "
+ "within %u and %u. Setting to %u\n",
+ session->first_burst,
+ ISCSI_MIN_FIRST_BURST_LEN,
+ ISCSI_MAX_FIRST_BURST_LEN,
+ DEF_INI_FIRST_BURST_LEN);
+ session_conf->FirstBurstLength = DEF_INI_FIRST_BURST_LEN;
+ session->first_burst = DEF_INI_FIRST_BURST_LEN;
+ }
+
+ session->max_burst = __padding(session_conf->MaxBurstLength);
+ if (session->max_burst < ISCSI_MIN_MAX_BURST_LEN ||
+ session->max_burst > ISCSI_MAX_MAX_BURST_LEN) {
+ log_error("Invalid iscsi.MaxBurstLength of %u. Must be "
+ "within %u and %u. Setting to %u\n",
+ session->max_burst, ISCSI_MIN_MAX_BURST_LEN,
+ ISCSI_MAX_MAX_BURST_LEN, DEF_INI_MAX_BURST_LEN);
+ session_conf->MaxBurstLength = DEF_INI_MAX_BURST_LEN;
+ session->max_burst = DEF_INI_MAX_BURST_LEN;
+ }
+
+ if (session->first_burst > session->max_burst) {
+ log_error("Invalid iscsi.FirstBurstLength of %u. Must be "
+ "less than iscsi.MaxBurstLength. Setting to %u\n",
+ session->first_burst, session->max_burst);
+ session_conf->FirstBurstLength = session->max_burst;
+ session->first_burst = session->max_burst;
+ }
+
+ session->def_time2wait = session_conf->DefaultTime2Wait;
+ session->def_time2retain = session_conf->DefaultTime2Retain;
+ session->erl = session_conf->ERL;
+
+ if (session->type == ISCSI_SESSION_TYPE_DISCOVERY) {
+ /*
+ * Right now, we only support 8K max for kernel based
+ * sendtargets discovery, because the recv pdu buffers are
+ * limited to this size.
+ */
+ if ((t->caps & CAP_TEXT_NEGO) &&
+ conn->max_recv_dlength > ISCSI_DEF_MAX_RECV_SEG_LEN)
+ conn->max_recv_dlength = ISCSI_DEF_MAX_RECV_SEG_LEN;
+
+ /* We do not support discovery sessions with digests */
+ conn->hdrdgst_en = ISCSI_DIGEST_NONE;
+ conn->datadgst_en = ISCSI_DIGEST_NONE;
+ }
+
+ if (t->template->create_conn)
+ t->template->create_conn(conn);
+}
+
+int iscsi_setup_portal(struct iscsi_conn *conn, char *address, int port)
+{
+ char serv[NI_MAXSERV];
+
+ sprintf(serv, "%d", port);
+ if (resolve_address(address, serv, &conn->saddr)) {
+ log_error("cannot resolve host name %s", address);
+ return ISCSI_ERR_TRANS;
+ }
+ conn->failback_saddr = conn->saddr;
+
+ getnameinfo((struct sockaddr *)&conn->saddr, sizeof(conn->saddr),
+ conn->host, sizeof(conn->host), NULL, 0, NI_NUMERICHOST);
+ log_debug(4, "resolved %s to %s", address, conn->host);
+ return 0;
+}
+
+int host_set_param(struct iscsi_transport *t,
+ uint32_t host_no, int param, char *value,
+ int type)
+{
+ int rc;
+
+ rc = ipc->set_host_param(t->handle, host_no, param, value, type);
+ /* 2.6.20 and below returns EINVAL */
+ if (rc && rc != -ENOSYS && rc != -EINVAL) {
+ log_error("can't set operational parameter %d for "
+ "host %d, retcode %d (%d)", param, host_no,
+ rc, errno);
+ return rc;
+ }
+ return 0;
+}
+
+static void print_param_value(enum iscsi_param param, void *value, int type)
+{
+ log_debug(3, "set operational parameter %d to:", param);
+
+ if (type == ISCSI_STRING)
+ log_debug(3, "%s", value ? (char *)value : "NULL");
+ else
+ log_debug(3, "%u", *(uint32_t *)value);
+}
+
+#define MAX_HOST_PARAMS 2
+
+int iscsi_host_set_params(struct iscsi_session *session)
+{
+ struct iscsi_transport *t = session->t;
+ int i;
+ struct hostparam {
+ int param;
+ int type;
+ void *value;
+ } hosttbl[MAX_HOST_PARAMS] = {
+ {
+ .param = ISCSI_HOST_PARAM_NETDEV_NAME,
+ .value = session->nrec.iface.netdev,
+ .type = ISCSI_STRING,
+ }, {
+ .param = ISCSI_HOST_PARAM_HWADDRESS,
+ .value = session->nrec.iface.hwaddress,
+ .type = ISCSI_STRING,
+ },
+ };
+
+ for (i = 0; i < MAX_HOST_PARAMS; i++) {
+ if (host_set_param(t, session->hostno,
+ hosttbl[i].param, hosttbl[i].value,
+ hosttbl[i].type)) {
+ return EPERM;
+ }
+
+ print_param_value(hosttbl[i].param, hosttbl[i].value,
+ hosttbl[i].type);
+ }
+
+ return 0;
+}
+
+#define MAX_SESSION_PARAMS 32
+
+int iscsi_session_set_params(struct iscsi_conn *conn)
+{
+ struct iscsi_session *session = conn->session;
+ struct iscsi_transport *t = session->t;
+ int i, rc;
+ uint32_t one = 1, zero = 0;
+ struct connparam {
+ int param;
+ int type;
+ void *value;
+ int conn_only;
+ } conntbl[MAX_SESSION_PARAMS] = {
+ {
+ .param = ISCSI_PARAM_MAX_RECV_DLENGTH,
+ .value = &conn->max_recv_dlength,
+ .type = ISCSI_INT,
+ .conn_only = 0,
+ }, {
+ .param = ISCSI_PARAM_MAX_XMIT_DLENGTH,
+ .value = &conn->max_xmit_dlength,
+ .type = ISCSI_INT,
+ .conn_only = 0,
+ }, {
+ .param = ISCSI_PARAM_HDRDGST_EN,
+ .value = &conn->hdrdgst_en,
+ .type = ISCSI_INT,
+ .conn_only = 0,
+ }, {
+ .param = ISCSI_PARAM_DATADGST_EN,
+ .value = &conn->datadgst_en,
+ .type = ISCSI_INT,
+ .conn_only = 1,
+ }, {
+ .param = ISCSI_PARAM_INITIAL_R2T_EN,
+ .value = &session->initial_r2t_en,
+ .type = ISCSI_INT,
+ .conn_only = 0,
+ }, {
+ .param = ISCSI_PARAM_MAX_R2T,
+ .value = &one, /* FIXME: session->max_r2t */
+ .type = ISCSI_INT,
+ .conn_only = 0,
+ }, {
+ .param = ISCSI_PARAM_IMM_DATA_EN,
+ .value = &session->imm_data_en,
+ .type = ISCSI_INT,
+ .conn_only = 0,
+ }, {
+ .param = ISCSI_PARAM_FIRST_BURST,
+ .value = &session->first_burst,
+ .type = ISCSI_INT,
+ .conn_only = 0,
+ }, {
+ .param = ISCSI_PARAM_MAX_BURST,
+ .value = &session->max_burst,
+ .type = ISCSI_INT,
+ .conn_only = 0,
+ }, {
+ .param = ISCSI_PARAM_PDU_INORDER_EN,
+ .value = &session->pdu_inorder_en,
+ .type = ISCSI_INT,
+ .conn_only = 0,
+ }, {
+ .param =ISCSI_PARAM_DATASEQ_INORDER_EN,
+ .value = &session->dataseq_inorder_en,
+ .type = ISCSI_INT,
+ .conn_only = 0,
+ }, {
+ .param = ISCSI_PARAM_ERL,
+ .value = &zero, /* FIXME: session->erl */
+ .type = ISCSI_INT,
+ .conn_only = 0,
+ }, {
+ .param = ISCSI_PARAM_IFMARKER_EN,
+ .value = &zero,/* FIXME: session->ifmarker_en */
+ .type = ISCSI_INT,
+ .conn_only = 0,
+ }, {
+ .param = ISCSI_PARAM_OFMARKER_EN,
+ .value = &zero,/* FIXME: session->ofmarker_en */
+ .type = ISCSI_INT,
+ .conn_only = 0,
+ }, {
+ .param = ISCSI_PARAM_EXP_STATSN,
+ .value = &conn->exp_statsn,
+ .type = ISCSI_INT,
+ .conn_only = 1,
+ }, {
+ .param = ISCSI_PARAM_TARGET_NAME,
+ .conn_only = 0,
+ .type = ISCSI_STRING,
+ .value = session->target_name,
+ }, {
+ .param = ISCSI_PARAM_TPGT,
+ .value = &session->portal_group_tag,
+ .type = ISCSI_INT,
+ .conn_only = 0,
+ }, {
+ .param = ISCSI_PARAM_PERSISTENT_ADDRESS,
+ .value = session->nrec.conn[conn->id].address,
+ .type = ISCSI_STRING,
+ .conn_only = 1,
+ }, {
+ .param = ISCSI_PARAM_PERSISTENT_PORT,
+ .value = &session->nrec.conn[conn->id].port,
+ .type = ISCSI_INT,
+ .conn_only = 1,
+ }, {
+ .param = ISCSI_PARAM_SESS_RECOVERY_TMO,
+ .value = &session->replacement_timeout,
+ .type = ISCSI_INT,
+ .conn_only = 0,
+ }, {
+ .param = ISCSI_PARAM_USERNAME,
+ .value = session->username,
+ .type = ISCSI_STRING,
+ .conn_only = 0,
+ }, {
+ .param = ISCSI_PARAM_USERNAME_IN,
+ .value = session->username_in,
+ .type = ISCSI_STRING,
+ .conn_only = 0,
+ }, {
+ .param = ISCSI_PARAM_PASSWORD,
+ .value = session->password,
+ .type = ISCSI_STRING,
+ .conn_only = 0,
+ }, {
+ .param = ISCSI_PARAM_PASSWORD_IN,
+ .value = session->password_in,
+ .type = ISCSI_STRING,
+ .conn_only = 0,
+ }, {
+ .param = ISCSI_PARAM_FAST_ABORT,
+ .value = &session->fast_abort,
+ .type = ISCSI_INT,
+ .conn_only = 0,
+ }, {
+ .param = ISCSI_PARAM_ABORT_TMO,
+ .value = &session->abort_timeout,
+ .type = ISCSI_INT,
+ .conn_only = 0,
+ }, {
+ .param = ISCSI_PARAM_LU_RESET_TMO,
+ .value = &session->lu_reset_timeout,
+ .type = ISCSI_INT,
+ .conn_only = 0,
+ }, {
+ .param = ISCSI_PARAM_TGT_RESET_TMO,
+ .value = &session->tgt_reset_timeout,
+ .type = ISCSI_INT,
+ .conn_only = 0,
+ }, {
+ .param = ISCSI_PARAM_PING_TMO,
+ .value = &conn->noop_out_timeout,
+ .type = ISCSI_INT,
+ .conn_only = 1,
+ }, {
+ .param = ISCSI_PARAM_RECV_TMO,
+ .value = &conn->noop_out_interval,
+ .type = ISCSI_INT,
+ .conn_only = 1,
+ }, {
+ .param = ISCSI_PARAM_IFACE_NAME,
+ .value = session->nrec.iface.name,
+ .type = ISCSI_STRING,
+ }, {
+ .param = ISCSI_PARAM_INITIATOR_NAME,
+ .value = session->initiator_name,
+ .type = ISCSI_STRING,
+ },
+ };
+
+ session->param_mask = ~0ULL;
+ if (!(t->caps & CAP_MULTI_R2T))
+ session->param_mask &= ~ISCSI_MAX_R2T;
+ if (!(t->caps & CAP_HDRDGST))
+ session->param_mask &= ~ISCSI_HDRDGST_EN;
+ if (!(t->caps & CAP_DATADGST))
+ session->param_mask &= ~ISCSI_DATADGST_EN;
+ if (!(t->caps & CAP_MARKERS)) {
+ session->param_mask &= ~ISCSI_IFMARKER_EN;
+ session->param_mask &= ~ISCSI_OFMARKER_EN;
+ }
+
+ /* some llds will send nops internally */
+ if (!iscsi_sysfs_session_supports_nop(session->id)) {
+ session->param_mask &= ~ISCSI_PING_TMO;
+ session->param_mask &= ~ISCSI_RECV_TMO;
+ }
+
+ /* Entered full-feature phase! */
+ for (i = 0; i < MAX_SESSION_PARAMS; i++) {
+ if (conn->id != 0 && !conntbl[i].conn_only)
+ continue;
+
+ if (!(session->param_mask & (1ULL << conntbl[i].param)))
+ continue;
+
+ rc = ipc->set_param(session->t->handle, session->id,
+ conn->id, conntbl[i].param, conntbl[i].value,
+ conntbl[i].type);
+ if (rc && rc != -ENOSYS) {
+ log_error("can't set operational parameter %d for "
+ "connection %d:%d, retcode %d (%d)",
+ conntbl[i].param, session->id, conn->id,
+ rc, errno);
+ return EPERM;
+ }
+
+ if (rc == -ENOSYS) {
+ switch (conntbl[i].param) {
+ case ISCSI_PARAM_PING_TMO:
+ /*
+ * older kernels may not support nops
+ * in kernel
+ */
+ conn->userspace_nop = 1;
+ break;
+#if 0
+TODO handle this
+ case ISCSI_PARAM_INITIATOR_NAME:
+ /* use host level one instead */
+ hosttbl[ISCSI_HOST_PARAM_INITIATOR_NAME].set = 1;
+ break;
+#endif
+ }
+ }
+
+ print_param_value(conntbl[i].param, conntbl[i].value,
+ conntbl[i].type);
+ }
+
+ return 0;
+}
+
+int iscsi_host_set_net_params(struct iface_rec *iface,
+ struct iscsi_session *session)
+{
+ struct iscsi_transport *t = session->t;
+ int rc = 0;
+
+ log_debug(3, "setting iface %s, dev %s, set ip %s, hw %s, "
+ "transport %s.\n",
+ iface->name, iface->netdev, iface->ipaddress,
+ iface->hwaddress, iface->transport_name);
+
+ if (!t->template->set_host_ip)
+ return 0;
+
+ /* if we need to set the ip addr then set all the iface net settings */
+ if (!iface_is_bound_by_ipaddr(iface)) {
+ log_warning("Please set the iface.ipaddress for iface %s, "
+ "then retry the login command.\n", iface->name);
+ return EINVAL;
+ }
+
+ rc = host_set_param(t, session->hostno,
+ ISCSI_HOST_PARAM_IPADDRESS,
+ iface->ipaddress, ISCSI_STRING);
+ if (rc)
+ return rc;
+
+ if (iface_is_bound_by_netdev(iface)) {
+ rc = host_set_param(t, session->hostno,
+ ISCSI_HOST_PARAM_NETDEV_NAME,
+ iface->netdev, ISCSI_STRING);
+ if (rc)
+ return rc;
+ }
+
+ if (iface_is_bound_by_hwaddr(iface)) {
+ rc = host_set_param(t, session->hostno,
+ ISCSI_HOST_PARAM_HWADDRESS,
+ iface->hwaddress, ISCSI_STRING);
+ if (rc)
+ return rc;
+ }
+ return 0;
+}
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/initiator.h open-iscsi-2.0-872-rc4-bnx2i.work/usr/initiator.h
--- open-iscsi-2.0-872-rc4-bnx2i/usr/initiator.h 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/initiator.h 2012-03-05 23:02:46.000000000 -0600
@@ -39,25 +39,18 @@
#define INITIATOR_NAME_FILE ISCSI_CONFIG_ROOT"initiatorname.iscsi"
#define PID_FILE "/var/run/iscsid.pid"
+#ifndef LOCK_DIR
#define LOCK_DIR "/var/lock/iscsi"
-#define LOCK_FILE "/var/lock/iscsi/lock"
-#define LOCK_WRITE_FILE "/var/lock/iscsi/lock.write"
-
-typedef enum iscsi_conn_state_e {
- STATE_FREE,
- STATE_XPT_WAIT,
- STATE_IN_LOGIN,
- STATE_LOGGED_IN,
- STATE_IN_LOGOUT,
- STATE_LOGOUT_REQUESTED,
- STATE_CLEANUP_WAIT,
-} iscsi_conn_state_e;
+#endif
+#define LOCK_FILE LOCK_DIR"/lock"
+#define LOCK_WRITE_FILE LOCK_DIR"/lock.write"
typedef enum iscsi_session_r_stage_e {
R_STAGE_NO_CHANGE,
R_STAGE_SESSION_CLEANUP,
R_STAGE_SESSION_REOPEN,
R_STAGE_SESSION_REDIRECT,
+ R_STAGE_SESSION_DESTOYED,
} iscsi_session_r_stage_e;
typedef enum conn_login_status_e {
@@ -67,6 +60,7 @@ typedef enum conn_login_status_e {
CONN_LOGIN_RETRY = 3,
CONN_LOGIN_IMM_RETRY = 4,
CONN_LOGIN_IMM_REDIRECT_RETRY = 5,
+ CONN_LOGIN_AUTH_FAILED = 6,
} conn_login_status_e;
enum iscsi_login_status {
@@ -88,6 +82,7 @@ typedef enum iscsi_event_e {
EV_CONN_ERROR,
EV_CONN_LOGOUT_TIMER,
EV_CONN_STOP,
+ EV_CONN_LOGIN,
} iscsi_event_e;
struct queue_task;
@@ -112,18 +107,18 @@ typedef struct iscsi_login_context {
struct iscsi_session;
struct iscsi_conn;
-struct iscsi_conn_context;
+struct iscsi_ev_context;
/* daemon's connection structure */
typedef struct iscsi_conn {
uint32_t id;
struct iscsi_session *session;
iscsi_login_context_t login_context;
- struct iscsi_conn_context *recv_context;
+ struct iscsi_ev_context *recv_context;
struct queue_task *logout_qtask;
char data[ISCSI_DEF_MAX_RECV_SEG_LEN];
char host[NI_MAXHOST]; /* scratch */
- iscsi_conn_state_e state;
+ enum iscsi_conn_state state;
int userspace_nop;
struct timeval initial_connect_time;
@@ -131,7 +126,7 @@ typedef struct iscsi_conn {
actor_t nop_out_timer;
#define CONTEXT_POOL_MAX 32
- struct iscsi_conn_context *context_pool[CONTEXT_POOL_MAX];
+ struct iscsi_ev_context *context_pool[CONTEXT_POOL_MAX];
/* login state machine */
int current_stage;
@@ -140,6 +135,11 @@ typedef struct iscsi_conn {
conn_login_status_e status;
/* tcp/socket settings */
+
+ /*
+ * Either a tcp/ip or a netlink socket to do
+ * IO through.
+ */
int socket_fd;
/* address being used for normal session connection */
struct sockaddr_storage saddr;
@@ -173,7 +173,7 @@ typedef struct iscsi_conn {
uint32_t max_xmit_dlength; /* the value declared by the target */
} iscsi_conn_t;
-struct iscsi_conn_context {
+struct iscsi_ev_context {
struct actor actor;
struct iscsi_conn *conn;
int allocated;
@@ -201,6 +201,7 @@ typedef struct iscsi_session {
uint32_t hostno;
char netdev[IFNAMSIZ];
struct iscsi_transport *t;
+ uint8_t use_ipc;
node_rec_t nrec; /* copy of original Node record in database */
unsigned int irrelevant_keys_bitmap;
int send_async_text;
@@ -242,7 +243,6 @@ typedef struct iscsi_session {
uint8_t password_in[AUTH_STR_MAX_LEN];
int password_in_length;
iscsi_conn_t conn[ISCSI_CONN_MAX];
- int ctrl_fd;
uint64_t param_mask;
/* connection reopens during recovery */
@@ -256,8 +256,11 @@ typedef struct iscsi_session {
int lu_reset_timeout;
int abort_timeout;
- /* sync up fields */
- queue_task_t *sync_qtask;
+ /*
+ * used for hw and sync up to notify caller that the operation
+ * is complete
+ */
+ queue_task_t *notify_qtask;
} iscsi_session_t;
/* login.c */
@@ -330,20 +333,25 @@ extern int iscsi_io_recv_pdu(iscsi_conn_
/* initiator.c */
extern int session_login_task(node_rec_t *rec, queue_task_t *qtask);
extern int session_logout_task(int sid, queue_task_t *qtask);
-extern iscsi_session_t *session_find_by_sid(int sid);
-extern struct iscsi_conn_context *iscsi_conn_context_get(iscsi_conn_t *conn,
- int ev_size);
-extern void iscsi_conn_context_put(struct iscsi_conn_context *conn_context);
-extern void iscsi_sched_conn_context(struct iscsi_conn_context *context,
- struct iscsi_conn *conn, unsigned long tmo,
- int event);
-extern mgmt_ipc_err_e iscsi_sync_session(node_rec_t *rec, queue_task_t
+extern iscsi_session_t *session_find_by_sid(uint32_t sid);
+extern int iscsi_sync_session(node_rec_t *rec, queue_task_t
*tsk, uint32_t sid);
-extern mgmt_ipc_err_e iscsi_host_send_targets(queue_task_t *qtask,
+extern int iscsi_host_send_targets(queue_task_t *qtask,
int host_no, int do_login, struct sockaddr_storage *ss);
-extern mgmt_ipc_err_e iscsi_host_set_param(int host_no, int param, char *value);
-extern void iscsi_async_session_creation(uint32_t host_no, uint32_t sid);
-extern void iscsi_async_session_destruction(uint32_t host_no, uint32_t sid);
+
extern void free_initiator(void);
+extern void iscsi_initiator_init(void);
+
+/* initiator code common to discovery and normal sessions */
+extern int iscsi_session_set_params(struct iscsi_conn *conn);
+extern int iscsi_host_set_params(struct iscsi_session *session);
+extern int iscsi_host_set_net_params(struct iface_rec *iface,
+ struct iscsi_session *session);
+extern void iscsi_copy_operational_params(struct iscsi_conn *conn,
+ struct iscsi_session_operational_config *session_conf,
+ struct iscsi_conn_operational_config *conn_conf);
+extern int iscsi_setup_authentication(struct iscsi_session *session,
+ struct iscsi_auth_config *auth_cfg);
+extern int iscsi_setup_portal(struct iscsi_conn *conn, char *address, int port);
#endif /* INITIATOR_H */
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/io.c open-iscsi-2.0-872-rc4-bnx2i.work/usr/io.c
--- open-iscsi-2.0-872-rc4-bnx2i/usr/io.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/io.c 2012-03-05 23:02:46.000000000 -0600
@@ -26,11 +26,14 @@
#include <fcntl.h>
#include <sys/poll.h>
#include <sys/ioctl.h>
+#include <sys/types.h>
+#include <ifaddrs.h>
#include <netinet/tcp.h>
#include <arpa/inet.h>
#include "types.h"
#include "iscsi_proto.h"
+#include "iscsi_settings.h"
#include "initiator.h"
#include "iscsi_ipc.h"
#include "log.h"
@@ -38,6 +41,7 @@
#include "idbm.h"
#include "iface.h"
#include "sysdeps.h"
+#include "dcb_app.h"
#define LOG_CONN_CLOSED(conn) \
do { \
@@ -53,6 +57,13 @@ do { \
log_error("Connection to Discovery Address %s failed", conn->host); \
} while (0)
+union sockaddr_u {
+ struct sockaddr_storage ss;
+ struct sockaddr sa;
+ struct sockaddr_in si;
+ struct sockaddr_in6 si6;
+};
+
static int timedout;
static void
@@ -76,6 +87,93 @@ set_non_blocking(int fd)
}
+static int select_priority(struct iscsi_conn *conn, int pri_mask)
+{
+ int msk;
+
+ if (!pri_mask)
+ return 0;
+
+ /*
+ * TODO: Configure priority selection from the mask
+ * For now, just always take the highest
+ */
+
+ /* Find highest bit set */
+ while ((msk = pri_mask & (pri_mask - 1)))
+ pri_mask = msk;
+
+ return ffs(pri_mask) - 1;
+}
+
+static int
+inet_cmp_addr(const union sockaddr_u *s1, const union sockaddr_u *s2)
+{
+ const struct sockaddr_in *si1 = &s1->si;
+ const struct sockaddr_in *si2 = &s2->si;
+
+ return si1->sin_addr.s_addr != si2->sin_addr.s_addr;
+}
+
+static int
+inet6_cmp_addr(const union sockaddr_u *s1, const union sockaddr_u *s2)
+{
+ const struct sockaddr_in6 *si1 = &s1->si6;
+ const struct sockaddr_in6 *si2 = &s2->si6;
+
+ return memcmp(&si1->sin6_addr, &si2->sin6_addr, sizeof(si1->sin6_addr));
+}
+
+static char *
+find_ifname(const struct ifaddrs *ifa, const union sockaddr_u *ss)
+{
+ for (; ifa; ifa = ifa->ifa_next) {
+ if (!ifa->ifa_addr)
+ continue;
+
+ if (ss->ss.ss_family != ifa->ifa_addr->sa_family)
+ continue;
+ switch (ss->ss.ss_family) {
+ case AF_INET:
+ if (inet_cmp_addr(ss, (union sockaddr_u *)ifa->ifa_addr) == 0)
+ return ifa->ifa_name;
+ break;
+ case AF_INET6:
+ if (inet6_cmp_addr(ss, (union sockaddr_u *)ifa->ifa_addr) == 0)
+ return ifa->ifa_name;
+ break;
+ }
+ }
+
+ return NULL;
+}
+
+static void set_dcb_priority(struct iscsi_conn *conn, const char *devname)
+{
+ int pri_mask = 0;
+
+ pri_mask = get_dcb_app_pri_by_stream_port(devname, ISCSI_DEFAULT_PORT);
+ if (pri_mask < 0)
+ log_debug(2, "Getting priority for %s returned %d",
+ devname, pri_mask);
+ else if (pri_mask == 0)
+ log_debug(2, "No priority for %s", devname);
+ else {
+ int pri = select_priority(conn, pri_mask);
+ int rc;
+
+ log_debug(1, "Setting socket %d priority to %d",
+ conn->socket_fd, pri);
+ rc = setsockopt(conn->socket_fd, SOL_SOCKET,
+ SO_PRIORITY, &pri, sizeof(pri));
+ if (rc < 0) {
+ log_warning("Setting socket %d priority to %d failed "
+ "with errno %d", conn->socket_fd,
+ pri, errno);
+ }
+ }
+}
+
#if 0
/* not used by anyone */
static int get_hwaddress_from_netdev(char *netdev, char *hwaddress)
@@ -201,15 +299,20 @@ static int bind_conn_to_iface(iscsi_conn
{
struct iscsi_session *session = conn->session;
+ if (strcmp(iface->transport_name, DEFAULT_TRANSPORT))
+ return 0;
+
memset(session->netdev, 0, IFNAMSIZ);
- if (iface_is_bound_by_hwaddr(iface) &&
- net_get_netdev_from_hwaddress(iface->hwaddress, session->netdev)) {
- log_error("Cannot match %s to net/scsi interface.",
- iface->hwaddress);
- return -1;
- } else if (iface_is_bound_by_netdev(iface))
+ if (iface_is_bound_by_hwaddr(iface)) {
+ if (net_get_netdev_from_hwaddress(iface->hwaddress,
+ session->netdev)) {
+ log_error("Cannot match %s to net/scsi interface.",
+ iface->hwaddress);
+ return -1;
+ }
+ } else if (iface_is_bound_by_netdev(iface)) {
strcpy(session->netdev, iface->netdev);
- else if (iface_is_bound_by_ipaddr(iface)) {
+ } else if (iface_is_bound_by_ipaddr(iface)) {
/*
* we never supported this but now with offload having to
* set the ip address in the iface, useris may forget to
@@ -260,10 +363,8 @@ iscsi_io_tcp_connect(iscsi_conn_t *conn,
return -1;
}
- if (conn->session) {
- if (bind_conn_to_iface(conn, &conn->session->nrec.iface))
- return -1;
- }
+ if (bind_conn_to_iface(conn, &conn->session->nrec.iface))
+ return -1;
onearg = 1;
rc = setsockopt(conn->socket_fd, IPPROTO_TCP, TCP_NODELAY, &onearg,
@@ -320,6 +421,10 @@ iscsi_io_tcp_connect(iscsi_conn_t *conn,
log_debug(1, "connecting to %s:%s", conn->host, serv);
if (non_blocking)
set_non_blocking(conn->socket_fd);
+
+ if (conn->session->netdev[0])
+ set_dcb_priority(conn, conn->session->netdev);
+
rc = connect(conn->socket_fd, (struct sockaddr *) ss, sizeof (*ss));
return rc;
}
@@ -331,7 +436,7 @@ iscsi_io_tcp_poll(iscsi_conn_t *conn, in
struct pollfd pdesc;
char serv[NI_MAXSERV], lserv[NI_MAXSERV];
struct sockaddr_storage ss;
- socklen_t len = sizeof(ss);
+ socklen_t len;
pdesc.fd = conn->socket_fd;
pdesc.events = POLLOUT;
@@ -368,8 +473,9 @@ iscsi_io_tcp_poll(iscsi_conn_t *conn, in
}
len = sizeof(ss);
- if (log_level > 0 &&
- getsockname(conn->socket_fd, (struct sockaddr *) &ss, &len) >= 0) {
+ if (log_level > 0 || !conn->session->netdev[0])
+ rc = getsockname(conn->socket_fd, (struct sockaddr *)&ss, &len);
+ if (log_level > 0 && rc >= 0) {
getnameinfo((struct sockaddr *) &conn->saddr,
sizeof(conn->saddr), conn->host,
sizeof(conn->host), serv, sizeof(serv),
@@ -381,6 +487,22 @@ iscsi_io_tcp_poll(iscsi_conn_t *conn, in
log_debug(1, "connected local port %s to %s:%s",
lserv, conn->host, serv);
}
+
+ if (!conn->session->netdev[0] && rc >= 0) {
+ struct ifaddrs *ifa;
+ char *ifname;
+
+ rc = getifaddrs(&ifa);
+ if (rc < 0)
+ log_error("getifaddrs failed with %d\n", errno);
+ else {
+ ifname = find_ifname(ifa, (union sockaddr_u *)&ss);
+ if (ifname)
+ set_dcb_priority(conn, ifname);
+ freeifaddrs(ifa);
+ }
+ }
+
return 1;
}
@@ -401,7 +523,6 @@ iscsi_io_connect(iscsi_conn_t *conn)
int rc, ret;
struct sigaction action;
struct sigaction old;
- char serv[NI_MAXSERV];
/* set a timeout, since the socket calls may take a long time to
* timeout on their own
@@ -420,22 +541,21 @@ iscsi_io_connect(iscsi_conn_t *conn)
*/
rc = iscsi_io_tcp_connect(conn, 0);
if (timedout) {
+ log_error("connect to %s timed out", conn->host);
+
log_debug(1, "socket %d connect timed out", conn->socket_fd);
ret = 0;
goto done;
} else if (rc < 0) {
- getnameinfo((struct sockaddr *) &conn->saddr,
- sizeof(conn->saddr),
- conn->host, sizeof(conn->host), serv, sizeof(serv),
- NI_NUMERICHOST|NI_NUMERICSERV);
- log_error("cannot make connection to %s:%s (%d)",
- conn->host, serv, errno);
+ log_error("cannot make connection to %s: %s",
+ conn->host, strerror(errno));
close(conn->socket_fd);
ret = 0;
goto done;
} else if (log_level > 0) {
struct sockaddr_storage ss;
char lserv[NI_MAXSERV];
+ char serv[NI_MAXSERV];
socklen_t salen = sizeof(ss);
if (getsockname(conn->socket_fd, (struct sockaddr *) &ss,
@@ -503,7 +623,7 @@ iscsi_io_send_pdu(iscsi_conn_t *conn, st
/* set a timeout, since the socket calls may take a long time
* to timeout on their own
*/
- if (!ipc) {
+ if (!session->use_ipc) {
memset(&action, 0, sizeof (struct sigaction));
memset(&old, 0, sizeof (struct sigaction));
action.sa_sigaction = NULL;
@@ -566,7 +686,7 @@ iscsi_io_send_pdu(iscsi_conn_t *conn, st
else
pad_bytes = 0;
- if (ipc)
+ if (session->use_ipc)
ipc->send_pdu_begin(session->t->handle, session->id,
conn->id, end - header,
ntoh24(hdr->dlength) + pad_bytes);
@@ -575,8 +695,8 @@ iscsi_io_send_pdu(iscsi_conn_t *conn, st
vec[0].iov_base = header;
vec[0].iov_len = end - header;
- if (!ipc)
- rc = writev(session->ctrl_fd, vec, 1);
+ if (!session->use_ipc)
+ rc = writev(conn->socket_fd, vec, 1);
else
rc = ipc->writev(0, vec, 1);
if (timedout) {
@@ -603,13 +723,13 @@ iscsi_io_send_pdu(iscsi_conn_t *conn, st
vec[1].iov_base = (void *) &pad;
vec[1].iov_len = pad_bytes;
- if (!ipc)
- rc = writev(session->ctrl_fd, vec, 2);
+ if (!session->use_ipc)
+ rc = writev(conn->socket_fd, vec, 2);
else
rc = ipc->writev(0, vec, 2);
if (timedout) {
log_error("socket %d write timed out",
- conn->socket_fd);
+ conn->socket_fd);
ret = 0;
goto done;
} else if ((rc <= 0) && (errno != EAGAIN)) {
@@ -627,7 +747,7 @@ iscsi_io_send_pdu(iscsi_conn_t *conn, st
}
}
- if (ipc) {
+ if (session->use_ipc) {
if (ipc->send_pdu_end(session->t->handle, session->id,
conn->id, &rc)) {
ret = 0;
@@ -638,7 +758,7 @@ iscsi_io_send_pdu(iscsi_conn_t *conn, st
ret = 1;
done:
- if (!ipc) {
+ if (!session->use_ipc) {
alarm(0);
sigaction(SIGALRM, &old, NULL);
timedout = 0;
@@ -670,7 +790,7 @@ iscsi_io_recv_pdu(iscsi_conn_t *conn, st
/* set a timeout, since the socket calls may take a long
* time to timeout on their own
*/
- if (!ipc) {
+ if (!session->use_ipc) {
memset(&action, 0, sizeof (struct sigaction));
memset(&old, 0, sizeof (struct sigaction));
action.sa_sigaction = NULL;
@@ -680,7 +800,10 @@ iscsi_io_recv_pdu(iscsi_conn_t *conn, st
timedout = 0;
alarm(timeout);
} else {
- if (ipc->recv_pdu_begin(conn)) {
+ failed = ipc->recv_pdu_begin(conn);
+ if (failed == -EAGAIN)
+ return -EAGAIN;
+ else if (failed < 0) {
failed = 1;
goto done;
}
@@ -688,14 +811,14 @@ iscsi_io_recv_pdu(iscsi_conn_t *conn, st
/* read a response header */
do {
- if (!ipc)
- rlen = read(session->ctrl_fd, header,
+ if (!session->use_ipc)
+ rlen = read(conn->socket_fd, header,
sizeof (*hdr) - h_bytes);
else
rlen = ipc->read(header, sizeof (*hdr) - h_bytes);
if (timedout) {
log_error("socket %d header read timed out",
- conn->socket_fd);
+ conn->socket_fd);
failed = 1;
goto done;
} else if (rlen == 0) {
@@ -714,7 +837,7 @@ iscsi_io_recv_pdu(iscsi_conn_t *conn, st
} while (h_bytes < sizeof (*hdr));
log_debug(4, "read %d PDU header bytes, opcode 0x%x, dlength %u, "
- "data %p, max %u", h_bytes, hdr->opcode,
+ "data %p, max %u", h_bytes, hdr->opcode & ISCSI_OPCODE_MASK,
ntoh24(hdr->dlength), data, max_data_length);
/* check for additional headers */
@@ -745,14 +868,14 @@ iscsi_io_recv_pdu(iscsi_conn_t *conn, st
/* read the rest into our buffer */
d_bytes = 0;
while (d_bytes < dlength) {
- if (!ipc)
- rlen = read(session->ctrl_fd, data + d_bytes,
+ if (!session->use_ipc)
+ rlen = read(conn->socket_fd, data + d_bytes,
dlength - d_bytes);
else
rlen = ipc->read(data + d_bytes, dlength - d_bytes);
if (timedout) {
log_error("socket %d data read timed out",
- conn->socket_fd);
+ conn->socket_fd);
failed = 1;
goto done;
} else if (rlen == 0) {
@@ -772,7 +895,7 @@ iscsi_io_recv_pdu(iscsi_conn_t *conn, st
/* handle PDU data padding.
* data is padded in case of kernel_io */
pad = dlength % ISCSI_PAD_LEN;
- if (pad && !ipc) {
+ if (pad && !session->use_ipc) {
int pad_bytes = pad = ISCSI_PAD_LEN - pad;
char bytes[ISCSI_PAD_LEN];
@@ -780,7 +903,7 @@ iscsi_io_recv_pdu(iscsi_conn_t *conn, st
rlen = read(conn->socket_fd, &bytes, pad_bytes);
if (timedout) {
log_error("socket %d pad read timed out",
- conn->socket_fd);
+ conn->socket_fd);
failed = 1;
goto done;
} else if (rlen == 0) {
@@ -828,7 +951,7 @@ iscsi_io_recv_pdu(iscsi_conn_t *conn, st
}
done:
- if (!ipc) {
+ if (!session->use_ipc) {
alarm(0);
sigaction(SIGALRM, &old, NULL);
} else {
@@ -840,7 +963,7 @@ done:
if (timedout || failed) {
timedout = 0;
- return 0;
+ return -EIO;
}
return h_bytes + ahs_bytes + d_bytes;
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/iscsiadm.c open-iscsi-2.0-872-rc4-bnx2i.work/usr/iscsiadm.c
--- open-iscsi-2.0-872-rc4-bnx2i/usr/iscsiadm.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/iscsiadm.c 2012-03-05 23:02:46.000000000 -0600
@@ -4,6 +4,7 @@
* Copyright (C) 2004 Dmitry Yusupov, Alex Aizman
* Copyright (C) 2006 Mike Christie
* Copyright (C) 2006 Red Hat, Inc. All rights reserved.
+ * Copyright (C) 2011 Dell Inc.
* maintained by open-iscsi@googlegroups.com
*
* This program is free software; you can redistribute it and/or modify
@@ -48,10 +49,12 @@
#include "session_mgmt.h"
#include "iscsid_req.h"
#include "isns-proto.h"
+#include "iscsi_err.h"
+#include "iscsi_ipc.h"
-struct iscsi_ipc *ipc = NULL; /* dummy */
static char program_name[] = "iscsiadm";
static char config_file[TARGET_NAME_MAXLEN];
+extern struct iscsi_ipc *ipc;
enum iscsiadm_mode {
MODE_DISCOVERY,
@@ -69,7 +72,9 @@ enum iscsiadm_op {
OP_DELETE = 0x2,
OP_UPDATE = 0x4,
OP_SHOW = 0x8,
- OP_NONPERSISTENT = 0x10
+ OP_NONPERSISTENT = 0x10,
+ OP_APPLY = 0x20,
+ OP_APPLY_ALL = 0x40
};
static struct option const long_options[] =
@@ -108,18 +113,18 @@ static void usage(int status)
program_name);
else {
printf("\
-iscsiadm -m discovery2 [ -hV ] [ -d debug_level ] [-P printlevel] [ -t type -p ip:port -I ifaceN ... [ -Dl ] ] | [ [ -p ip:port -t type] \
+iscsiadm -m discoverydb [ -hV ] [ -d debug_level ] [-P printlevel] [ -t type -p ip:port -I ifaceN ... [ -Dl ] ] | [ [ -p ip:port -t type] \
[ -o operation ] [ -n name ] [ -v value ] [ -lD ] ] \n\
iscsiadm -m discovery [ -hV ] [ -d debug_level ] [-P printlevel] [ -t type -p ip:port -I ifaceN ... [ -l ] ] | [ [ -p ip:port ] [ -l | -D ] ] \n\
iiscsiadm -m node [ -hV ] [ -d debug_level ] [ -P printlevel ] [ -L all,manual,automatic ] [ -U all,manual,automatic ] [ -S ] [ [ -T targetname -p ip:port -I ifaceN ] [ -l | -u | -R | -s] ] \
[ [ -o operation ] [ -n name ] [ -v value ] ]\n\
iscsiadm -m session [ -hV ] [ -d debug_level ] [ -P printlevel] [ -r sessionid | sysfsdir [ -R | -u | -s ] [ -o operation ] [ -n name ] [ -v value ] ]\n\
-iscsiadm -m iface [ -hV ] [ -d debug_level ] [ -P printlevel ] [ -I ifacename ] [ [ -o operation ] [ -n name ] [ -v value ] ]\n\
+iscsiadm -m iface [ -hV ] [ -d debug_level ] [ -P printlevel ] [ -I ifacename | -H hostno|MAC ] [ [ -o operation ] [ -n name ] [ -v value ] ]\n\
iscsiadm -m fw [ -l ]\n\
-iscsiadm -m host [ -P printlevel ] [ -H hostno ]\n\
+iscsiadm -m host [ -P printlevel ] [ -H hostno|MAC ]\n\
iscsiadm -k priority\n");
}
- exit(status == 0 ? 0 : -1);
+ exit(status);
}
static int
@@ -137,6 +142,10 @@ str_to_op(char *str)
op = OP_SHOW;
else if (!strcmp("nonpersistent", str))
op = OP_NONPERSISTENT;
+ else if (!strcmp("apply", str))
+ op = OP_APPLY;
+ else if (!strcmp("applyall", str))
+ op = OP_APPLY_ALL;
else
op = OP_NOOP;
@@ -212,7 +221,7 @@ static void kill_iscsid(int priority)
req.command = MGMT_IPC_IMMEDIATE_STOP;
rc = iscsid_exec_req(&req, &rsp, 0);
if (rc) {
- iscsid_handle_error(rc);
+ iscsi_err_print_msg(rc);
log_error("Could not stop iscsid. Trying sending iscsid "
"SIGTERM or SIGKILL signals manually\n");
}
@@ -251,12 +260,12 @@ static int print_ifaces(struct iface_rec
break;
default:
log_error("Invalid info level %d. Try 0 - 1.", info_level);
- return EINVAL;
+ return ISCSI_ERR_INVAL;
}
if (!num_found) {
log_error("No interfaces found.");
- err = ENODEV;
+ err = ISCSI_ERR_NO_OBJS_FOUND;
}
return err;
}
@@ -264,15 +273,10 @@ static int print_ifaces(struct iface_rec
static int
match_startup_mode(node_rec_t *rec, char *mode)
{
- /*
- * we always skip onboot because this should be handled by
- * something else
- */
- if (rec->startup == ISCSI_STARTUP_ONBOOT)
- return -1;
-
if ((!strcmp(mode, "automatic") &&
rec->startup == ISCSI_STARTUP_AUTOMATIC) ||
+ (!strcmp(mode, "onboot") &&
+ rec->startup == ISCSI_STARTUP_ONBOOT) ||
(!strcmp(mode, "manual") &&
rec->startup == ISCSI_STARTUP_MANUAL) ||
!strcmp(mode, "all"))
@@ -281,6 +285,8 @@ match_startup_mode(node_rec_t *rec, char
/* support conn or session startup params */
if ((!strcmp(mode, "automatic") &&
rec->conn[0].startup == ISCSI_STARTUP_AUTOMATIC) ||
+ (!strcmp(mode, "onboot") &&
+ rec->conn[0].startup == ISCSI_STARTUP_ONBOOT) ||
(!strcmp(mode, "manual") &&
rec->conn[0].startup == ISCSI_STARTUP_MANUAL) ||
!strcmp(mode, "all"))
@@ -294,13 +300,18 @@ for_each_session(struct node_rec *rec, i
{
int err, num_found = 0;
- err = iscsi_sysfs_for_each_session(rec, &num_found, fn);
+ if (rec && rec->session.info) {
+ num_found = 1;
+ err = fn(rec, rec->session.info);
+ } else {
+ err = iscsi_sysfs_for_each_session(rec, &num_found, fn);
+ }
if (err)
- log_error("Could not execute operation on all sessions. Err "
- "%d.", err);
+ log_error("Could not execute operation on all sessions: %s",
+ iscsi_err_to_str(err));
else if (!num_found) {
- log_error("No portal found.");
- err = ENODEV;
+ log_error("No session found.");
+ err = ISCSI_ERR_NO_OBJS_FOUND;
}
return err;
@@ -313,7 +324,7 @@ static int link_recs(void *data, struct
rec_copy = calloc(1, sizeof(*rec_copy));
if (!rec_copy)
- return ENOMEM;
+ return ISCSI_ERR_NOMEM;
memcpy(rec_copy, rec, sizeof(*rec_copy));
INIT_LIST_HEAD(&rec_copy->list);
list_add_tail(&rec_copy->list, list);
@@ -326,7 +337,6 @@ __logout_by_startup(void *data, struct l
{
char *mode = data;
node_rec_t rec;
- int rc = 0;
memset(&rec, 0, sizeof(node_rec_t));
if (idbm_rec_read(&rec, info->targetname, info->tpgt,
@@ -352,74 +362,188 @@ __logout_by_startup(void *data, struct l
if (rec.startup == ISCSI_STARTUP_ONBOOT)
return -1;
- if (!match_startup_mode(&rec, mode))
- rc = iscsi_logout_portal(info, list);
- return rc;
+ if (match_startup_mode(&rec, mode))
+ return -1;
+
+ return iscsi_logout_portal(info, list);
}
static int
logout_by_startup(char *mode)
{
int nr_found;
+ int rc;
if (!mode || !(!strcmp(mode, "automatic") || !strcmp(mode, "all") ||
!strcmp(mode,"manual"))) {
log_error("Invalid logoutall option %s.", mode);
- usage(0);
- return EINVAL;
+ usage(ISCSI_ERR_INVAL);
+ return ISCSI_ERR_INVAL;
}
- return iscsi_logout_portals(mode, &nr_found, 1, __logout_by_startup);
+ rc = iscsi_logout_portals(mode, &nr_found, 1, __logout_by_startup);
+ if (rc == ISCSI_ERR_NO_OBJS_FOUND)
+ log_error("No matching sessions found");
+ return rc;
+}
+
+struct startup_data {
+ char *mode;
+ struct list_head all_logins;
+ struct list_head leading_logins;
+};
+
+static int link_startup_recs(void *data, struct node_rec *rec)
+{
+ struct startup_data *startup = data;
+ struct node_rec *rec_copy;
+
+ if (match_startup_mode(rec, startup->mode))
+ return -1;
+
+ rec_copy = calloc(1, sizeof(*rec_copy));
+ if (!rec_copy)
+ return ISCSI_ERR_NOMEM;
+ memcpy(rec_copy, rec, sizeof(*rec_copy));
+ INIT_LIST_HEAD(&rec_copy->list);
+
+ if (rec_copy->leading_login)
+ list_add_tail(&rec_copy->list, &startup->leading_logins);
+ else
+ list_add_tail(&rec_copy->list, &startup->all_logins);
+ return 0;
}
-/*
- * TODO: merged this and logout into the common for_each_rec by making
- * the matching more generic
- */
static int
-__login_by_startup(void *data, struct list_head *list, struct node_rec *rec)
+__do_leading_login(void *data, struct list_head *list, struct node_rec *rec)
{
- char *mode = data;
- /*
- * we always skip onboot because this should be handled by
- * something else
- */
- if (rec->startup == ISCSI_STARTUP_ONBOOT)
+ struct iface_rec *pattern_iface = data;
+ int nr_found;
+
+ /* Skip any records that do not match the pattern iface */
+ if (!iface_match(pattern_iface, &rec->iface))
return -1;
- if (match_startup_mode(rec, mode))
+ /*
+ * If there is an existing session that matcthes the target,
+ * the leading login is complete.
+ */
+ if (iscsi_sysfs_for_each_session(rec, &nr_found, iscsi_match_target)) {
+ log_debug(1, "Skipping %s: Already a session for that target",
+ rec->name);
return -1;
+ }
- iscsi_login_portal(NULL, list, rec);
- return 0;
+ /* No existing session: Attempt a login. */
+ return iscsi_login_portal(NULL, list, rec);
}
static int
login_by_startup(char *mode)
{
- int nr_found = 0, rc, err;
- struct list_head rec_list;
+ int nr_found = 0, err, rc;
+ struct startup_data startup;
if (!mode || !(!strcmp(mode, "automatic") || !strcmp(mode, "all") ||
- !strcmp(mode,"manual"))) {
+ !strcmp(mode,"manual") || !strcmp(mode, "onboot"))) {
log_error("Invalid loginall option %s.", mode);
- usage(0);
- return EINVAL;
+ usage(ISCSI_ERR_INVAL);
+ return ISCSI_ERR_INVAL;
}
- INIT_LIST_HEAD(&rec_list);
- rc = idbm_for_each_rec(&nr_found, &rec_list, link_recs);
- err = iscsi_login_portals(mode, &nr_found, 1, &rec_list,
- __login_by_startup);
- if (err && !rc)
- rc = err;
+ /*
+ * Filter all node records that match the given 'mode' into 2 lists:
+ * Those with leading_login enabled, and those without.
+ */
+ startup.mode = mode;
+ INIT_LIST_HEAD(&startup.all_logins);
+ INIT_LIST_HEAD(&startup.leading_logins);
+ err = idbm_for_each_rec(&nr_found, &startup, link_startup_recs);
+ if (err && (!list_empty(&startup.all_logins) ||
+ !list_empty(&startup.leading_logins)))
+ /* log msg and try to log into what we found */
+ log_error("Could not read all records: %s",
+ iscsi_err_to_str(err));
+ else if (list_empty(&startup.all_logins) &&
+ list_empty(&startup.leading_logins)) {
+ if (err) {
+ log_error("Could not read node DB: %s.",
+ iscsi_err_to_str(err));
+ } else {
+ log_error("No records found");
+ err = ISCSI_ERR_NO_OBJS_FOUND;
+ }
+ return err;
+ }
+ rc = err;
- if (rc)
- log_error("Could not log into all portals. Err %d.", rc);
- else if (!nr_found) {
- log_error("No records found!");
- rc = ENODEV;
+ if (!list_empty(&startup.all_logins)) {
+ log_debug(1, "Logging into normal (non-leading-login) portals");
+ /* Login all regular (non-leading-login) portals first */
+ err = iscsi_login_portals(NULL, &nr_found, 1,
+ &startup.all_logins, iscsi_login_portal);
+ if (err)
+ log_error("Could not log into all portals");
+ if (err && !rc)
+ rc = err;
}
+
+ if (!list_empty(&startup.leading_logins)) {
+ /*
+ * For each iface in turn, try to login all portals on that
+ * iface that do not already have a session present.
+ */
+ struct iface_rec *pattern_iface, *tmp_iface;
+ struct node_rec *rec, *tmp_rec;
+ struct list_head iface_list;
+ int missed_leading_login = 0;
+ log_debug(1, "Logging into leading-login portals");
+ INIT_LIST_HEAD(&iface_list);
+ iface_link_ifaces(&iface_list);
+ list_for_each_entry_safe(pattern_iface, tmp_iface, &iface_list,
+ list) {
+ log_debug(1, "Establishing leading-logins via iface %s",
+ pattern_iface->name);
+ err = iscsi_login_portals_safe(pattern_iface, &nr_found,
+ 1,
+ &startup.leading_logins,
+ __do_leading_login);
+ if (err)
+ log_error("Could not log into all portals on "
+ "%s, trying next interface",
+ pattern_iface->name);
+
+ /*
+ * Note: We always try all iface records in case there
+ * are targets that are associated with only a subset
+ * of iface records. __do_leading_login already
+ * prevents duplicate sessions if an iface has succeded
+ * for a particular target.
+ */
+ }
+ /*
+ * Double-check that all leading-login portals have at least
+ * one session
+ */
+ list_for_each_entry_safe(rec, tmp_rec, &startup.leading_logins,
+ list) {
+ if (!iscsi_sysfs_for_each_session(rec, &nr_found,
+ iscsi_match_target))
+ missed_leading_login++;
+ /*
+ * Cleanup the list, since 'iscsi_login_portals_safe'
+ * does not
+ */
+ list_del(&rec->list);
+ free(rec);
+ }
+ if (missed_leading_login) {
+ log_error("Could not login all leading-login portals");
+ if (!rc)
+ rc = ISCSI_ERR_FATAL_LOGIN;
+ }
+ }
+
return rc;
}
@@ -442,30 +566,22 @@ static int iscsi_logout_matched_portal(v
if (!iscsi_match_session(pattern_rec, info))
return -1;
- /* we do not support this yet */
- if (t->caps & CAP_FW_DB) {
- log_error("Could not logout session of [sid: %d, "
- "target: %s, portal: %s,%d].", info->sid,
- info->targetname, info->persistent_address,
- info->port);
- log_error("Logout not supported for driver: %s.", t->name);
- return -1;
- }
return iscsi_logout_portal(info, list);
}
-static int iface_fn(void *data, node_rec_t *rec)
+static int rec_match_fn(void *data, node_rec_t *rec)
{
struct rec_op_data *op_data = data;
if (!__iscsi_match_session(op_data->match_rec, rec->name,
rec->conn[0].address, rec->conn[0].port,
- &rec->iface))
+ &rec->iface, rec->session.sid))
return -1;
return op_data->fn(op_data->data, rec);
}
-static int for_each_rec(struct node_rec *rec, void *data, idbm_iface_op_fn *fn)
+static int __for_each_matched_rec(int verbose, struct node_rec *rec,
+ void *data, idbm_iface_op_fn *fn)
{
struct rec_op_data op_data;
int nr_found = 0, rc;
@@ -475,30 +591,51 @@ static int for_each_rec(struct node_rec
op_data.match_rec = rec;
op_data.fn = fn;
- rc = idbm_for_each_rec(&nr_found, &op_data, iface_fn);
+ rc = idbm_for_each_rec(&nr_found, &op_data, rec_match_fn);
if (rc) {
- log_error("Could not execute operation on all "
- "records. Err %d.", rc);
+ if (verbose)
+ log_error("Could not execute operation on all "
+ "records: %s", iscsi_err_to_str(rc));
} else if (!nr_found) {
- log_error("no records found!");
- rc = ENODEV;
+ if (verbose)
+ log_error("No records found");
+ rc = ISCSI_ERR_NO_OBJS_FOUND;
}
return rc;
}
+static int for_each_matched_rec(struct node_rec *rec, void *data,
+ idbm_iface_op_fn *fn)
+{
+ return __for_each_matched_rec(1, rec, data, fn);
+}
+
+
static int login_portals(struct node_rec *pattern_rec)
{
struct list_head rec_list;
- int err, ret, nr_found;
+ int nr_found, rc, err;
INIT_LIST_HEAD(&rec_list);
- ret = for_each_rec(pattern_rec, &rec_list, link_recs);
- err = iscsi_login_portals(NULL, &nr_found, 1, &rec_list,
+ err = for_each_matched_rec(pattern_rec, &rec_list, link_recs);
+ if (err == ISCSI_ERR_NO_OBJS_FOUND)
+ return err;
+ else if (err && list_empty(&rec_list))
+ return err;
+
+ rc = err;
+ /* if there is an err but some recs then try to login to what we have */
+
+ err = iscsi_login_portals(pattern_rec, &nr_found, 1, &rec_list,
iscsi_login_portal);
- if (err && !ret)
- ret = err;
- return ret;
+ if (err)
+ log_error("Could not log into all portals");
+
+ if (err && !rc)
+ rc = err;
+
+ return rc;
}
static int print_nodes(int info_level, struct node_rec *rec)
@@ -509,17 +646,16 @@ static int print_nodes(int info_level, s
switch (info_level) {
case 0:
case -1:
- if (for_each_rec(rec, NULL, idbm_print_node_flat))
- rc = -1;
+ rc = for_each_matched_rec(rec, NULL, idbm_print_node_flat);
break;
case 1:
memset(&tmp_rec, 0, sizeof(node_rec_t));
- if (for_each_rec(rec, &tmp_rec, idbm_print_node_and_iface_tree))
- rc = -1;
+ rc = for_each_matched_rec(rec, &tmp_rec,
+ idbm_print_node_and_iface_tree);
break;
default:
log_error("Invalid info level %d. Try 0 or 1.", info_level);
- rc = -1;
+ rc = ISCSI_ERR_INVAL;
}
return rc;
@@ -586,7 +722,7 @@ session_stats(void *data, struct session
rc = iscsid_exec_req(&req, &rsp, 1);
if (rc)
- return EIO;
+ return rc;
printf("Stats for session [sid: %d, target: %s, portal: "
"%s,%d]\n",
@@ -665,14 +801,14 @@ static int add_static_rec(int *found, ch
rec = calloc(1, sizeof(*rec));
if (!rec) {
log_error("Could not allocate memory for node addition");
- rc = ENOMEM;
+ rc = ISCSI_ERR_NOMEM;
goto done;
}
drec = calloc(1, sizeof(*drec));
if (!drec) {
log_error("Could not allocate memory for node addition");
- rc = ENOMEM;
+ rc = ISCSI_ERR_NOMEM;
goto free_rec;
}
drec->type = DISCOVERY_TYPE_STATIC;
@@ -715,10 +851,10 @@ static int add_static_portal(int *found,
if (strlen(rec->conn[0].address) &&
strcmp(rec->conn[0].address, ip))
- return 0;
+ return -1;
if (rec->conn[0].port != -1 && rec->conn[0].port != port)
- return 0;
+ return -1;
return add_static_rec(found, targetname, tpgt, ip, port,
&rec->iface);
@@ -733,7 +869,7 @@ static int add_static_node(int *found, v
goto search;
if (strcmp(rec->name, targetname))
- return 0;
+ return -1;
if (!strlen(rec->conn[0].address))
goto search;
@@ -751,11 +887,8 @@ static int add_static_recs(struct node_r
int rc, nr_found = 0;
rc = idbm_for_each_node(&nr_found, rec, add_static_node);
- if (rc) {
- log_error("Error while adding records. DB may be in an "
- "inconsistent state. Err %d", rc);
- return rc;
- }
+ if (rc)
+ goto done;
/* success */
if (nr_found > 0)
return 0;
@@ -765,13 +898,12 @@ static int add_static_recs(struct node_r
rc = add_static_rec(&nr_found, rec->name, rec->tpgt,
rec->conn[0].address, rec->conn[0].port,
&rec->iface);
- if (rc)
- goto done;
- return 0;
+ if (!rc)
+ return 0;
}
done:
- printf("No records added.\n");
- return ENODEV;
+ log_error("Error while adding record: %s", iscsi_err_to_str(rc));
+ return rc;
}
/*
@@ -799,7 +931,7 @@ static int delete_node(void *data, struc
"using it. Logout session then rerun command to "
"remove record.", rec->iface.name, rec->name,
rec->conn[0].address, rec->conn[0].port);
- return EINVAL;
+ return ISCSI_ERR_SESS_EXISTS;
}
return idbm_delete_node(rec);
@@ -822,18 +954,18 @@ static int delete_stale_rec(void *data,
* if we are not from the same discovery source
* ignore it
*/
- return 0;
+ return -1;
if (__iscsi_match_session(rec,
new_rec->name,
new_rec->conn[0].address,
new_rec->conn[0].port,
- &new_rec->iface))
- return 0;
+ &new_rec->iface,
+ new_rec->session.sid))
+ return -1;
}
/* if there is a error we can continue on */
- delete_node(NULL, rec);
- return 0;
+ return delete_node(NULL, rec);
}
static int
@@ -918,8 +1050,12 @@ do_software_sendtargets(discovery_rec_t
rc = idbm_bind_ifaces_to_nodes(discovery_sendtargets, drec, ifaces,
&rec_list);
if (rc) {
- log_error("Could not perform SendTargets discovery.");
+ log_error("Could not perform SendTargets discovery: %s",
+ iscsi_err_to_str(rc));
return rc;
+ } else if (list_empty(&rec_list)) {
+ log_error("No portals found");
+ return ISCSI_ERR_NO_OBJS_FOUND;
}
rc = exec_disc_op_on_recs(drec, &rec_list, info_level, do_login, op);
@@ -957,7 +1093,6 @@ do_sendtargets(discovery_rec_t *drec, st
free(iface);
continue;
}
-
host_no = iscsi_sysfs_get_host_no_from_hwinfo(iface, &rc);
if (rc || host_no == -1) {
log_debug(1, "Could not match iface" iface_fmt " to "
@@ -986,7 +1121,7 @@ do_sendtargets(discovery_rec_t *drec, st
}
if (list_empty(ifaces))
- return ENODEV;
+ return ISCSI_ERR_NO_OBJS_FOUND;
sw_st:
return do_software_sendtargets(drec, ifaces, info_level, do_login,
@@ -1013,8 +1148,12 @@ static int do_isns(discovery_rec_t *drec
rc = idbm_bind_ifaces_to_nodes(discovery_isns, drec, ifaces,
&rec_list);
if (rc) {
- log_error("Could not perform iSNS discovery.");
+ log_error("Could not perform iSNS discovery: %s",
+ iscsi_err_to_str(rc));
return rc;
+ } else if (list_empty(&rec_list)) {
+ log_error("No portals found");
+ return ISCSI_ERR_NO_OBJS_FOUND;
}
rc = exec_disc_op_on_recs(drec, &rec_list, info_level, do_login, op);
@@ -1053,10 +1192,97 @@ static void catch_sigint( int signo ) {
exit(1);
}
+static int iface_apply_net_config(struct iface_rec *iface, int op)
+{
+ int rc = ISCSI_ERR;
+ uint32_t host_no;
+ int param_count;
+ int param_used;
+ int iface_all = 0;
+ int i;
+ struct iovec *iovs = NULL;
+ struct iovec *iov = NULL;
+ struct iscsi_transport *t = NULL;
+ int fd;
+
+ log_debug(8, "Calling iscsid, to apply net config for"
+ "iface.name = %s\n", iface->name);
+
+ if (op == OP_APPLY_ALL)
+ iface_all = 1;
+
+ param_count = iface_get_param_count(iface, iface_all);
+ if (!param_count) {
+ log_error("Nothing to configure.");
+ return ISCSI_SUCCESS;
+ }
+
+ /*
+ * TODO: create a nicer interface where the caller does not have
+ * know the packet/hdr details
+ */
+
+ /* +2 for event and nlmsghdr */
+ param_count += 2;
+ iovs = calloc((param_count * sizeof(struct iovec)),
+ sizeof(char));
+ if (!iovs) {
+ log_error("Out of Memory.");
+ return ISCSI_ERR_NOMEM;
+ }
+
+ /* param_used gives actual number of iovecs used for netconfig */
+ param_used = iface_build_net_config(iface, iface_all, iovs);
+ if (!param_used) {
+ log_error("Build netconfig failed.");
+ goto free_buf;
+ }
+
+ t = iscsi_sysfs_get_transport_by_name(iface->transport_name);
+ if (!t) {
+ log_error("Can't find transport.");
+ goto free_buf;
+ }
+
+ host_no = iscsi_sysfs_get_host_no_from_hwinfo(iface, &rc);
+ if (host_no == -1) {
+ log_error("Can't find host_no.");
+ goto free_buf;
+ }
+ rc = ISCSI_ERR;
+
+ fd = ipc->ctldev_open();
+ if (fd < 0) {
+ log_error("Netlink open failed.");
+ goto free_buf;
+ }
+
+ rc = ipc->set_net_config(t->handle, host_no, iovs, param_count);
+ if (rc < 0)
+ log_error("Set net_config failed. errno=%d", errno);
+
+ ipc->ctldev_close();
+
+free_buf:
+ /* start at 2, because 0 is for nlmsghdr and 1 for event */
+ iov = iovs + 2;
+ for (i = 0; i < param_used; i++, iov++) {
+ if (iov->iov_base)
+ free(iov->iov_base);
+ }
+
+ free(iovs);
+ if (rc)
+ return ISCSI_ERR;
+ return ISCSI_SUCCESS;
+}
+
/* TODO: merge iter helpers and clean them up, so we can use them here */
static int exec_iface_op(int op, int do_show, int info_level,
- struct iface_rec *iface, char *name, char *value)
+ struct iface_rec *iface, uint32_t host_no,
+ char *name, char *value)
{
+ struct host_info hinfo;
struct db_set_param set_param;
struct node_rec *rec = NULL;
int rc = 0;
@@ -1071,7 +1297,7 @@ static int exec_iface_op(int op, int do_
rec = idbm_create_rec(NULL, -1, NULL, -1, iface, 0);
if (rec && iscsi_check_for_running_session(rec)) {
- rc = EBUSY;
+ rc = ISCSI_ERR_SESS_EXISTS;
goto new_fail;
}
@@ -1088,19 +1314,19 @@ new_fail:
if (!iface) {
log_error("Could not delete interface. No interface "
"passed in.");
- return EINVAL;
+ return ISCSI_ERR_INVAL;
}
rec = idbm_create_rec(NULL, -1, NULL, -1, iface, 1);
if (!rec) {
- rc = EINVAL;
+ rc = ISCSI_ERR_INVAL;
goto delete_fail;
}
/* logout and delete records using it first */
- rc = for_each_rec(rec, NULL, delete_node);
- if (rc)
- break;
+ rc = __for_each_matched_rec(0, rec, NULL, delete_node);
+ if (rc && rc != ISCSI_ERR_NO_OBJS_FOUND)
+ goto delete_fail;
rc = iface_conf_delete(iface);
if (rc)
@@ -1109,20 +1335,19 @@ new_fail:
printf("%s unbound and deleted.\n", iface->name);
break;
delete_fail:
- log_error("Could not delete iface %s. A session is "
- "is using it or it could not be found.",
- iface->name);
+ log_error("Could not delete iface %s: %s", iface->name,
+ iscsi_err_to_str(rc));
break;
case OP_UPDATE:
if (!iface || !name || !value) {
log_error("Update requires name, value, and iface.");
- rc = EINVAL;
+ rc = ISCSI_ERR_INVAL;
break;
}
rec = idbm_create_rec(NULL, -1, NULL, -1, iface, 1);
if (!rec) {
- rc = EINVAL;
+ rc = ISCSI_ERR_INVAL;
goto update_fail;
}
@@ -1136,7 +1361,7 @@ delete_fail:
log_error("Can not update "
"iface.iscsi_ifacename. Delete it, "
"and then create a new one.");
- rc = EINVAL;
+ rc = ISCSI_ERR_INVAL;
break;
}
@@ -1146,7 +1371,7 @@ delete_fail:
"from hwaddress to net_ifacename. ");
log_error("You must delete the interface and "
"create a new one");
- rc = EINVAL;
+ rc = ISCSI_ERR_INVAL;
break;
}
@@ -1156,7 +1381,7 @@ delete_fail:
"from net_ifacename to hwaddress. ");
log_error("You must delete the interface and "
"create a new one");
- rc = EINVAL;
+ rc = ISCSI_ERR_INVAL;
break;
}
set_param.name = name;
@@ -1167,23 +1392,74 @@ delete_fail:
if (rc)
goto update_fail;
- rc = for_each_rec(rec, &set_param, idbm_node_set_param);
- if (rc)
- break;
+ rc = __for_each_matched_rec(0, rec, &set_param,
+ idbm_node_set_param);
+ if (rc == ISCSI_ERR_NO_OBJS_FOUND)
+ rc = 0;
+ else if (rc)
+ goto update_fail;
printf("%s updated.\n", iface->name);
break;
update_fail:
- log_error("Could not update iface %s. A session is "
- "is using it or it could not be found.",
- iface->name);
+ log_error("Could not update iface %s: %s",
+ iface->name, iscsi_err_to_str(rc));
+ break;
+ case OP_APPLY:
+ if (!iface) {
+ log_error("Apply requires iface.");
+ rc = ISCSI_ERR_INVAL;
+ break;
+ }
+ rc = iface_conf_read(iface);
+ if (rc) {
+ log_error("Could not read iface %s (%d).",
+ iface->name, rc);
+ break;
+ }
+
+ rc = iface_apply_net_config(iface, op);
+ if (rc) {
+ log_error("Could not apply net configuration: %s",
+ iscsi_err_to_str(rc));
+ break;
+ }
+ printf("%s applied.\n", iface->name);
+ break;
+ case OP_APPLY_ALL:
+ if (host_no == -1) {
+ log_error("Applyall requires a host number or MAC "
+ "passed in with the --host argument.");
+ rc = ISCSI_ERR_INVAL;
+ break;
+ }
+
+ /*
+ * Need to get other iface info like transport.
+ */
+ memset(&hinfo, 0, sizeof(struct host_info));
+ hinfo.host_no = host_no;
+ if (iscsi_sysfs_get_hostinfo_by_host_no(&hinfo)) {
+ log_error("Could not match host%u to ifaces.", host_no);
+ rc = ISCSI_ERR_INVAL;
+ break;
+ }
+ rc = iface_apply_net_config(&hinfo.iface, op);
+ if (rc) {
+ log_error("Could not apply net configuration: %s",
+ iscsi_err_to_str(rc));
+ break;
+ }
+
+ printf("Applied settings to ifaces attached to host%u.\n",
+ host_no);
break;
default:
if (!iface || (iface && info_level > 0)) {
if (op == OP_NOOP || op == OP_SHOW)
rc = print_ifaces(iface, info_level);
else
- rc = EINVAL;
+ rc = ISCSI_ERR_INVAL;
} else {
rc = iface_conf_read(iface);
if (!rc)
@@ -1209,38 +1485,35 @@ static int exec_node_op(int op, int do_l
struct db_set_param set_param;
if (rec)
- log_debug(2, "%s: %s:%s node [%s,%s,%d]", __FUNCTION__,
+ log_debug(2, "%s: %s:%s node [%s,%s,%d] sid %u", __FUNCTION__,
rec->iface.transport_name, rec->iface.name,
- rec->name, rec->conn[0].address, rec->conn[0].port);
+ rec->name, rec->conn[0].address, rec->conn[0].port,
+ rec->session.sid);
if (op == OP_NEW) {
- if (add_static_recs(rec))
- rc = -1;
+ rc = add_static_recs(rec);
goto out;
}
if (do_rescan) {
- if (for_each_session(rec, rescan_portal))
- rc = -1;
+ rc = for_each_session(rec, rescan_portal);
goto out;
}
if (do_stats) {
- if (for_each_session(rec, session_stats))
- rc = -1;
+ rc = for_each_session(rec, session_stats);
goto out;
}
if (do_login && do_logout) {
- log_error("either login or logout at the time allowed!");
- rc = -1;
+ log_error("Invalid parameters. Both login and logout passed in");
+ rc = ISCSI_ERR_INVAL;
goto out;
}
if ((do_login || do_logout) && op > OP_NOOP) {
- log_error("either operation or login/logout "
- "at the time allowed!");
- rc = -1;
+ log_error("Invalid parameters. Login/logout and op passed in");
+ rc = ISCSI_ERR_INVAL;
goto out;
}
@@ -1252,30 +1525,29 @@ static int exec_node_op(int op, int do_l
}
if (do_login) {
- if (login_portals(rec))
- rc = -1;
+ rc = login_portals(rec);
goto out;
}
if (do_logout) {
int nr_found;
- if (iscsi_logout_portals(rec, &nr_found, 1,
- iscsi_logout_matched_portal))
- rc = -1;
+ rc = iscsi_logout_portals(rec, &nr_found, 1,
+ iscsi_logout_matched_portal);
+ if (rc == ISCSI_ERR_NO_OBJS_FOUND)
+ log_error("No matching sessions found");
goto out;
}
if (op == OP_NOOP || (!do_login && !do_logout && op == OP_SHOW)) {
- if (for_each_rec(rec, &do_show, idbm_print_node_info))
- rc = -1;
+ rc = for_each_matched_rec(rec, &do_show, idbm_print_node_info);
goto out;
}
if (op == OP_UPDATE) {
if (!name || !value) {
log_error("update requires name and value");
- rc = -1;
+ rc = ISCSI_ERR_INVAL;
goto out;
}
@@ -1284,7 +1556,7 @@ static int exec_node_op(int op, int do_l
strcmp(name, "iface.transport_name")) {
log_error("Cannot modify %s. Use iface mode to update "
"this value.", name);
- rc = -1;
+ rc = ISCSI_ERR_INVAL;
goto out;
}
@@ -1304,7 +1576,7 @@ static int exec_node_op(int op, int do_l
"transport name while a session "
"is using it. Log out the session "
"then update record.");
- rc = -1;
+ rc = ISCSI_ERR_SESS_EXISTS;
goto out;
}
}
@@ -1312,16 +1584,14 @@ static int exec_node_op(int op, int do_l
set_param.name = name;
set_param.value = value;
- if (for_each_rec(rec, &set_param, idbm_node_set_param))
- rc = -1;
+ rc = for_each_matched_rec(rec, &set_param, idbm_node_set_param);
goto out;
} else if (op == OP_DELETE) {
- if (for_each_rec(rec, NULL, delete_node))
- rc = -1;
+ rc = for_each_matched_rec(rec, NULL, delete_node);
goto out;
} else {
log_error("operation is not supported.");
- rc = -1;
+ rc = ISCSI_ERR_INVAL;
goto out;
}
out:
@@ -1443,7 +1713,7 @@ static int exec_fw_op(discovery_rec_t *d
if (!rec) {
log_error("Could not convert firmware info to "
"node record.\n");
- rc = ENOMEM;
+ rc = ISCSI_ERR_NOMEM;
break;
}
@@ -1493,9 +1763,9 @@ static void setup_drec_defaults(int type
* and will read and add a drec, and perform discovery if needed.
*
* returns:
- * -1 - error
+ * Greater than 0 - error
* 0 - op/discovery completed
- * 1 - exec db op
+ * -1 - exec db op
*/
static int exec_discover(int disc_type, char *ip, int port,
struct list_head *ifaces, int info_level,
@@ -1506,15 +1776,16 @@ static int exec_discover(int disc_type,
if (ip == NULL) {
log_error("Please specify portal as <ipaddr>[:<ipport>]");
- return -1;
+ return ISCSI_ERR_INVAL;
}
if (op & OP_NEW && !do_discover) {
setup_drec_defaults(disc_type, ip, port, drec);
- if (idbm_add_discovery(drec)) {
+ rc = idbm_add_discovery(drec);
+ if (rc) {
log_error("Could not add new discovery record.");
- return -1;
+ return rc;
} else {
printf("New discovery record for [%s,%d] added.\n", ip,
port);
@@ -1527,7 +1798,7 @@ static int exec_discover(int disc_type,
if (!do_discover) {
log_error("Discovery record [%s,%d] not found.",
ip, port);
- return -1;
+ return rc;
}
/* Just add default rec for user */
@@ -1539,11 +1810,11 @@ static int exec_discover(int disc_type,
if (rc) {
log_error("Could not add new discovery "
"record.");
- return -1;
+ return rc;
}
}
} else if (!do_discover)
- return 1;
+ return -1;
rc = 0;
switch (disc_type) {
@@ -1563,9 +1834,7 @@ static int exec_discover(int disc_type,
break;
}
- if (rc)
- return -1;
- return 0;
+ return rc;
}
static int exec_disc2_op(int disc_type, char *ip, int port,
@@ -1587,12 +1856,12 @@ static int exec_disc2_op(int disc_type,
rc = exec_discover(disc_type, ip, port, ifaces, info_level,
do_login, do_discover, op, &drec);
- if (rc == 1)
+ if (rc < 0)
goto do_db_op;
goto done;
case DISCOVERY_TYPE_SLP:
log_error("SLP discovery is not fully implemented yet.");
- rc = -1;
+ rc = ISCSI_ERR_INVAL;
goto done;
case DISCOVERY_TYPE_ISNS:
if (port < 0)
@@ -1600,29 +1869,30 @@ static int exec_disc2_op(int disc_type,
rc = exec_discover(disc_type, ip, port, ifaces, info_level,
do_login, do_discover, op, &drec);
- if (rc == 1)
+ if (rc < 0)
goto do_db_op;
goto done;
case DISCOVERY_TYPE_FW:
if (!do_discover) {
log_error("Invalid command. Possibly missing "
"--discover argument.");
- rc = -1;
+ rc = ISCSI_ERR_INVAL;
goto done;
}
drec.type = DISCOVERY_TYPE_FW;
- if (exec_fw_op(&drec, ifaces, info_level, do_login, op))
- rc = -1;
+ rc = exec_fw_op(&drec, ifaces, info_level, do_login, op);
goto done;
default:
- rc = -1;
+ rc = ISCSI_ERR_INVAL;
if (!ip) {
if (op == OP_NOOP || op == OP_SHOW) {
if (idbm_print_all_discovery(info_level))
/* successfully found some recs */
rc = 0;
+ else
+ rc = ISCSI_ERR_NO_OBJS_FOUND;
} else
log_error("Invalid operation. Operation not "
"supported.");
@@ -1640,29 +1910,27 @@ do_db_op:
if (op == OP_NOOP || op == OP_SHOW) {
if (!idbm_print_discovery_info(&drec, do_show)) {
- log_error("No records found!");
- rc = -1;
+ log_error("No records found");
+ rc = ISCSI_ERR_NO_OBJS_FOUND;
}
} else if (op == OP_DELETE) {
- if (idbm_delete_discovery(&drec)) {
+ rc = idbm_delete_discovery(&drec);
+ if (rc)
log_error("Unable to delete record!");
- rc = -1;
- }
} else if (op == OP_UPDATE) {
struct db_set_param set_param;
if (!name || !value) {
log_error("Update requires name and value.");
- rc = -1;
+ rc = ISCSI_ERR_INVAL;
goto done;
}
set_param.name = name;
set_param.value = value;
- if (idbm_discovery_set_param(&set_param, &drec))
- rc = -1;
+ rc = idbm_discovery_set_param(&set_param, &drec);
} else {
log_error("Operation is not supported.");
- rc = -1;
+ rc = ISCSI_ERR_INVAL;
goto done;
}
done:
@@ -1689,7 +1957,7 @@ static int exec_disc_op(int disc_type, c
if (ip == NULL) {
log_error("Please specify portal as "
"<ipaddr>[:<ipport>]");
- rc = -1;
+ rc = ISCSI_ERR_INVAL;
goto done;
}
@@ -1697,21 +1965,20 @@ static int exec_disc_op(int disc_type, c
strlcpy(drec.address, ip, sizeof(drec.address));
drec.port = port;
- if (do_sendtargets(&drec, ifaces, info_level,
- do_login, op, 1)) {
- rc = -1;
+ rc = do_sendtargets(&drec, ifaces, info_level,
+ do_login, op, 1);
+ if (rc)
goto done;
- }
break;
case DISCOVERY_TYPE_SLP:
log_error("SLP discovery is not fully implemented yet.");
- rc = -1;
+ rc = ISCSI_ERR_INVAL;
break;
case DISCOVERY_TYPE_ISNS:
if (!ip) {
log_error("Please specify portal as "
"<ipaddr>:[<ipport>]");
- rc = -1;
+ rc = ISCSI_ERR_INVAL;
goto done;
}
@@ -1721,15 +1988,13 @@ static int exec_disc_op(int disc_type, c
else
drec.port = port;
- if (do_isns(&drec, ifaces, info_level, do_login, op)) {
- rc = -1;
+ rc = do_isns(&drec, ifaces, info_level, do_login, op);
+ if (rc)
goto done;
- }
break;
case DISCOVERY_TYPE_FW:
drec.type = DISCOVERY_TYPE_FW;
- if (exec_fw_op(&drec, ifaces, info_level, do_login, op))
- rc = -1;
+ rc = exec_fw_op(&drec, ifaces, info_level, do_login, op);
break;
default:
if (ip) {
@@ -1749,42 +2014,41 @@ static int exec_disc_op(int disc_type, c
ip, port)) {
log_error("Discovery record [%s,%d] "
"not found!", ip, port);
- rc = -1;
+ rc = ISCSI_ERR_INVAL;
goto done;
}
if ((do_discover || do_login) &&
drec.type == DISCOVERY_TYPE_SENDTARGETS) {
- do_sendtargets(&drec, ifaces, info_level,
- do_login, op, 0);
+ rc = do_sendtargets(&drec, ifaces, info_level,
+ do_login, op, 0);
} else if (op == OP_NOOP || op == OP_SHOW) {
if (!idbm_print_discovery_info(&drec,
do_show)) {
- log_error("No records found!");
- rc = -1;
+ log_error("No records found");
+ rc = ISCSI_ERR_NO_OBJS_FOUND;
}
} else if (op == OP_DELETE) {
- if (idbm_delete_discovery(&drec)) {
+ rc = idbm_delete_discovery(&drec);
+ if (rc)
log_error("Unable to delete record!");
- rc = -1;
- }
} else if (op == OP_UPDATE || op == OP_NEW) {
log_error("Operations new and update for "
"discovery mode is not supported. "
"Use discoverydb mode.");
- rc = -1;
+ rc = ISCSI_ERR_INVAL;
goto done;
} else {
log_error("Invalid operation.");
- rc = -1;
+ rc = ISCSI_ERR_INVAL;
goto done;
}
} else if (op == OP_NOOP || op == OP_SHOW) {
if (!idbm_print_all_discovery(info_level))
- rc = -1;
+ rc = ISCSI_ERR_NO_OBJS_FOUND;
goto done;
} else {
log_error("Invalid operation.");
- rc = -1;
+ rc = ISCSI_ERR_INVAL;
goto done;
}
/* fall through */
@@ -1794,6 +2058,30 @@ done:
return rc;
}
+static uint32_t parse_host_info(char *optarg, int *rc)
+{
+ int err = 0;
+ uint32_t host_no = -1;
+
+ *rc = 0;
+ if (strstr(optarg, ":")) {
+ host_no = iscsi_sysfs_get_host_no_from_hwaddress(optarg,
+ &err);
+ if (err) {
+ log_error("Could not match MAC to host.");
+ *rc = ISCSI_ERR_INVAL;
+ }
+ } else {
+ host_no = strtoul(optarg, NULL, 10);
+ if (errno) {
+ log_error("Invalid host no %s. %s.",
+ optarg, strerror(errno));
+ *rc = ISCSI_ERR_INVAL;
+ }
+ }
+ return host_no;
+}
+
int
main(int argc, char **argv)
{
@@ -1837,7 +2125,7 @@ main(int argc, char **argv)
log_error("Invalid killiscsid priority %d "
"Priority must be greater than or "
"equal to zero.", killiscsid);
- rc = -1;
+ rc = ISCSI_ERR_INVAL;
goto free_ifaces;
}
break;
@@ -1849,7 +2137,7 @@ main(int argc, char **argv)
if (op == OP_NOOP) {
log_error("can not recognize operation: '%s'",
optarg);
- rc = -1;
+ rc = ISCSI_ERR_INVAL;
goto free_ifaces;
}
break;
@@ -1860,21 +2148,16 @@ main(int argc, char **argv)
value = optarg;
break;
case 'H':
- errno = 0;
- host_no = strtoul(optarg, NULL, 10);
- if (errno) {
- log_error("invalid host no %s. %s.",
- optarg, strerror(errno));
- rc = -1;
+ host_no = parse_host_info(optarg, &rc);
+ if (rc)
goto free_ifaces;
- }
break;
case 'r':
sid = iscsi_sysfs_get_sid_from_path(optarg);
if (sid < 0) {
log_error("invalid sid '%s'",
optarg);
- rc = -1;
+ rc = ISCSI_ERR_INVAL;
goto free_ifaces;
}
break;
@@ -1921,15 +2204,14 @@ main(int argc, char **argv)
break;
case 'I':
iface = iface_alloc(optarg, &rc);
- if (rc == EINVAL) {
+ if (rc == ISCSI_ERR_INVAL) {
printf("Invalid iface name %s. Must be from "
"1 to %d characters.\n",
optarg, ISCSI_MAX_IFACE_LEN - 1);
- rc = -1;
goto free_ifaces;
} else if (!iface || rc) {
printf("Could not add iface %s.", optarg);
- rc = -1;
+ rc = ISCSI_ERR_INVAL;
goto free_ifaces;
}
@@ -1947,7 +2229,7 @@ main(int argc, char **argv)
if (optopt) {
log_error("unrecognized character '%c'", optopt);
- rc = -1;
+ rc = ISCSI_ERR_INVAL;
goto free_ifaces;
}
@@ -1957,13 +2239,13 @@ main(int argc, char **argv)
}
if (mode < 0)
- usage(0);
+ usage(ISCSI_ERR_INVAL);
if (mode == MODE_FW) {
if ((rc = verify_mode_params(argc, argv, "ml", 0))) {
log_error("fw mode: option '-%c' is not "
"allowed/supported", rc);
- rc = -1;
+ rc = ISCSI_ERR_INVAL;
goto free_ifaces;
}
@@ -1974,7 +2256,7 @@ main(int argc, char **argv)
increase_max_files();
if (idbm_init(get_config_file)) {
log_warning("exiting due to idbm configuration error");
- rc = -1;
+ rc = ISCSI_ERR_IDBM;
goto free_ifaces;
}
@@ -1983,7 +2265,7 @@ main(int argc, char **argv)
if ((rc = verify_mode_params(argc, argv, "HdmP", 0))) {
log_error("host mode: option '-%c' is not "
"allowed/supported", rc);
- rc = -1;
+ rc = ISCSI_ERR_INVAL;
goto out;
}
@@ -1992,10 +2274,10 @@ main(int argc, char **argv)
case MODE_IFACE:
iface_setup_host_bindings();
- if ((rc = verify_mode_params(argc, argv, "IdnvmPo", 0))) {
+ if ((rc = verify_mode_params(argc, argv, "HIdnvmPo", 0))) {
log_error("iface mode: option '-%c' is not "
"allowed/supported", rc);
- rc = -1;
+ rc = ISCSI_ERR_INVAL;
goto out;
}
@@ -2007,14 +2289,14 @@ main(int argc, char **argv)
"interface. Using the first one "
"%s.", iface->name);
}
- rc = exec_iface_op(op, do_show, info_level, iface,
+ rc = exec_iface_op(op, do_show, info_level, iface, host_no,
name, value);
break;
case MODE_DISCOVERYDB:
if ((rc = verify_mode_params(argc, argv, "DSIPdmntplov", 0))) {
log_error("discovery mode: option '-%c' is not "
"allowed/supported", rc);
- rc = -1;
+ rc = ISCSI_ERR_INVAL;
goto out;
}
@@ -2026,7 +2308,7 @@ main(int argc, char **argv)
if ((rc = verify_mode_params(argc, argv, "DSIPdmntplov", 0))) {
log_error("discovery mode: option '-%c' is not "
"allowed/supported", rc);
- rc = -1;
+ rc = ISCSI_ERR_INVAL;
goto out;
}
@@ -2039,7 +2321,7 @@ main(int argc, char **argv)
0))) {
log_error("node mode: option '-%c' is not "
"allowed/supported", rc);
- rc = -1;
+ rc = ISCSI_ERR_INVAL;
goto out;
}
@@ -2069,7 +2351,7 @@ main(int argc, char **argv)
rec = idbm_create_rec(targetname, tpgt, ip, port, iface, 1);
if (!rec) {
- rc = -1;
+ rc = ISCSI_ERR_NOMEM;
goto out;
}
@@ -2082,7 +2364,7 @@ main(int argc, char **argv)
"PiRdrmusonuSv", 1))) {
log_error("session mode: option '-%c' is not "
"allowed or supported", rc);
- rc = -1;
+ rc = ISCSI_ERR_INVAL;
goto out;
}
if (sid >= 0) {
@@ -2094,7 +2376,7 @@ main(int argc, char **argv)
info = calloc(1, sizeof(*info));
if (!info) {
- rc = ENOMEM;
+ rc = ISCSI_ERR_NOMEM;
goto out;
}
@@ -2115,9 +2397,8 @@ main(int argc, char **argv)
if (!do_logout && !do_rescan && !do_stats &&
op == OP_NOOP && info_level > 0) {
- rc = session_info_print(info_level, info);
- if (rc)
- rc = -1;
+ rc = session_info_print(info_level, info,
+ do_show);
goto free_info;
}
@@ -2127,9 +2408,21 @@ main(int argc, char **argv)
info->persistent_port,
&info->iface, 1);
if (!rec) {
- rc = -1;
+ rc = ISCSI_ERR_NOMEM;
goto free_info;
}
+ rec->session.info = info;
+ rec->session.sid = sid;
+
+ /*
+ * A "new" session means to login a multiple of the
+ * currently-detected session.
+ */
+ if (op == OP_NEW) {
+ op = OP_NOOP;
+ do_login = 1;
+ rec->session.multiple = 1;
+ }
/* drop down to node ops */
rc = exec_node_op(op, do_login, do_logout, do_show,
@@ -2139,6 +2432,12 @@ free_info:
free(info);
goto out;
} else {
+ if (op == OP_NEW) {
+ log_error("session mode: Operation 'new' only "
+ "allowed with specific session IDs");
+ rc = ISCSI_ERR_INVAL;
+ goto out;
+ }
if (do_logout || do_rescan || do_stats) {
rc = exec_node_op(op, do_login, do_logout,
do_show, do_rescan, do_stats,
@@ -2146,7 +2445,7 @@ free_info:
goto out;
}
- rc = session_info_print(info_level, NULL);
+ rc = session_info_print(info_level, NULL, do_show);
}
break;
default:
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/iscsid.c open-iscsi-2.0-872-rc4-bnx2i.work/usr/iscsid.c
--- open-iscsi-2.0-872-rc4-bnx2i/usr/iscsid.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/iscsid.c 2012-03-05 23:05:31.000000000 -0600
@@ -31,6 +31,8 @@
#include <sys/utsname.h>
#include <sys/types.h>
#include <sys/wait.h>
+#include <sys/types.h>
+#include <sys/stat.h>
#include "iscsid.h"
#include "mgmt_ipc.h"
@@ -48,16 +50,17 @@
#include "sysdeps.h"
#include "discoveryd.h"
#include "iscsid_req.h"
+#include "iscsi_err.h"
/* global config info */
struct iscsi_daemon_config daemon_config;
struct iscsi_daemon_config *dconfig = &daemon_config;
static char program_name[] = "iscsid";
-int control_fd, mgmt_ipc_fd;
static pid_t log_pid;
static gid_t gid;
static int daemonize = 1;
+static int mgmt_ipc_fd;
static struct option const long_options[] = {
{"config", required_argument, NULL, 'c'},
@@ -66,6 +69,7 @@ static struct option const long_options[
{"debug", required_argument, NULL, 'd'},
{"uid", required_argument, NULL, 'u'},
{"gid", required_argument, NULL, 'g'},
+ {"no-pid-file", no_argument, NULL, 'n'},
{"pid", required_argument, NULL, 'p'},
{"help", no_argument, NULL, 'h'},
{"version", no_argument, NULL, 'v'},
@@ -87,12 +91,13 @@ Open-iSCSI initiator daemon.\n\
-d, --debug debuglevel print debugging information\n\
-u, --uid=uid run as uid, default is current user\n\
-g, --gid=gid run as gid, default is current user group\n\
+ -n, --no-pid-file do not use a pid file\n\
-p, --pid=pidfile use pid file (default " PID_FILE ").\n\
-h, --help display this help and exit\n\
-v, --version display version and exit\n\
");
}
- exit(status == 0 ? 0 : -1);
+ exit(status);
}
static void
@@ -196,11 +201,6 @@ static int sync_session(void *data, stru
t = iscsi_sysfs_get_transport_by_sid(info->sid);
if (!t)
return 0;
- if (set_transport_template(t)) {
- log_error("Could not find userspace transport template for %s",
- t->name);
- return 0;
- }
/*
* Just rescan the device in case this is the first startup.
@@ -213,13 +213,17 @@ static int sync_session(void *data, stru
host_no = iscsi_sysfs_get_host_no_from_sid(info->sid, &err);
if (err) {
log_error("Could not get host no from sid %u. Can not "
- "sync session. Error %d", info->sid, err);
+ "sync session: %s", info->sid,
+ iscsi_err_to_str(err));
return 0;
}
iscsi_sysfs_scan_host(host_no, 0);
return 0;
}
+ if (!iscsi_sysfs_session_user_created(info->sid))
+ return 0;
+
memset(&rec, 0, sizeof(node_rec_t));
/*
* We might get the local ip address for software. We do not
@@ -272,7 +276,7 @@ static int sync_session(void *data, stru
retry:
rc = iscsid_exec_req(&req, &rsp, 0);
- if (rc == MGMT_IPC_ERR_ISCSID_NOTCONN && retries < 30) {
+ if (rc == ISCSI_ERR_ISCSID_NOTCONN && retries < 30) {
retries++;
sleep(1);
goto retry;
@@ -302,7 +306,12 @@ static void iscsid_shutdown(void)
static void catch_signal(int signo)
{
- log_debug(1, "%d caught signal -%d...", signo, getpid());
+ log_debug(1, "pid %d caught signal %d", getpid(), signo);
+
+ /* In foreground mode, treat SIGINT like SIGTERM */
+ if (!daemonize && signo == SIGINT)
+ signo = SIGTERM;
+
switch (signo) {
case SIGTERM:
iscsid_shutdown();
@@ -318,7 +327,7 @@ static void missing_iname_warn(char *ini
log_error("Warning: InitiatorName file %s does not exist or does not "
"contain a properly formated InitiatorName. If using "
"software iscsi (iscsi_tcp or ib_iser) or partial offload "
- "(bnx2i or cxgb3i iscsi), you may not be able to log "
+ "(bnx2i or cxgbi iscsi), you may not be able to log "
"into or discover targets. Please create a file %s that "
"contains a sting with the format: InitiatorName="
"iqn.yyyy-mm.<reversed domain name>[:identifier].\n\n"
@@ -337,17 +346,10 @@ int main(int argc, char *argv[])
uid_t uid = 0;
struct sigaction sa_old;
struct sigaction sa_new;
+ int control_fd;
pid_t pid;
- /* do not allow ctrl-c for now... */
- sa_new.sa_handler = catch_signal;
- sigemptyset(&sa_new.sa_mask);
- sa_new.sa_flags = 0;
- sigaction(SIGINT, &sa_new, &sa_old );
- sigaction(SIGPIPE, &sa_new, &sa_old );
- sigaction(SIGTERM, &sa_new, &sa_old );
-
- while ((ch = getopt_long(argc, argv, "c:i:fd:u:g:p:vh", long_options,
+ while ((ch = getopt_long(argc, argv, "c:i:fd:nu:g:p:vh", long_options,
&longindex)) >= 0) {
switch (ch) {
case 'c':
@@ -368,6 +370,9 @@ int main(int argc, char *argv[])
case 'g':
gid = strtoul(optarg, NULL, 10);
break;
+ case 'n':
+ pid_file = NULL;
+ break;
case 'p':
pid_file = optarg;
break;
@@ -388,17 +393,25 @@ int main(int argc, char *argv[])
log_pid = log_init(program_name, DEFAULT_AREA_SIZE,
daemonize ? log_do_log_daemon : log_do_log_std, NULL);
if (log_pid < 0)
- exit(1);
+ exit(ISCSI_ERR);
+
+ /* do not allow ctrl-c for now... */
+ sa_new.sa_handler = catch_signal;
+ sigemptyset(&sa_new.sa_mask);
+ sa_new.sa_flags = 0;
+ sigaction(SIGINT, &sa_new, &sa_old );
+ sigaction(SIGPIPE, &sa_new, &sa_old );
+ sigaction(SIGTERM, &sa_new, &sa_old );
sysfs_init();
if (idbm_init(iscsid_get_config_file)) {
log_close(log_pid);
- exit(1);
+ exit(ISCSI_ERR);
}
if (iscsi_sysfs_check_class_version()) {
log_close(log_pid);
- exit(1);
+ exit(ISCSI_ERR);
}
umask(0177);
@@ -410,24 +423,26 @@ int main(int argc, char *argv[])
if ((mgmt_ipc_fd = mgmt_ipc_listen()) < 0) {
log_close(log_pid);
- exit(1);
+ exit(ISCSI_ERR);
}
if (daemonize) {
char buf[64];
- int fd;
+ int fd = -1;
- fd = open(pid_file, O_WRONLY|O_CREAT, 0644);
- if (fd < 0) {
- log_error("Unable to create pid file");
- log_close(log_pid);
- exit(1);
+ if (pid_file) {
+ fd = open(pid_file, O_WRONLY|O_CREAT, 0644);
+ if (fd < 0) {
+ log_error("Unable to create pid file");
+ log_close(log_pid);
+ exit(ISCSI_ERR);
+ }
}
pid = fork();
if (pid < 0) {
log_error("Starting daemon failed");
log_close(log_pid);
- exit(1);
+ exit(ISCSI_ERR);
} else if (pid) {
log_error("iSCSI daemon with pid=%d started!", pid);
exit(0);
@@ -435,18 +450,29 @@ int main(int argc, char *argv[])
if ((control_fd = ipc->ctldev_open()) < 0) {
log_close(log_pid);
- exit(1);
+ exit(ISCSI_ERR);
}
- chdir("/");
- if (lockf(fd, F_TLOCK, 0) < 0) {
- log_error("Unable to lock pid file");
- log_close(log_pid);
- exit(1);
+ if (chdir("/") < 0)
+ log_debug(1, "Unable to chdir to /");
+ if (fd > 0) {
+ if (lockf(fd, F_TLOCK, 0) < 0) {
+ log_error("Unable to lock pid file");
+ log_close(log_pid);
+ exit(ISCSI_ERR);
+ }
+ if (ftruncate(fd, 0) < 0) {
+ log_error("Unable to truncate pid file");
+ log_close(log_pid);
+ exit(ISCSI_ERR);
+ }
+ sprintf(buf, "%d\n", getpid());
+ if (write(fd, buf, strlen(buf)) < 0) {
+ log_error("Unable to write pid file");
+ log_close(log_pid);
+ exit(ISCSI_ERR);
+ }
}
- ftruncate(fd, 0);
- sprintf(buf, "%d\n", getpid());
- write(fd, buf, strlen(buf));
daemon_init();
} else {
@@ -498,6 +524,7 @@ int main(int argc, char *argv[])
} else
reap_inc();
+ iscsi_initiator_init();
increase_max_files();
discoveryd_start(daemon_config.initiator_name);
@@ -509,7 +536,7 @@ int main(int argc, char *argv[])
if (mlockall(MCL_CURRENT | MCL_FUTURE)) {
log_error("failed to mlockall, exiting...");
log_close(log_pid);
- exit(1);
+ exit(ISCSI_ERR);
}
actor_init();
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/iscsid.h open-iscsi-2.0-872-rc4-bnx2i.work/usr/iscsid.h
--- open-iscsi-2.0-872-rc4-bnx2i/usr/iscsid.h 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/iscsid.h 2012-03-05 23:02:46.000000000 -0600
@@ -31,6 +31,5 @@ struct iscsi_daemon_config {
char *initiator_alias;
};
extern struct iscsi_daemon_config *dconfig;
-extern int control_fd;
#endif /* ISCSID_H */
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/iscsid_req.c open-iscsi-2.0-872-rc4-bnx2i.work/usr/iscsid_req.c
--- open-iscsi-2.0-872-rc4-bnx2i/usr/iscsid_req.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/iscsid_req.c 2012-03-05 23:02:46.000000000 -0600
@@ -31,6 +31,7 @@
#include "mgmt_ipc.h"
#include "iscsi_util.h"
#include "config.h"
+#include "iscsi_err.h"
static void iscsid_startup(void)
{
@@ -46,12 +47,14 @@ static void iscsid_startup(void)
return;
}
- system(startup_cmd);
+ if (system(startup_cmd) < 0)
+ log_error("Could not execute '%s' (err %d)",
+ startup_cmd, errno);
}
#define MAXSLEEP 128
-static mgmt_ipc_err_e iscsid_connect(int *fd, int start_iscsid)
+static int iscsid_connect(int *fd, int start_iscsid)
{
int nsec;
struct sockaddr_un addr;
@@ -59,7 +62,7 @@ static mgmt_ipc_err_e iscsid_connect(int
*fd = socket(AF_LOCAL, SOCK_STREAM, 0);
if (*fd < 0) {
log_error("can not create IPC socket (%d)!", errno);
- return MGMT_IPC_ERR_ISCSID_NOTCONN;
+ return ISCSI_ERR_ISCSID_NOTCONN;
}
memset(&addr, 0, sizeof(addr));
@@ -72,7 +75,7 @@ static mgmt_ipc_err_e iscsid_connect(int
for (nsec = 1; nsec <= MAXSLEEP; nsec <<= 1) {
if (connect(*fd, (struct sockaddr *) &addr, sizeof(addr)) == 0)
/* Connection established */
- return MGMT_IPC_OK;
+ return ISCSI_SUCCESS;
/* If iscsid isn't there, there's no sense
* in retrying. */
@@ -90,10 +93,10 @@ static mgmt_ipc_err_e iscsid_connect(int
sleep(nsec);
}
log_error("can not connect to iSCSI daemon (%d)!", errno);
- return MGMT_IPC_ERR_ISCSID_NOTCONN;
+ return ISCSI_ERR_ISCSID_NOTCONN;
}
-mgmt_ipc_err_e iscsid_request(int *fd, iscsiadm_req_t *req, int start_iscsid)
+int iscsid_request(int *fd, iscsiadm_req_t *req, int start_iscsid)
{
int err;
@@ -105,33 +108,33 @@ mgmt_ipc_err_e iscsid_request(int *fd, i
log_error("got write error (%d/%d) on cmd %d, daemon died?",
err, errno, req->command);
close(*fd);
- return MGMT_IPC_ERR_ISCSID_COMM_ERR;
+ return ISCSI_ERR_ISCSID_COMM_ERR;
}
- return MGMT_IPC_OK;
+ return ISCSI_SUCCESS;
}
-mgmt_ipc_err_e iscsid_response(int fd, iscsiadm_cmd_e cmd, iscsiadm_rsp_t *rsp)
+int iscsid_response(int fd, iscsiadm_cmd_e cmd, iscsiadm_rsp_t *rsp)
{
- mgmt_ipc_err_e iscsi_err;
+ int iscsi_err;
int err;
if ((err = recv(fd, rsp, sizeof(*rsp), MSG_WAITALL)) != sizeof(*rsp)) {
log_error("got read error (%d/%d), daemon died?", err, errno);
- iscsi_err = MGMT_IPC_ERR_ISCSID_COMM_ERR;
+ iscsi_err = ISCSI_ERR_ISCSID_COMM_ERR;
} else
iscsi_err = rsp->err;
close(fd);
if (!iscsi_err && cmd != rsp->command)
- iscsi_err = MGMT_IPC_ERR_ISCSID_COMM_ERR;
+ iscsi_err = ISCSI_ERR_ISCSID_COMM_ERR;
return iscsi_err;
}
-mgmt_ipc_err_e iscsid_exec_req(iscsiadm_req_t *req, iscsiadm_rsp_t *rsp,
+int iscsid_exec_req(iscsiadm_req_t *req, iscsiadm_rsp_t *rsp,
int start_iscsid)
{
int fd;
- mgmt_ipc_err_e err;
+ int err;
err = iscsid_request(&fd, req, start_iscsid);
if (err)
@@ -189,31 +192,3 @@ int iscsid_req_by_sid(iscsiadm_cmd_e cmd
return err;
return iscsid_req_wait(cmd, fd);
}
-
-void iscsid_handle_error(mgmt_ipc_err_e err)
-{
- static char *err_msgs[] = {
- /* 0 */ "",
- /* 1 */ "unknown error",
- /* 2 */ "not found",
- /* 3 */ "no available memory",
- /* 4 */ "encountered connection failure",
- /* 5 */ "encountered iSCSI login failure",
- /* 6 */ "encountered iSCSI database failure",
- /* 7 */ "invalid parameter",
- /* 8 */ "connection timed out",
- /* 9 */ "internal error",
- /* 10 */ "encountered iSCSI logout failure",
- /* 11 */ "iSCSI PDU timed out",
- /* 12 */ "iSCSI driver not found. Please make sure it is loaded, and retry the operation",
- /* 13 */ "daemon access denied",
- /* 14 */ "iSCSI driver does not support requested capability.",
- /* 15 */ "already exists",
- /* 16 */ "Unknown request",
- /* 17 */ "encountered iSNS failure",
- /* 18 */ "could not communicate to iscsid",
- /* 19 */ "encountered non-retryable iSCSI login failure",
- /* 20 */ "could not connect to iscsid",
- };
- log_error("initiator reported error (%d - %s)", err, err_msgs[err]);
-}
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/iscsid_req.h open-iscsi-2.0-872-rc4-bnx2i.work/usr/iscsid_req.h
--- open-iscsi-2.0-872-rc4-bnx2i/usr/iscsid_req.h 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/iscsid_req.h 2012-03-05 23:02:46.000000000 -0600
@@ -27,7 +27,6 @@ struct node_rec;
extern int iscsid_exec_req(struct iscsiadm_req *req, struct iscsiadm_rsp *rsp,
int iscsid_start);
-extern void iscsid_handle_error(int err);
extern int iscsid_req_wait(int cmd, int fd);
extern int iscsid_req_by_rec_async(int cmd, struct node_rec *rec, int *fd);
extern int iscsid_req_by_rec(int cmd, struct node_rec *rec);
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/iscsi_err.c open-iscsi-2.0-872-rc4-bnx2i.work/usr/iscsi_err.c
--- open-iscsi-2.0-872-rc4-bnx2i/usr/iscsi_err.c 1969-12-31 18:00:00.000000000 -0600
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/iscsi_err.c 2012-03-05 23:02:46.000000000 -0600
@@ -0,0 +1,72 @@
+/*
+ * iSCSI error helpers
+ *
+ * Copyright (C) 2011 Mike Christie
+ * Copyright (C) 2011 Red Hat, Inc. All rights reserved.
+ * maintained by open-iscsi@googlegroups.com
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published
+ * by the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * General Public License for more details.
+ *
+ * See the file COPYING included with this distribution for more details.
+ */
+#include "stdlib.h"
+#include "iscsi_err.h"
+#include "log.h"
+
+static char *iscsi_err_msgs[] = {
+ /* 0 */ "",
+ /* 1 */ "unknown error",
+ /* 2 */ "session not found",
+ /* 3 */ "no available memory",
+ /* 4 */ "encountered connection failure",
+ /* 5 */ "encountered iSCSI login failure",
+ /* 6 */ "encountered iSCSI database failure",
+ /* 7 */ "invalid parameter",
+ /* 8 */ "connection timed out",
+ /* 9 */ "internal error",
+ /* 10 */ "encountered iSCSI logout failure",
+ /* 11 */ "iSCSI PDU timed out",
+ /* 12 */ "iSCSI driver not found. Please make sure it is loaded, and retry the operation",
+ /* 13 */ "daemon access denied",
+ /* 14 */ "iSCSI driver does not support requested capability.",
+ /* 15 */ "session exists",
+ /* 16 */ "Unknown request",
+ /* 17 */ "iSNS service not supported",
+ /* 18 */ "could not communicate to iscsid",
+ /* 19 */ "encountered non-retryable iSCSI login failure",
+ /* 20 */ "could not connect to iscsid",
+ /* 21 */ "no objects found",
+ /* 22 */ "sysfs lookup failure",
+ /* 23 */ "host not found",
+ /* 24 */ "iSCSI login failed due to authorization failure",
+ /* 25 */ "iSNS query failed",
+ /* 26 */ "iSNS registration failed",
+};
+
+char *iscsi_err_to_str(int err)
+{
+ if (err >= ISCSI_MAX_ERR_VAL || err < 0) {
+ log_error("invalid error code %d", err);
+ return NULL;
+ }
+
+ return iscsi_err_msgs[err];
+}
+
+void iscsi_err_print_msg(int err)
+{
+ if (err >= ISCSI_MAX_ERR_VAL || err < 0) {
+ log_error("invalid error code %d", err);
+ return;
+ }
+ log_error("initiator reported error (%d - %s)", err,
+ iscsi_err_msgs[err]);
+}
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/iscsi_ipc.h open-iscsi-2.0-872-rc4-bnx2i.work/usr/iscsi_ipc.h
--- open-iscsi-2.0-872-rc4-bnx2i/usr/iscsi_ipc.h 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/iscsi_ipc.h 2012-03-05 23:02:46.000000000 -0600
@@ -34,6 +34,26 @@ enum {
};
struct iscsi_conn;
+struct iscsi_ev_context;
+
+/*
+ * When handling async events, the initiator may not be able to
+ * handle the event in the same context, so this allows the interface
+ * code to call into the initiator to shedule handling.
+ */
+struct iscsi_ipc_ev_clbk {
+ void (*create_session) (uint32_t host_no, uint32_t sid);
+ void (*destroy_session) (uint32_t host_no, uint32_t sid);
+
+ struct iscsi_ev_context *(*get_ev_context) (struct iscsi_conn *conn,
+ int ev_size);
+ void (*put_ev_context) (struct iscsi_ev_context *ev_context);
+ int (*sched_ev_context) (struct iscsi_ev_context *ev_context,
+ struct iscsi_conn *conn,
+ unsigned long tmo, int event);
+};
+
+extern void ipc_register_ev_callback(struct iscsi_ipc_ev_clbk *ipc_ev_clbk);
/**
* struct iscsi_ipc - Open-iSCSI Interface for Kernel IPC
@@ -109,6 +129,11 @@ struct iscsi_ipc {
int (*recv_pdu_begin) (struct iscsi_conn *conn);
int (*recv_pdu_end) (struct iscsi_conn *conn);
+
+ int (*set_net_config) (uint64_t transport_handle, uint32_t host_no,
+ struct iovec *iovs, uint32_t param_count);
+
+ int (*recv_conn_state) (struct iscsi_conn *conn, uint32_t *state);
};
#endif /* ISCSI_IPC_H */
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/iscsi_netlink.h open-iscsi-2.0-872-rc4-bnx2i.work/usr/iscsi_netlink.h
--- open-iscsi-2.0-872-rc4-bnx2i/usr/iscsi_netlink.h 1969-12-31 18:00:00.000000000 -0600
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/iscsi_netlink.h 2012-03-05 23:04:01.000000000 -0600
@@ -0,0 +1,33 @@
+/*
+ * iSCSI Netlink attr helpers
+ *
+ * Copyright (C) 2011 Red Hat, Inc. All rights reserved.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published
+ * by the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * General Public License for more details.
+ *
+ * See the file COPYING included with this distribution for more details.
+ */
+
+#ifndef ISCSI_NLA_H
+#define ISCSI_NLA_H
+
+#include <linux/netlink.h>
+
+struct iovec;
+
+#define ISCSI_NLA_HDRLEN ((int) NLA_ALIGN(sizeof(struct nlattr)))
+#define ISCSI_NLA_DATA(nla) ((void *)((char*)(nla) + ISCSI_NLA_HDRLEN))
+#define ISCSI_NLA_LEN(len) ((len) + NLA_ALIGN(ISCSI_NLA_HDRLEN))
+#define ISCSI_NLA_TOTAL_LEN(len) (NLA_ALIGN(ISCSI_NLA_LEN(len)))
+
+extern struct nlattr *iscsi_nla_alloc(uint16_t type, uint16_t len);
+
+#endif
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/iscsi_net_util.c open-iscsi-2.0-872-rc4-bnx2i.work/usr/iscsi_net_util.c
--- open-iscsi-2.0-872-rc4-bnx2i/usr/iscsi_net_util.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/iscsi_net_util.c 2012-03-05 23:02:46.000000000 -0600
@@ -41,6 +41,7 @@ struct iscsi_net_driver {
static struct iscsi_net_driver net_drivers[] = {
#ifdef OFFLOAD_BOOT_SUPPORTED
{"cxgb3", "cxgb3i" },
+ {"cxgb4", "cxgb4i" },
{"bnx2", "bnx2i" },
{"bnx2x", "bnx2i"},
#endif
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/iscsistart.c open-iscsi-2.0-872-rc4-bnx2i.work/usr/iscsistart.c
--- open-iscsi-2.0-872-rc4-bnx2i/usr/iscsistart.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/iscsistart.c 2012-03-05 23:06:04.000000000 -0600
@@ -47,6 +47,7 @@
#include "iface.h"
#include "sysdeps.h"
#include "iscsid_req.h"
+#include "iscsi_err.h"
/* global config info */
/* initiator needs initiator name/alias */
@@ -55,12 +56,16 @@ struct iscsi_daemon_config *dconfig = &d
static node_rec_t config_rec;
static LIST_HEAD(targets);
+static LIST_HEAD(user_params);
+
+struct user_param {
+ struct list_head list;
+ char *param_string;
+};
static char program_name[] = "iscsistart";
-static int mgmt_ipc_fd;
/* used by initiator */
-int control_fd;
extern struct iscsi_ipc *ipc;
static struct option const long_options[] = {
@@ -77,6 +82,7 @@ static struct option const long_options[
{"fwparam_connect", no_argument, NULL, 'b'},
{"fwparam_network", no_argument, NULL, 'N'},
{"fwparam_print", no_argument, NULL, 'f'},
+ {"param", required_argument, NULL, 'P'},
{"help", no_argument, NULL, 'h'},
{"version", no_argument, NULL, 'v'},
{NULL, 0, NULL, 0},
@@ -104,11 +110,12 @@ Open-iSCSI initiator.\n\
-b, --fwparam_connect create a session to the target using iBFT or OF\n\
-N, --fwparam_network bring up the network as specified by iBFT or OF\n\
-f, --fwparam_print print the iBFT or OF info to STDOUT \n\
+ -P, --param=NAME=VALUE set parameter with the name NAME to VALUE\n\
-h, --help display this help and exit\n\
-v, --version display version and exit\n\
");
}
- exit(status == 0 ? 0 : -1);
+ exit(status);
}
static int stop_event_loop(void)
@@ -121,26 +128,75 @@ static int stop_event_loop(void)
req.command = MGMT_IPC_IMMEDIATE_STOP;
rc = iscsid_exec_req(&req, &rsp, 0);
if (rc) {
- iscsid_handle_error(rc);
+ iscsi_err_print_msg(rc);
log_error("Could not stop event_loop\n");
}
return rc;
}
+static int apply_params(struct node_rec *rec)
+{
+ struct user_param *param;
+ int rc;
+
+ /* Must init this so we can check if user overrode them */
+ rec->session.initial_login_retry_max = -1;
+ rec->conn[0].timeo.noop_out_interval = -1;
+ rec->conn[0].timeo.noop_out_timeout = -1;
+
+ list_for_each_entry(param, &user_params, list) {
+ rc = idbm_parse_param(param->param_string, rec);
+ if (rc)
+ return rc;
+ }
+
+ /*
+ * For root boot we could not change this in older versions so
+ * if user did not override then use the defaults.
+ *
+ * Increase to account for boot using static setup.
+ */
+ if (rec->session.initial_login_retry_max == -1)
+ rec->session.initial_login_retry_max = 30;
+ /* we used to not be able to answer so turn off */
+ if (rec->conn[0].timeo.noop_out_interval == -1)
+ rec->conn[0].timeo.noop_out_interval = 0;
+ if (rec->conn[0].timeo.noop_out_timeout == -1)
+ rec->conn[0].timeo.noop_out_timeout = 0;
+
+ return 0;
+}
+
+static int alloc_param(char *param_string)
+{
+ struct user_param *param;
+
+ param = calloc(1, sizeof(*param));
+ if (!param) {
+ printf("Could not allocate for param.\n");
+ return ISCSI_ERR_NOMEM;
+ }
+
+ INIT_LIST_HEAD(¶m->list);
+ param->param_string = strdup(param_string);
+ if (!param->param_string) {
+ printf("Could not allocate for param.\n");
+ free(param);
+ return ISCSI_ERR_NOMEM;
+ }
+ list_add(¶m->list, &user_params);
+ return 0;
+}
static int login_session(struct node_rec *rec)
{
iscsiadm_req_t req;
iscsiadm_rsp_t rsp;
int rc, retries = 0;
- /*
- * For root boot we cannot change this so increase to account
- * for boot using static setup.
- */
- rec->session.initial_login_retry_max = 30;
- /* we cannot answer so turn off */
- rec->conn[0].timeo.noop_out_interval = 0;
- rec->conn[0].timeo.noop_out_timeout = 0;
+
+ rc = apply_params(rec);
+ if (rc)
+ exit(rc);
printf("%s: Logging into %s %s:%d,%d\n", program_name, rec->name,
rec->conn[0].address, rec->conn[0].port,
@@ -155,12 +211,12 @@ retry:
* handle race where iscsid proc is starting up while we are
* trying to connect.
*/
- if (rc == MGMT_IPC_ERR_ISCSID_NOTCONN && retries < 30) {
+ if (rc == ISCSI_ERR_ISCSID_NOTCONN && retries < 30) {
retries++;
sleep(1);
goto retry;
} else if (rc)
- iscsid_handle_error(rc);
+ iscsi_err_print_msg(rc);
return rc;
}
@@ -229,7 +285,7 @@ do { \
if (strlen(str) > max_len) { \
printf("%s: invalid %s %s. Max %s length is %d.\n", \
program_name, param, str, param, max_len); \
- exit(1); \
+ exit(ISCSI_ERR_INVAL); \
} \
} while (0);
@@ -242,6 +298,7 @@ int main(int argc, char *argv[])
struct boot_context *context, boot_context;
struct sigaction sa_old;
struct sigaction sa_new;
+ int control_fd, mgmt_ipc_fd, err;
pid_t pid;
idbm_node_setup_defaults(&config_rec);
@@ -260,9 +317,9 @@ int main(int argc, char *argv[])
sysfs_init();
if (iscsi_sysfs_check_class_version())
- exit(1);
+ exit(ISCSI_ERR_SYSFS_LOOKUP);
- while ((ch = getopt_long(argc, argv, "i:t:g:a:p:d:u:w:U:W:bNfvh",
+ while ((ch = getopt_long(argc, argv, "P:i:t:g:a:p:d:u:w:U:W:bNfvh",
long_options, &longindex)) >= 0) {
switch (ch) {
case 'i':
@@ -316,25 +373,24 @@ int main(int argc, char *argv[])
ret = fw_get_entry(&boot_context);
if (ret) {
printf("Could not get boot entry.\n");
- exit(1);
+ exit(ret);
}
initiatorname = boot_context.initiatorname;
ret = fw_get_targets(&targets);
if (ret || list_empty(&targets)) {
printf("Could not setup fw entries.\n");
- exit(1);
+ exit(ret);
}
break;
case 'N':
- ret = fw_setup_nics();
- exit(ret);
+ exit(fw_setup_nics());
case 'f':
ret = fw_get_targets(&targets);
if (ret || list_empty(&targets)) {
printf("Could not get list of targets from "
"firmware.\n");
- exit(1);
+ exit(ret);
}
list_for_each_entry(context, &targets, list)
@@ -342,6 +398,11 @@ int main(int argc, char *argv[])
fw_free_targets(&targets);
exit(0);
+ case 'P':
+ err = alloc_param(optarg);
+ if (err)
+ exit(err);
+ break;
case 'v':
printf("%s version %s\n", program_name,
ISCSI_VERSION_STR);
@@ -350,18 +411,18 @@ int main(int argc, char *argv[])
usage(0);
break;
default:
- usage(1);
+ usage(ISCSI_ERR_INVAL);
break;
}
}
if (list_empty(&targets) && check_params(initiatorname))
- exit(1);
+ exit(ISCSI_ERR_INVAL);
pid = fork();
if (pid < 0) {
log_error("iscsiboot fork failed");
- exit(1);
+ exit(ISCSI_ERR_NOMEM);
} else if (pid) {
int status, rc, rc2;
@@ -376,7 +437,7 @@ int main(int argc, char *argv[])
waitpid(pid, &status, WUNTRACED);
if (rc || rc2)
- exit(-1);
+ exit(ISCSI_ERR);
log_debug(1, "iscsi parent done");
exit(0);
@@ -385,12 +446,12 @@ int main(int argc, char *argv[])
mgmt_ipc_fd = mgmt_ipc_listen();
if (mgmt_ipc_fd < 0) {
log_error("Could not setup mgmt ipc\n");
- exit(-1);
+ exit(ISCSI_ERR_NOMEM);
}
control_fd = ipc->ctldev_open();
if (control_fd < 0)
- exit(-1);
+ exit(ISCSI_ERR_NOMEM);
memset(&daemon_config, 0, sizeof (daemon_config));
daemon_config.initiator_name = initiatorname;
@@ -420,6 +481,7 @@ int main(int argc, char *argv[])
/*
* Start Main Event Loop
*/
+ iscsi_initiator_init();
actor_init();
event_loop(ipc, control_fd, mgmt_ipc_fd);
ipc->ctldev_close();
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/iscsi_sysfs.c open-iscsi-2.0-872-rc4-bnx2i.work/usr/iscsi_sysfs.c
--- open-iscsi-2.0-872-rc4-bnx2i/usr/iscsi_sysfs.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/iscsi_sysfs.c 2012-03-05 23:05:31.000000000 -0600
@@ -36,6 +36,7 @@
#include "iface.h"
#include "session_info.h"
#include "host.h"
+#include "iscsi_err.h"
/*
* TODO: remove the _DIR defines and search for subsys dirs like
@@ -49,6 +50,7 @@
#define ISCSI_CONN_SUBSYS "iscsi_connection"
#define ISCSI_HOST_SUBSYS "iscsi_host"
#define ISCSI_TRANSPORT_SUBSYS "iscsi_transport"
+#define ISCSI_IFACE_SUBSYS "iscsi_iface"
#define SCSI_HOST_SUBSYS "scsi_host"
#define SCSI_SUBSYS "scsi"
@@ -115,6 +117,10 @@ static int read_transports(void)
INIT_LIST_HEAD(&t->list);
strlcpy(t->name, namelist[i]->d_name,
ISCSI_TRANSPORT_NAME_MAXLEN);
+ if (set_transport_template(t)) {
+ free(t);
+ return -1;
+ }
} else
log_debug(7, "Updating transport %s",
namelist[i]->d_name);
@@ -143,7 +149,6 @@ static int read_transports(void)
*/
if (!strcmp(t->name, "qla4xxx")) {
t->caps |= CAP_DATA_PATH_OFFLOAD;
- t->caps |= CAP_FW_DB;
}
if (list_empty(&t->list))
@@ -226,6 +231,29 @@ void iscsi_sysfs_get_negotiated_session_
&conf->MaxOutstandingR2T);
}
+/*
+ * iscsi_sysfs_session_user_created - return if session was setup by userspace
+ * @sid: id of session to test
+ *
+ * Returns -1 if we could not tell due to kernel not supporting the
+ * feature. 0 is returned if kernel created it. And 1 is returned
+ * if userspace created it.
+ */
+int iscsi_sysfs_session_user_created(int sid)
+{
+ char id[NAME_SIZE];
+ pid_t pid;
+
+ snprintf(id, sizeof(id), ISCSI_SESSION_ID, sid);
+ if (sysfs_get_int(id, ISCSI_SESSION_SUBSYS, "creator", &pid))
+ return -1;
+
+ if (pid == -1)
+ return 0;
+ else
+ return 1;
+}
+
uint32_t iscsi_sysfs_get_host_no_from_sid(uint32_t sid, int *err)
{
struct sysfs_device *session_dev, *host_dev;
@@ -238,7 +266,7 @@ uint32_t iscsi_sysfs_get_host_no_from_si
ISCSI_SESSION_SUBSYS, id)) {
log_error("Could not lookup devpath for %s. Possible sysfs "
"incompatibility.\n", id);
- *err = EIO;
+ *err = ISCSI_ERR_SYSFS_LOOKUP;
return 0;
}
@@ -246,7 +274,7 @@ uint32_t iscsi_sysfs_get_host_no_from_si
if (!session_dev) {
log_error("Could not get dev for %s. Possible sysfs "
"incompatibility.\n", id);
- *err = EIO;
+ *err = ISCSI_ERR_SYSFS_LOOKUP;
return 0;
}
@@ -271,7 +299,7 @@ uint32_t iscsi_sysfs_get_host_no_from_si
if (!host_dev) {
log_error("Could not get host dev for %s. Possible "
"sysfs incompatibility.\n", id);
- *err = EIO;
+ *err = ISCSI_ERR_SYSFS_LOOKUP;
return 0;
}
}
@@ -301,7 +329,7 @@ static uint32_t get_host_no_from_netdev(
info = calloc(1, sizeof(*info));
if (!info) {
- *rc = ENOMEM;
+ *rc = ISCSI_ERR_NOMEM;
return -1;
}
strcpy(info->iface.netdev, netdev);
@@ -311,7 +339,7 @@ static uint32_t get_host_no_from_netdev(
if (local_rc == 1)
host_no = info->host_no;
else
- *rc = ENODEV;
+ *rc = ISCSI_ERR_HOST_NOT_FOUND;
free(info);
return host_no;
}
@@ -320,14 +348,14 @@ static int __get_host_no_from_hwaddress(
{
struct host_info *ret_info = data;
- if (!strcmp(ret_info->iface.hwaddress, info->iface.hwaddress)) {
+ if (!strcasecmp(ret_info->iface.hwaddress, info->iface.hwaddress)) {
ret_info->host_no = info->host_no;
return 1;
}
return 0;
}
-static uint32_t get_host_no_from_hwaddress(char *address, int *rc)
+uint32_t iscsi_sysfs_get_host_no_from_hwaddress(char *hwaddress, int *rc)
{
uint32_t host_no = -1;
struct host_info *info;
@@ -337,17 +365,17 @@ static uint32_t get_host_no_from_hwaddre
info = calloc(1, sizeof(*info));
if (!info) {
- *rc = ENOMEM;
+ *rc = ISCSI_ERR_NOMEM;
return -1;
}
- strcpy(info->iface.hwaddress, address);
+ strcpy(info->iface.hwaddress, hwaddress);
local_rc = iscsi_sysfs_for_each_host(info, &nr_found,
__get_host_no_from_hwaddress);
if (local_rc == 1)
host_no = info->host_no;
else
- *rc = ENODEV;
+ *rc = ISCSI_ERR_HOST_NOT_FOUND;
free(info);
return host_no;
}
@@ -374,7 +402,7 @@ static uint32_t get_host_no_from_ipaddre
info = calloc(1, sizeof(*info));
if (!info) {
- *rc = ENOMEM;
+ *rc = ISCSI_ERR_NOMEM;
return -1;
}
strcpy(info->iface.ipaddress, address);
@@ -384,7 +412,7 @@ static uint32_t get_host_no_from_ipaddre
if (local_rc == 1)
host_no = info->host_no;
else
- *rc = ENODEV;
+ *rc = ISCSI_ERR_HOST_NOT_FOUND;
free(info);
return host_no;
}
@@ -396,7 +424,8 @@ uint32_t iscsi_sysfs_get_host_no_from_hw
if (strlen(iface->hwaddress) &&
strcasecmp(iface->hwaddress, DEFAULT_HWADDRESS))
- host_no = get_host_no_from_hwaddress(iface->hwaddress, &tmp_rc);
+ host_no = iscsi_sysfs_get_host_no_from_hwaddress(
+ iface->hwaddress, &tmp_rc);
else if (strlen(iface->netdev) &&
strcasecmp(iface->netdev, DEFAULT_NETDEV))
host_no = get_host_no_from_netdev(iface->netdev, &tmp_rc);
@@ -404,7 +433,7 @@ uint32_t iscsi_sysfs_get_host_no_from_hw
strcasecmp(iface->ipaddress, DEFAULT_IPADDRESS))
host_no = get_host_no_from_ipaddress(iface->ipaddress, &tmp_rc);
else
- tmp_rc = EINVAL;
+ tmp_rc = ISCSI_ERR_INVAL;
*rc = tmp_rc;
return host_no;
@@ -417,11 +446,12 @@ uint32_t iscsi_sysfs_get_host_no_from_hw
* qla4xxx.
*/
static int iscsi_sysfs_read_iface(struct iface_rec *iface, int host_no,
- char *session)
+ char *session, char *iface_kern_id)
{
- char id[NAME_SIZE];
+ uint32_t tmp_host_no, iface_num;
+ char host_id[NAME_SIZE];
struct iscsi_transport *t;
- int ret;
+ int ret, iface_type;
t = iscsi_sysfs_get_transport_by_hba(host_no);
if (!t)
@@ -430,26 +460,31 @@ static int iscsi_sysfs_read_iface(struct
else
strcpy(iface->transport_name, t->name);
- snprintf(id, sizeof(id), ISCSI_HOST_ID, host_no);
+ snprintf(host_id, sizeof(host_id), ISCSI_HOST_ID, host_no);
/*
* backward compat
* If we cannot get the address we assume we are doing the old
* style and use default.
*/
- ret = sysfs_get_str(id, ISCSI_HOST_SUBSYS, "hwaddress",
+ ret = sysfs_get_str(host_id, ISCSI_HOST_SUBSYS, "hwaddress",
iface->hwaddress, sizeof(iface->hwaddress));
if (ret)
log_debug(7, "could not read hwaddress for host%d\n", host_no);
- /* if not found just print out default */
- ret = sysfs_get_str(id, ISCSI_HOST_SUBSYS, "ipaddress",
- iface->ipaddress, sizeof(iface->ipaddress));
+ if (iface_kern_id)
+ ret = sysfs_get_str(iface_kern_id, ISCSI_IFACE_SUBSYS,
+ "ipaddress",
+ iface->ipaddress, sizeof(iface->ipaddress));
+ else
+ /* if not found just print out default */
+ ret = sysfs_get_str(host_id, ISCSI_HOST_SUBSYS, "ipaddress",
+ iface->ipaddress, sizeof(iface->ipaddress));
if (ret)
log_debug(7, "could not read local address for host%d\n",
host_no);
/* if not found just print out default */
- ret = sysfs_get_str(id, ISCSI_HOST_SUBSYS, "netdev",
+ ret = sysfs_get_str(host_id, ISCSI_HOST_SUBSYS, "netdev",
iface->netdev, sizeof(iface->netdev));
if (ret)
log_debug(7, "could not read netdev for host%d\n", host_no);
@@ -459,7 +494,7 @@ static int iscsi_sysfs_read_iface(struct
* host level because we cannot create different initiator ports
* (cannot set isid either). The LLD also exports the iname at the
* hba level so apps can see it, but we no longer set the iname for
- * each iscsid controlled host since bnx2i cxgb3i can support multiple
+ * each iscsid controlled host since bnx2i cxgbi can support multiple
* initiator names and of course software iscsi can support anything.
*/
ret = 1;
@@ -481,7 +516,7 @@ static int iscsi_sysfs_read_iface(struct
}
if (ret) {
- ret = sysfs_get_str(id, ISCSI_HOST_SUBSYS, "initiatorname",
+ ret = sysfs_get_str(host_id, ISCSI_HOST_SUBSYS, "initiatorname",
iface->iname, sizeof(iface->iname));
if (ret)
/*
@@ -493,6 +528,8 @@ static int iscsi_sysfs_read_iface(struct
*/
log_debug(7, "Could not read initiatorname for "
"host%d\n", host_no);
+ /* optional so do not return error */
+ ret = 0;
}
/*
@@ -523,12 +560,67 @@ static int iscsi_sysfs_read_iface(struct
iface_str(iface));
}
}
- return ret;
+
+ if (!iface_kern_id)
+ goto done;
+
+ strlcpy(iface->name, iface_kern_id, sizeof(iface->name));
+
+ if (!strncmp(iface_kern_id, "ipv4", 4)) {
+ sysfs_get_str(iface_kern_id, ISCSI_IFACE_SUBSYS, "bootproto",
+ iface->bootproto, sizeof(iface->bootproto));
+
+ sysfs_get_str(iface_kern_id, ISCSI_IFACE_SUBSYS, "gateway",
+ iface->gateway, sizeof(iface->gateway));
+
+ sysfs_get_str(iface_kern_id, ISCSI_IFACE_SUBSYS, "subnet",
+ iface->subnet_mask, sizeof(iface->subnet_mask));
+ } else {
+ sysfs_get_str(iface_kern_id, ISCSI_IFACE_SUBSYS,
+ "ipaddr_autocfg",
+ iface->ipv6_autocfg, sizeof(iface->ipv6_autocfg));
+
+ sysfs_get_str(iface_kern_id, ISCSI_IFACE_SUBSYS,
+ "link_local_addr", iface->ipv6_linklocal,
+ sizeof(iface->ipv6_linklocal));
+
+ sysfs_get_str(iface_kern_id, ISCSI_IFACE_SUBSYS,
+ "link_local_autocfg", iface->linklocal_autocfg,
+ sizeof(iface->linklocal_autocfg));
+
+ sysfs_get_str(iface_kern_id, ISCSI_IFACE_SUBSYS, "router_addr",
+ iface->ipv6_router,
+ sizeof(iface->ipv6_router));
+ }
+
+ if (sysfs_get_uint16(iface_kern_id, ISCSI_IFACE_SUBSYS, "port",
+ &iface->port))
+ iface->port = 0;
+ if (sysfs_get_uint16(iface_kern_id, ISCSI_IFACE_SUBSYS, "mtu",
+ &iface->mtu))
+ iface->mtu = 0;
+ if (sysfs_get_uint16(iface_kern_id, ISCSI_IFACE_SUBSYS, "vlan_id",
+ &iface->vlan_id))
+ iface->vlan_id = UINT16_MAX;
+
+ if (sysfs_get_uint8(iface_kern_id, ISCSI_IFACE_SUBSYS, "vlan_priority",
+ &iface->vlan_priority))
+ iface->vlan_priority = UINT8_MAX;
+
+ if (sscanf(iface_kern_id, "ipv%d-iface-%u-%u", &iface_type,
+ &tmp_host_no, &iface_num) == 3)
+ iface->iface_num = iface_num;
+done:
+ if (ret)
+ return ISCSI_ERR_SYSFS_LOOKUP;
+ else
+ return 0;
}
int iscsi_sysfs_get_hostinfo_by_host_no(struct host_info *hinfo)
{
- return iscsi_sysfs_read_iface(&hinfo->iface, hinfo->host_no, NULL);
+ return iscsi_sysfs_read_iface(&hinfo->iface, hinfo->host_no, NULL,
+ NULL);
}
int iscsi_sysfs_for_each_host(void *data, int *nr_found,
@@ -540,7 +632,7 @@ int iscsi_sysfs_for_each_host(void *data
info = malloc(sizeof(*info));
if (!info)
- return ENOMEM;
+ return ISCSI_ERR_NOMEM;
n = scandir(ISCSI_HOST_DIR, &namelist, trans_filter,
alphasort);
@@ -572,6 +664,50 @@ free_info:
return rc;
}
+int iscsi_sysfs_for_each_iface_on_host(void *data, uint32_t host_no,
+ int *nr_found,
+ iscsi_sysfs_iface_op_fn *fn)
+{
+ struct dirent **namelist;
+ int rc = 0, i, n;
+ struct iface_rec iface;
+ char devpath[PATH_SIZE];
+ char sysfs_path[PATH_SIZE];
+ char id[NAME_SIZE];
+
+ snprintf(id, sizeof(id), "host%u", host_no);
+ if (!sysfs_lookup_devpath_by_subsys_id(devpath, sizeof(devpath),
+ SCSI_SUBSYS, id)) {
+ log_error("Could not look up host's ifaces via scsi bus.");
+ return ISCSI_ERR_SYSFS_LOOKUP;
+ }
+
+ sprintf(sysfs_path, "/sys");
+ strlcat(sysfs_path, devpath, sizeof(sysfs_path));
+ strlcat(sysfs_path, "/iscsi_iface", sizeof(sysfs_path));
+
+ n = scandir(sysfs_path, &namelist, trans_filter, alphasort);
+ if (n <= 0)
+ /* older kernels or some drivers will not have ifaces */
+ return 0;
+
+ for (i = 0; i < n; i++) {
+ memset(&iface, 0, sizeof(iface));
+
+ iscsi_sysfs_read_iface(&iface, host_no, NULL,
+ namelist[i]->d_name);
+ rc = fn(data, &iface);
+ if (rc != 0)
+ break;
+ (*nr_found)++;
+ }
+
+ for (i = 0; i < n; i++)
+ free(namelist[i]);
+ free(namelist);
+ return rc;
+}
+
/**
* sysfs_session_has_leadconn - checks if session has lead conn in kernel
* @sid: session id
@@ -631,7 +767,7 @@ int iscsi_sysfs_get_sid_from_path(char *
if (!dev) {
log_error("Could not get dev for %s. Possible sysfs "
"incompatibility.\n", devpath);
- exit(1);
+ return -1;
}
if (!strncmp(dev->kernel, "session", 7))
@@ -645,8 +781,7 @@ int iscsi_sysfs_get_sid_from_path(char *
}
log_error("Unable to find sid in path %s", session);
- exit(1);
- return 0;
+ return -1;
}
int iscsi_sysfs_get_sessioninfo_by_id(struct session_info *info, char *session)
@@ -657,21 +792,65 @@ int iscsi_sysfs_get_sessioninfo_by_id(st
if (sscanf(session, "session%d", &info->sid) != 1) {
log_error("invalid session '%s'", session);
- return EINVAL;
+ return ISCSI_ERR_INVAL;
}
ret = sysfs_get_str(session, ISCSI_SESSION_SUBSYS, "targetname",
info->targetname, sizeof(info->targetname));
if (ret) {
log_error("could not read session targetname: %d", ret);
- return ret;
+ return ISCSI_ERR_SYSFS_LOOKUP;
}
+ ret = sysfs_get_str(session, ISCSI_SESSION_SUBSYS, "username",
+ (info->chap).username,
+ sizeof((info->chap).username));
+ if (ret)
+ log_debug(5, "could not read username: %d", ret);
+
+ ret = sysfs_get_str(session, ISCSI_SESSION_SUBSYS, "password",
+ (info->chap).password,
+ sizeof((info->chap).password));
+ if (ret)
+ log_debug(5, "could not read password: %d", ret);
+
+ ret = sysfs_get_str(session, ISCSI_SESSION_SUBSYS, "username_in",
+ (info->chap).username_in,
+ sizeof((info->chap).username_in));
+ if (ret)
+ log_debug(5, "could not read username in: %d", ret);
+
+ ret = sysfs_get_str(session, ISCSI_SESSION_SUBSYS, "password_in",
+ (info->chap).password_in,
+ sizeof((info->chap).password_in));
+ if (ret)
+ log_debug(5, "could not read password in: %d", ret);
+
+ ret = sysfs_get_int(session, ISCSI_SESSION_SUBSYS, "recovery_tmo",
+ &((info->tmo).recovery_tmo));
+ if (ret)
+ (info->tmo).recovery_tmo = -1;
+
+ ret = sysfs_get_int(session, ISCSI_SESSION_SUBSYS, "lu_reset_tmo",
+ &((info->tmo).lu_reset_tmo));
+ if (ret)
+ (info->tmo).lu_reset_tmo = -1;
+
+ ret = sysfs_get_int(session, ISCSI_SESSION_SUBSYS, "tgt_reset_tmo",
+ &((info->tmo).tgt_reset_tmo));
+ if (ret)
+ (info->tmo).lu_reset_tmo = -1;
+
+ sysfs_get_int(session, ISCSI_SESSION_SUBSYS, "abort_tmo",
+ &((info->tmo).abort_tmo));
+ if (ret)
+ (info->tmo).abort_tmo = -1;
+
ret = sysfs_get_int(session, ISCSI_SESSION_SUBSYS, "tpgt",
&info->tpgt);
if (ret) {
- log_error("could not read session tpgt: %u", ret);
- return ret;
+ log_error("could not read session tpgt: %d", ret);
+ return ISCSI_ERR_SYSFS_LOOKUP;
}
snprintf(id, sizeof(id), ISCSI_CONN_ID, info->sid);
@@ -727,13 +906,13 @@ int iscsi_sysfs_get_sessioninfo_by_id(st
ret = 0;
host_no = iscsi_sysfs_get_host_no_from_sid(info->sid, &ret);
if (ret) {
- log_error("could not get host_no for session%d err %d.",
- info->sid, ret);
+ log_error("could not get host_no for session%d: %s.",
+ info->sid, iscsi_err_to_str(ret));
return ret;
}
- iscsi_sysfs_read_iface(&info->iface, host_no, session);
-
+ iscsi_sysfs_read_iface(&info->iface, host_no, session, NULL);
+
log_debug(7, "found targetname %s address %s pers address %s port %d "
"pers port %d driver %s iface name %s ipaddress %s "
"netdev %s hwaddress %s iname %s",
@@ -745,7 +924,7 @@ int iscsi_sysfs_get_sessioninfo_by_id(st
info->iface.iname);
return 0;
}
-
+
int iscsi_sysfs_for_each_session(void *data, int *nr_found,
iscsi_sysfs_session_op_fn *fn)
{
@@ -755,7 +934,7 @@ int iscsi_sysfs_for_each_session(void *d
info = calloc(1, sizeof(*info));
if (!info)
- return ENOMEM;
+ return ISCSI_ERR_NOMEM;
n = scandir(ISCSI_SESSION_DIR, &namelist, trans_filter,
alphasort);
@@ -797,8 +976,10 @@ int iscsi_sysfs_get_session_state(char *
char id[NAME_SIZE];
snprintf(id, sizeof(id), ISCSI_SESSION_ID, sid);
- return sysfs_get_str(id, ISCSI_SESSION_SUBSYS, "state", state,
- SCSI_MAX_STATE_VALUE);
+ if (sysfs_get_str(id, ISCSI_SESSION_SUBSYS, "state", state,
+ SCSI_MAX_STATE_VALUE))
+ return ISCSI_ERR_SYSFS_LOOKUP;
+ return 0;
}
int iscsi_sysfs_get_host_state(char *state, int host_no)
@@ -806,8 +987,10 @@ int iscsi_sysfs_get_host_state(char *sta
char id[NAME_SIZE];
snprintf(id, sizeof(id), ISCSI_HOST_ID, host_no);
- return sysfs_get_str(id, SCSI_HOST_SUBSYS, "state", state,
- SCSI_MAX_STATE_VALUE);
+ if (sysfs_get_str(id, SCSI_HOST_SUBSYS, "state", state,
+ SCSI_MAX_STATE_VALUE))
+ return ISCSI_ERR_SYSFS_LOOKUP;
+ return 0;
}
int iscsi_sysfs_get_device_state(char *state, int host_no, int target, int lun)
@@ -818,7 +1001,7 @@ int iscsi_sysfs_get_device_state(char *s
if (sysfs_get_str(id, SCSI_SUBSYS, "state", state,
SCSI_MAX_STATE_VALUE)) {
log_debug(3, "Could not read attr state for %s\n", id);
- return EIO;
+ return ISCSI_ERR_SYSFS_LOOKUP;
}
return 0;
@@ -828,7 +1011,6 @@ char *iscsi_sysfs_get_blockdev_from_lun(
{
char devpath[PATH_SIZE];
char path_full[PATH_SIZE];
- char *path;
char id[NAME_SIZE];
DIR *dirfd;
struct dirent *dent;
@@ -845,9 +1027,8 @@ char *iscsi_sysfs_get_blockdev_from_lun(
}
sysfs_len = strlcpy(path_full, sysfs_path, sizeof(path_full));
- if(sysfs_len >= sizeof(path_full))
+ if (sysfs_len >= sizeof(path_full))
sysfs_len = sizeof(path_full) - 1;
- path = &path_full[sysfs_len];
strlcat(path_full, devpath, sizeof(path_full));
dirfd = opendir(path_full);
@@ -912,14 +1093,13 @@ static uint32_t get_target_no_from_sid(u
{
char devpath[PATH_SIZE];
char path_full[PATH_SIZE];
- char *path;
char id[NAME_SIZE];
DIR *dirfd;
struct dirent *dent;
uint32_t host, bus, target = 0;
size_t sysfs_len;
- *err = ENODEV;
+ *err = ISCSI_ERR_SESS_NOT_FOUND;
snprintf(id, sizeof(id), "session%u", sid);
if (!sysfs_lookup_devpath_by_subsys_id(devpath, sizeof(devpath),
@@ -935,9 +1115,8 @@ static uint32_t get_target_no_from_sid(u
* /class/iscsi_session/sessionX/device.
*/
sysfs_len = strlcpy(path_full, sysfs_path, sizeof(path_full));
- if(sysfs_len >= sizeof(path_full))
+ if (sysfs_len >= sizeof(path_full))
sysfs_len = sizeof(path_full) - 1;
- path = &path_full[sysfs_len];
strlcat(path_full, devpath, sizeof(path_full));
strlcat(path_full, "/device", sizeof(devpath));
@@ -970,7 +1149,8 @@ struct iscsi_transport *iscsi_sysfs_get_
struct iscsi_transport *t;
/* sync up kernel and userspace */
- read_transports();
+ if (read_transports())
+ return NULL;
/* check if the transport is loaded and matches */
list_for_each_entry(t, &transports, list) {
@@ -1043,6 +1223,19 @@ int iscsi_sysfs_get_exp_statsn(int sid)
return exp_statsn;
}
+int iscsi_sysfs_session_supports_nop(int sid)
+{
+ char id[NAME_SIZE];
+ uint32_t ping_tmo = 0;
+
+ snprintf(id, sizeof(id), ISCSI_CONN_ID, sid);
+ if (sysfs_get_uint(id, ISCSI_CONN_SUBSYS, "ping_tmo",
+ &ping_tmo)) {
+ return 0;
+ }
+ return 1;
+}
+
int iscsi_sysfs_for_each_device(void *data, int host_no, uint32_t sid,
void (* fn)(void *data, int host_no,
int target, int lun))
@@ -1061,7 +1254,7 @@ int iscsi_sysfs_for_each_device(void *da
ISCSI_SESSION_SUBSYS, id)) {
log_debug(3, "Could not lookup devpath for %s %s\n",
ISCSI_SESSION_SUBSYS, id);
- return EIO;
+ return ISCSI_ERR_SYSFS_LOOKUP;
}
snprintf(path_full, sizeof(path_full), "%s%s/device/target%d:0:%d",
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/iscsi_sysfs.h open-iscsi-2.0-872-rc4-bnx2i.work/usr/iscsi_sysfs.h
--- open-iscsi-2.0-872-rc4-bnx2i/usr/iscsi_sysfs.h 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/iscsi_sysfs.h 2012-03-05 23:05:31.000000000 -0600
@@ -43,7 +43,11 @@ extern int iscsi_sysfs_session_has_leadc
typedef int (iscsi_sysfs_session_op_fn)(void *, struct session_info *);
typedef int (iscsi_sysfs_host_op_fn)(void *, struct host_info *);
+typedef int (iscsi_sysfs_iface_op_fn)(void *, struct iface_rec *);
+extern int iscsi_sysfs_for_each_iface_on_host(void *data, uint32_t host_no,
+ int *nr_found,
+ iscsi_sysfs_iface_op_fn *fn);
extern int iscsi_sysfs_for_each_session(void *data, int *nr_found,
iscsi_sysfs_session_op_fn *fn);
extern int iscsi_sysfs_for_each_host(void *data, int *nr_found,
@@ -51,6 +55,7 @@ extern int iscsi_sysfs_for_each_host(voi
extern uint32_t iscsi_sysfs_get_host_no_from_sid(uint32_t sid, int *err);
extern uint32_t iscsi_sysfs_get_host_no_from_hwinfo(struct iface_rec *iface,
int *rc);
+extern uint32_t iscsi_sysfs_get_host_no_from_hwaddress(char *hwaddress, int *rc);
extern int iscsi_sysfs_get_hostinfo_by_host_no(struct host_info *hinfo);
extern int iscsi_sysfs_get_sid_from_path(char *session);
extern char *iscsi_sysfs_get_blockdev_from_lun(int hostno, int target, int sid);
@@ -84,6 +89,8 @@ extern struct iscsi_transport *iscsi_sys
extern struct iscsi_transport *iscsi_sysfs_get_transport_by_session(char *sys_session);
extern struct iscsi_transport *iscsi_sysfs_get_transport_by_sid(uint32_t sid);
extern struct iscsi_transport *iscsi_sysfs_get_transport_by_name(char *transport_name);
+extern int iscsi_sysfs_session_supports_nop(int sid);
+extern int iscsi_sysfs_session_user_created(int sid);
extern struct list_head transports;
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/iscsi_timer.c open-iscsi-2.0-872-rc4-bnx2i.work/usr/iscsi_timer.c
--- open-iscsi-2.0-872-rc4-bnx2i/usr/iscsi_timer.c 1969-12-31 18:00:00.000000000 -0600
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/iscsi_timer.c 2012-03-05 23:02:46.000000000 -0600
@@ -0,0 +1,86 @@
+/*
+ * iSCSI timer
+ *
+ * Copyright (C) 2002 Cisco Systems, Inc.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published
+ * by the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * General Public License for more details.
+ *
+ * See the file COPYING included with this distribution for more details.
+ */
+#include <string.h>
+#include <sys/time.h>
+
+void iscsi_timer_clear(struct timeval *timer)
+{
+ memset(timer, 0, sizeof (*timer));
+}
+
+/* set timer to now + seconds */
+void iscsi_timer_set(struct timeval *timer, int seconds)
+{
+ if (timer) {
+ memset(timer, 0, sizeof (*timer));
+ gettimeofday(timer, NULL);
+
+ timer->tv_sec += seconds;
+ }
+}
+
+int iscsi_timer_expired(struct timeval *timer)
+{
+ struct timeval now;
+
+ /* no timer, can't have expired */
+ if ((timer == NULL) || ((timer->tv_sec == 0) && (timer->tv_usec == 0)))
+ return 0;
+
+ memset(&now, 0, sizeof (now));
+ gettimeofday(&now, NULL);
+
+ if (now.tv_sec > timer->tv_sec)
+ return 1;
+ if ((now.tv_sec == timer->tv_sec) && (now.tv_usec >= timer->tv_usec))
+ return 1;
+ return 0;
+}
+
+int iscsi_timer_msecs_until(struct timeval *timer)
+{
+ struct timeval now;
+ int msecs;
+ long partial;
+
+ /* no timer, can't have expired, infinite time til it expires */
+ if ((timer == NULL) || ((timer->tv_sec == 0) && (timer->tv_usec == 0)))
+ return -1;
+
+ memset(&now, 0, sizeof (now));
+ gettimeofday(&now, NULL);
+
+ /* already expired? */
+ if (now.tv_sec > timer->tv_sec)
+ return 0;
+ if ((now.tv_sec == timer->tv_sec) && (now.tv_usec >= timer->tv_usec))
+ return 0;
+
+ /* not expired yet, do the math */
+ partial = timer->tv_usec - now.tv_usec;
+ if (partial < 0) {
+ partial += 1000 * 1000;
+ msecs = (partial + 500) / 1000;
+ msecs += (timer->tv_sec - now.tv_sec - 1) * 1000;
+ } else {
+ msecs = (partial + 500) / 1000;
+ msecs += (timer->tv_sec - now.tv_sec) * 1000;
+ }
+
+ return msecs;
+}
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/iscsi_timer.h open-iscsi-2.0-872-rc4-bnx2i.work/usr/iscsi_timer.h
--- open-iscsi-2.0-872-rc4-bnx2i/usr/iscsi_timer.h 1969-12-31 18:00:00.000000000 -0600
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/iscsi_timer.h 2012-03-05 23:02:46.000000000 -0600
@@ -0,0 +1,28 @@
+/*
+ * iSCSI timer
+ *
+ * Copyright (C) 2002 Cisco Systems, Inc.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published
+ * by the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * General Public License for more details.
+ *
+ * See the file COPYING included with this distribution for more details.
+ */
+#ifndef ISCSI_TIMER_H
+#define ISCSI_TIMER_H
+
+struct timeval;
+
+extern void iscsi_timer_clear(struct timeval *timer);
+extern void iscsi_timer_set(struct timeval *timer, int seconds);
+extern int iscsi_timer_expired(struct timeval *timer);
+extern int iscsi_timer_msecs_until(struct timeval *timer);
+
+#endif
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/iscsi_util.c open-iscsi-2.0-872-rc4-bnx2i.work/usr/iscsi_util.c
--- open-iscsi-2.0-872-rc4-bnx2i/usr/iscsi_util.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/iscsi_util.c 2012-03-05 23:02:46.000000000 -0600
@@ -25,12 +25,15 @@
#include <string.h>
#include <errno.h>
#include <ctype.h>
+#include <sys/types.h>
+#include <sys/stat.h>
#include <sys/resource.h>
#include "log.h"
#include "iscsi_settings.h"
#include "iface.h"
#include "session_info.h"
+#include "iscsi_util.h"
void daemon_init(void)
{
@@ -45,24 +48,38 @@ void daemon_init(void)
dup2(fd, 1);
dup2(fd, 2);
setsid();
- chdir("/");
+ if (chdir("/") < 0)
+ log_debug(1, "Could not chdir to /: %s", strerror(errno));
}
+#define ISCSI_OOM_PATH_LEN 48
+
int oom_adjust(void)
{
int fd;
- char path[48];
+ char path[ISCSI_OOM_PATH_LEN];
+ struct stat statb;
- nice(-10);
- sprintf(path, "/proc/%d/oom_adj", getpid());
+ if (nice(-10) < 0)
+ log_debug(1, "Could not increase process priority: %s",
+ strerror(errno));
+
+ snprintf(path, ISCSI_OOM_PATH_LEN, "/proc/%d/oom_score_adj", getpid());
+ if (stat(path, &statb)) {
+ /* older kernel so use old oom_adj file */
+ snprintf(path, ISCSI_OOM_PATH_LEN, "/proc/%d/oom_adj",
+ getpid());
+ }
fd = open(path, O_WRONLY);
- if (fd < 0) {
+ if (fd < 0)
return -1;
- }
- write(fd, "-16\n", 3); /* for 2.6.11 */
- write(fd, "-17\n", 3); /* for Andrea's patch */
+ if (write(fd, "-16", 3) < 0) /* for 2.6.11 */
+ log_debug(1, "Could not set oom score to -16: %s",
+ strerror(errno));
+ if (write(fd, "-17", 3) < 0) /* for Andrea's patch */
+ log_debug(1, "Could not set oom score to -17: %s",
+ strerror(errno));
close(fd);
-
return 0;
}
@@ -217,31 +234,92 @@ char *cfg_get_string_param(char *pathnam
return value;
}
+/**
+ * iscsi_addr_match - check if the addrs are to the same ip
+ * @address1: pattern
+ * @address2: address to check
+ *
+ * If address1 is blank then it matches any string passed in.
+ */
+static int iscsi_addr_match(char *address1, char *address2)
+{
+ struct addrinfo hints1, hints2, *res1, *res2;
+ int rc;
+
+ if (!strlen(address1))
+ return 1;
+
+ if (!strcmp(address1, address2))
+ return 1;
+
+ memset(&hints1, 0, sizeof(struct addrinfo));
+ hints1.ai_family = AF_UNSPEC;
+ hints1.ai_socktype = SOCK_STREAM;
+
+ memset(&hints2, 0, sizeof(struct addrinfo));
+ hints2.ai_family = AF_UNSPEC;
+ hints2.ai_socktype = SOCK_STREAM;
+
+ /*
+ * didn't match so we have to resolve to see if one is a dnsname
+ * that matches a ip address.
+ */
+ rc = getaddrinfo(address1, NULL, &hints1, &res1);
+ if (rc) {
+ log_debug(1, "Match error. Could not resolve %s: %s", address1,
+ gai_strerror(rc));
+ return 0;
+
+ }
+
+ rc = getaddrinfo(address2, NULL, &hints2, &res2);
+ if (rc) {
+ log_debug(1, "Match error. Could not resolve %s: %s", address2,
+ gai_strerror(rc));
+ rc = 0;
+ goto free_res1;
+ }
+
+ if ((res1->ai_addrlen != res2->ai_addrlen) ||
+ memcmp(res1->ai_addr, res2->ai_addr, res2->ai_addrlen))
+ rc = 0;
+ else
+ rc = 1;
+
+ freeaddrinfo(res2);
+free_res1:
+ freeaddrinfo(res1);
+ return rc;
+}
+
int __iscsi_match_session(node_rec_t *rec, char *targetname,
- char *address, int port, struct iface_rec *iface)
+ char *address, int port, struct iface_rec *iface,
+ unsigned sid)
{
if (!rec) {
log_debug(6, "no rec info to match\n");
return 1;
}
- log_debug(6, "match session [%s,%s,%d][%s %s,%s,%s]",
+ log_debug(6, "match session [%s,%s,%d][%s %s,%s,%s]:%u",
rec->name, rec->conn[0].address, rec->conn[0].port,
rec->iface.name, rec->iface.transport_name,
- rec->iface.hwaddress, rec->iface.ipaddress);
+ rec->iface.hwaddress, rec->iface.ipaddress,
+ rec->session.sid);
if (iface)
- log_debug(6, "to [%s,%s,%d][%s %s,%s,%s]",
+ log_debug(6, "to [%s,%s,%d][%s %s,%s,%s]:%u",
targetname, address, port, iface->name,
iface->transport_name, iface->hwaddress,
- iface->ipaddress);
+ iface->ipaddress, sid);
+ if (rec->session.sid && sid && rec->session.sid != sid)
+ return 0;
if (strlen(rec->name) && strcmp(rec->name, targetname))
return 0;
- if (strlen(rec->conn[0].address) &&
- strcmp(rec->conn[0].address, address))
+ if (!iscsi_addr_match(rec->conn[0].address, address))
return 0;
if (rec->conn[0].port != -1 && port != rec->conn[0].port)
@@ -257,5 +335,27 @@ int iscsi_match_session(void *data, stru
{
return __iscsi_match_session(data, info->targetname,
info->persistent_address,
- info->persistent_port, &info->iface);
+ info->persistent_port, &info->iface,
+ info->sid);
+}
+
+int iscsi_match_session_count(void *data, struct session_info *info)
+{
+ /*
+ * iscsi_sysfs_for_each_session expects:
+ * 0==match -1==nomatch >0==error
+ * but iscsi_match_session returns:
+ * 1==match 0==nomatch
+ */
+ if (iscsi_match_session(data, info))
+ return 0;
+ return -1;
+}
+
+int iscsi_match_target(void *data, struct session_info *info)
+{
+ return __iscsi_match_session(data, info->targetname,
+ info->persistent_address,
+ info->persistent_port, NULL,
+ MATCH_ANY_SID);
}
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/iscsi_util.h open-iscsi-2.0-872-rc4-bnx2i.work/usr/iscsi_util.h
--- open-iscsi-2.0-872-rc4-bnx2i/usr/iscsi_util.h 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/iscsi_util.h 2012-03-05 23:02:46.000000000 -0600
@@ -14,9 +14,14 @@ extern int increase_max_files(void);
extern char *str_to_ipport(char *str, int *port, int *tgpt);
extern int iscsi_match_session(void *data, struct session_info *info);
+extern int iscsi_match_target(void *data, struct session_info *info);
+extern int iscsi_match_session_count(void *data, struct session_info *info);
extern int __iscsi_match_session(struct node_rec *rec, char *targetname,
char *address, int port,
- struct iface_rec *iface);
+ struct iface_rec *iface,
+ unsigned sid);
+
+#define MATCH_ANY_SID 0
extern char *strstrip(char *s);
extern char *cfg_get_string_param(char *pathname, const char *key);
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/iser.c open-iscsi-2.0-872-rc4-bnx2i.work/usr/iser.c
--- open-iscsi-2.0-872-rc4-bnx2i/usr/iser.c 1969-12-31 18:00:00.000000000 -0600
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/iser.c 2012-03-05 23:06:13.000000000 -0600
@@ -0,0 +1,22 @@
+/*
+ * iser helpers
+ *
+ * Copyright (C) 2012 Red Hat, Inc. All rights reserved.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published
+ * by the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * General Public License for more details.
+ */
+#include "initiator.h"
+
+void iser_create_conn(struct iscsi_conn *conn)
+{
+ /* header digests not supported in iser */
+ conn->hdrdgst_en = ISCSI_DIGEST_NONE;
+}
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/iser.h open-iscsi-2.0-872-rc4-bnx2i.work/usr/iser.h
--- open-iscsi-2.0-872-rc4-bnx2i/usr/iser.h 1969-12-31 18:00:00.000000000 -0600
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/iser.h 2012-03-05 23:06:13.000000000 -0600
@@ -0,0 +1,8 @@
+#ifndef ISER_TRANSPORT
+#define ISER_TRANSPORT
+
+struct iscsi_conn;
+
+extern void iser_create_conn(struct iscsi_conn *conn);
+
+#endif
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/kern_err_table.c open-iscsi-2.0-872-rc4-bnx2i.work/usr/kern_err_table.c
--- open-iscsi-2.0-872-rc4-bnx2i/usr/kern_err_table.c 1969-12-31 18:00:00.000000000 -0600
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/kern_err_table.c 2012-03-05 23:03:56.000000000 -0600
@@ -0,0 +1,83 @@
+/*
+ * Copyright (C) 2011 Aastha Mehta
+ * Copyright (C) 2011 Mike Christie
+ *
+ * maintained by open-iscsi@googlegroups.com
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published
+ * by the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * General Public License for more details.
+ *
+ * See the file COPYING included with this distribution for more details.
+ */
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include "iscsi_if.h"
+
+#include "kern_err_table.h"
+
+const char *kern_err_code_to_string(int err)
+{
+ switch (err){
+ case ISCSI_OK:
+ return "ISCSI_OK: operation successful";
+ case ISCSI_ERR_DATASN:
+ return "ISCSI_ERR_DATASN: Received invalid data sequence "
+ "number from target";
+ case ISCSI_ERR_DATA_OFFSET:
+ return "ISCSI_ERR_DATA_OFFSET: Seeking offset beyond the size "
+ "of the iSCSI segment";
+ case ISCSI_ERR_MAX_CMDSN:
+ return "ISCSI_ERR_MAX_CMDSN: Received invalid command sequence "
+ "number from target";
+ case ISCSI_ERR_EXP_CMDSN:
+ return "ISCSI_ERR_EXP_CMDSN: Received invalid expected command " "sequence number from target";
+ case ISCSI_ERR_BAD_OPCODE:
+ return "ISCSI_ERR_BAD_OPCODE: Received an invalid iSCSI opcode";
+ case ISCSI_ERR_DATALEN:
+ return "ISCSI_ERR_DATALEN: Invalid data length value";
+ case ISCSI_ERR_AHSLEN:
+ return "ISCSI_ERR_AHSLEN: Received an invalid AHS length";
+ case ISCSI_ERR_PROTO:
+ return "ISCSI_ERR_PROTO: iSCSI protocol violation";
+ case ISCSI_ERR_LUN:
+ return "ISCSI_ERR_LUN: LUN mismatch";
+ case ISCSI_ERR_BAD_ITT:
+ return "ISCSI_ERR_BAD_ITT: Received invalid initiator task tag " "from target";
+ case ISCSI_ERR_CONN_FAILED:
+ return "ISCSI_ERR_CONN_FAILED: iSCSI connection failed";
+ case ISCSI_ERR_R2TSN:
+ return "ISCSI_ERR_R2TSN: Received invalid R2T (Ready to "
+ "Transfer) data sequence number from target";
+ case ISCSI_ERR_SESSION_FAILED:
+ return "ISCSI_ERR_SESSION_FAILED: iSCSI session failed";
+ case ISCSI_ERR_HDR_DGST:
+ return "ISCSI_ERR_HDR_DGST: Header digest mismatch";
+ case ISCSI_ERR_DATA_DGST:
+ return "ISCSI_ERR_DATA_DGST: Data digest mismatch";
+ case ISCSI_ERR_PARAM_NOT_FOUND:
+ return "ISCSI_ERR_PARAM_NOT_FOUND: Parameter not found";
+ case ISCSI_ERR_NO_SCSI_CMD:
+ return "ISCSI_ERR_NO_SCSI_CMD: Could not look up SCSI command";
+ case ISCSI_ERR_INVALID_HOST:
+ return "ISCSI_ERR_INVALID_HOST: iSCSI host is in an invalid "
+ "state";
+ case ISCSI_ERR_XMIT_FAILED:
+ return "ISCSI_ERR_XMIT_FAILED: Transmission of iSCSI packet "
+ "failed";
+ case ISCSI_ERR_TCP_CONN_CLOSE:
+ return "ISCSI_ERR_TCP_CONN_CLOSE: TCP connection closed";
+ case ISCSI_ERR_SCSI_EH_SESSION_RST:
+ return "ISCSI_ERR_SCSI_EH_SESSION_RST: Session was dropped as "
+ "a result of SCSI error recovery";
+ default:
+ return "Invalid or unknown error code";
+ }
+}
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/kern_err_table.h open-iscsi-2.0-872-rc4-bnx2i.work/usr/kern_err_table.h
--- open-iscsi-2.0-872-rc4-bnx2i/usr/kern_err_table.h 1969-12-31 18:00:00.000000000 -0600
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/kern_err_table.h 2012-03-05 23:03:56.000000000 -0600
@@ -0,0 +1,23 @@
+/*
+ * Copyright (C) 2011 Aastha Mehta
+ * Copyright (C) 2011 Mike Christie
+ *
+ * maintained by open-iscsi@googlegroups.com
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published
+ * by the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * General Public License for more details.
+ *
+ * See the file COPYING included with this distribution for more details.
+ */
+#ifndef __KERN_ERR_TABLE_H__
+#define __KERN_ERR_TABLE_H__
+
+extern const char *kern_err_code_to_string(int);
+#endif
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/log.c open-iscsi-2.0-872-rc4-bnx2i.work/usr/log.c
--- open-iscsi-2.0-872-rc4-bnx2i/usr/log.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/log.c 2012-03-05 23:02:46.000000000 -0600
@@ -326,6 +326,7 @@ void log_info(const char *fmt, ...)
va_end(ap);
}
+#if 0 /* Unused */
static void __dump_line(int level, unsigned char *buf, int *cp)
{
char line[16*3+5], *lp = line;
@@ -359,6 +360,7 @@ static void __dump_char(int level, unsig
#define dump_line() __dump_line(level, char_buf, &char_cnt)
#define dump_char(ch) __dump_char(level, char_buf, &char_cnt, ch)
+#endif /* Unused */
static void log_flush(void)
{
@@ -474,6 +476,8 @@ void log_close(pid_t pid)
return;
}
- kill(pid, SIGTERM);
- waitpid(pid, &status, 0);
+ if (pid > 0) {
+ kill(pid, SIGTERM);
+ waitpid(pid, &status, 0);
+ }
}
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/login.c open-iscsi-2.0-872-rc4-bnx2i.work/usr/login.c
--- open-iscsi-2.0-872-rc4-bnx2i/usr/login.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/login.c 2012-03-05 23:02:46.000000000 -0600
@@ -27,11 +27,14 @@
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
+#include <poll.h>
+#include <errno.h>
#include <sys/param.h>
#include "initiator.h"
#include "transport.h"
#include "log.h"
+#include "iscsi_timer.h"
/* caller is assumed to be well-behaved and passing NUL terminated strings */
int
@@ -1434,11 +1437,15 @@ int
iscsi_login_rsp(iscsi_session_t *session, iscsi_login_context_t *c)
{
iscsi_conn_t *conn = &session->conn[c->cid];
+ int err;
/* read the target's response into the same buffer */
- if (!iscsi_io_recv_pdu(conn, &c->pdu, ISCSI_DIGEST_NONE, c->data,
- c->max_data_length, ISCSI_DIGEST_NONE,
- c->timeout)) {
+ err = iscsi_io_recv_pdu(conn, &c->pdu, ISCSI_DIGEST_NONE, c->data,
+ c->max_data_length, ISCSI_DIGEST_NONE,
+ c->timeout);
+ if (err == -EAGAIN) {
+ goto done;
+ } else if (err < 0) {
/*
* FIXME: caller might want us to distinguish I/O
* error and timeout. Might want to switch portals on
@@ -1449,6 +1456,7 @@ iscsi_login_rsp(iscsi_session_t *session
goto done;
}
+ err = -EIO;
c->received_pdu = 1;
/* check the PDU response type */
@@ -1490,7 +1498,7 @@ iscsi_login_rsp(iscsi_session_t *session
if (c->ret == LOGIN_OK)
c->ret = LOGIN_FAILED;
}
- return 1;
+ return err;
}
/**
@@ -1514,7 +1522,9 @@ iscsi_login(iscsi_session_t *session, in
{
iscsi_conn_t *conn = &session->conn[cid];
iscsi_login_context_t *c = &conn->login_context;
- int ret;
+ struct timeval connection_timer;
+ struct pollfd pfd;
+ int ret, timeout;
/*
* assume iscsi_login is only called from discovery, so it is
@@ -1532,15 +1542,63 @@ iscsi_login(iscsi_session_t *session, in
do {
if (iscsi_login_req(session, c))
return c->ret;
- ret = iscsi_login_rsp(session, c);
- if (status_class)
- *status_class = c->status_class;
- if (status_detail)
- *status_detail = c->status_detail;
+ /*
+ * TODO: merge the poll and req/rsp code with the discovery
+ * poll and text req/rsp.
+ */
+ iscsi_timer_set(&connection_timer,
+ session->conn[0].active_timeout);
+ timeout = iscsi_timer_msecs_until(&connection_timer);
+
+ memset(&pfd, 0, sizeof (pfd));
+ pfd.fd = conn->socket_fd;
+ pfd.events = POLLIN | POLLPRI;
+
+repoll:
+ pfd.revents = 0;
+ ret = poll(&pfd, 1, timeout);
+ log_debug(7, "%s: Poll return %d\n", __FUNCTION__, ret);
+ if (iscsi_timer_expired(&connection_timer)) {
+ log_warning("Login response timeout. Waited %d "
+ "seconds and did not get reponse PDU.\n",
+ session->conn[0].active_timeout);
+ c->ret = LOGIN_FAILED;
+ return c->ret;
+ }
+
+ if (ret > 0) {
+ if (pfd.revents & (POLLIN | POLLPRI)) {
+ ret = iscsi_login_rsp(session, c);
+ if (ret == -EAGAIN)
+ goto repoll;
+
+ if (status_class)
+ *status_class = c->status_class;
+ if (status_detail)
+ *status_detail = c->status_detail;
+
+ if (ret)
+ return c->ret;
+ } else if (pfd.revents & POLLHUP) {
+ log_warning("Login POLLHUP");
+ c->ret = LOGIN_FAILED;
+ return c->ret;
+ } else if (pfd.revents & POLLNVAL) {
+ log_warning("Login POLLNVAL");
+ c->ret = LOGIN_IO_ERROR;
+ return c->ret;
+ } else if (pfd.revents & POLLERR) {
+ log_warning("Login POLLERR");
+ c->ret = LOGIN_IO_ERROR;
+ return c->ret;
+ }
- if (ret)
+ } else if (ret < 0) {
+ log_error("Login poll error.\n");
+ c->ret = LOGIN_FAILED;
return c->ret;
+ }
} while (conn->current_stage != ISCSI_FULL_FEATURE_PHASE);
c->ret = LOGIN_OK;
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/Makefile open-iscsi-2.0-872-rc4-bnx2i.work/usr/Makefile
--- open-iscsi-2.0-872-rc4-bnx2i/usr/Makefile 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/Makefile 2012-03-05 23:06:13.000000000 -0600
@@ -21,10 +21,12 @@ ifeq ($(OSNAME),Linux)
endif
endif
IPC_OBJ=netlink.o
+DCB_OBJ=dcb_app.o
else
ifeq ($(OSNAME),FreeBSD)
IPC_CFLAGS=
IPC_OBJ=ioctl.o
+DCB_OBJ=
endif
endif
@@ -37,12 +39,13 @@ PROGRAMS = iscsid iscsiadm iscsistart
# libc compat files
SYSDEPS_SRCS = $(wildcard ../utils/sysdeps/*.o)
# sources shared between iscsid, iscsiadm and iscsistart
-ISCSI_LIB_SRCS = iscsi_util.o io.o auth.o login.o log.o md5.o sha1.o iface.o \
- idbm.o sysfs.o host.o session_info.o iscsi_sysfs.o iscsi_net_util.o \
- iscsid_req.o $(SYSDEPS_SRCS)
+ISCSI_LIB_SRCS = iscsi_util.o io.o auth.o iscsi_timer.o login.o log.o md5.o \
+ sha1.o iface.o idbm.o sysfs.o host.o session_info.o iscsi_sysfs.o \
+ iscsi_net_util.o iscsid_req.o transport.o iser.o cxgbi.o be2iscsi.o \
+ initiator_common.o iscsi_err.o $(IPC_OBJ) $(SYSDEPS_SRCS) $(DCB_OBJ)
# core initiator files
-INITIATOR_SRCS = initiator.o scsi.o actor.o event_poll.o mgmt_ipc.o \
- transport.o cxgb3i.o be2iscsi.o
+INITIATOR_SRCS = initiator.o scsi.o actor.o event_poll.o mgmt_ipc.o kern_err_table.o
+
# fw boot files
FW_BOOT_SRCS = $(wildcard ../utils/fwparam_ibft/*.o)
@@ -51,14 +54,14 @@ DISCOVERY_SRCS = $(FW_BOOT_SRCS) strings
all: $(PROGRAMS)
-iscsid: $(ISCSI_LIB_SRCS) $(IPC_OBJ) $(INITIATOR_SRCS) $(DISCOVERY_SRCS) \
+iscsid: $(ISCSI_LIB_SRCS) $(INITIATOR_SRCS) $(DISCOVERY_SRCS) \
iscsid.o session_mgmt.o discoveryd.o
- $(CC) $(CFLAGS) $^ -o $@ -L../utils/open-isns -lisns -lcrypto
+ $(CC) $(CFLAGS) $^ -o $@ -L../utils/open-isns -lisns
iscsiadm: $(ISCSI_LIB_SRCS) $(DISCOVERY_SRCS) iscsiadm.o session_mgmt.o
- $(CC) $(CFLAGS) $^ -o $@ -L../utils/open-isns -lisns -lcrypto
+ $(CC) $(CFLAGS) $^ -o $@ -L../utils/open-isns -lisns
-iscsistart: $(IPC_OBJ) $(ISCSI_LIB_SRCS) $(INITIATOR_SRCS) $(FW_BOOT_SRCS) \
+iscsistart: $(ISCSI_LIB_SRCS) $(INITIATOR_SRCS) $(FW_BOOT_SRCS) \
iscsistart.o statics.o
$(CC) $(CFLAGS) -static $^ -o $@
clean:
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/mgmt_ipc.c open-iscsi-2.0-872-rc4-bnx2i.work/usr/mgmt_ipc.c
--- open-iscsi-2.0-872-rc4-bnx2i/usr/mgmt_ipc.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/mgmt_ipc.c 2012-03-05 23:02:46.000000000 -0600
@@ -35,6 +35,7 @@
#include "transport.h"
#include "sysdeps.h"
#include "iscsi_ipc.h"
+#include "iscsi_err.h"
#define PEERUSER_MAX 64
#define EXTMSG_MAX (64 * 1024)
@@ -79,13 +80,13 @@ mgmt_ipc_close(int fd)
close(fd);
}
-static mgmt_ipc_err_e
+static int
mgmt_ipc_session_login(queue_task_t *qtask)
{
return session_login_task(&qtask->req.u.session.rec, qtask);
}
-static mgmt_ipc_err_e
+static int
mgmt_ipc_session_getstats(queue_task_t *qtask)
{
int sid = qtask->req.u.session.sid;
@@ -93,7 +94,7 @@ mgmt_ipc_session_getstats(queue_task_t *
int rc;
if (!(session = session_find_by_sid(sid)))
- return MGMT_IPC_ERR_NOT_FOUND;
+ return ISCSI_ERR_SESS_NOT_FOUND;
rc = ipc->get_stats(session->t->handle,
session->id, session->conn[0].id,
@@ -102,33 +103,33 @@ mgmt_ipc_session_getstats(queue_task_t *
if (rc) {
log_error("get_stats(): IPC error %d "
"session [%02d]", rc, sid);
- return MGMT_IPC_ERR_INTERNAL;
+ return ISCSI_ERR_INTERNAL;
}
- mgmt_ipc_write_rsp(qtask, MGMT_IPC_OK);
- return MGMT_IPC_OK;
+ mgmt_ipc_write_rsp(qtask, ISCSI_SUCCESS);
+ return ISCSI_SUCCESS;
}
-static mgmt_ipc_err_e
+static int
mgmt_ipc_send_targets(queue_task_t *qtask)
{
iscsiadm_req_t *req = &qtask->req;
- mgmt_ipc_err_e err;
+ int err;
err = iscsi_host_send_targets(qtask, req->u.st.host_no,
req->u.st.do_login,
&req->u.st.ss);
mgmt_ipc_write_rsp(qtask, err);
- return MGMT_IPC_OK;
+ return ISCSI_SUCCESS;
}
-static mgmt_ipc_err_e
+static int
mgmt_ipc_session_logout(queue_task_t *qtask)
{
return session_logout_task(qtask->req.u.session.sid, qtask);
}
-static mgmt_ipc_err_e
+static int
mgmt_ipc_session_sync(queue_task_t *qtask)
{
struct ipc_msg_session *session= &qtask->req.u.session;
@@ -136,16 +137,16 @@ mgmt_ipc_session_sync(queue_task_t *qtas
return iscsi_sync_session(&session->rec, qtask, session->sid);
}
-static mgmt_ipc_err_e
+static int
mgmt_ipc_cfg_initiatorname(queue_task_t *qtask)
{
if (dconfig->initiator_name)
strcpy(qtask->rsp.u.config.var, dconfig->initiator_name);
- mgmt_ipc_write_rsp(qtask, MGMT_IPC_OK);
- return MGMT_IPC_OK;
+ mgmt_ipc_write_rsp(qtask, ISCSI_SUCCESS);
+ return ISCSI_SUCCESS;
}
-static mgmt_ipc_err_e
+static int
mgmt_ipc_session_info(queue_task_t *qtask)
{
int sid = qtask->req.u.session.sid;
@@ -154,61 +155,50 @@ mgmt_ipc_session_info(queue_task_t *qtas
if (!(session = session_find_by_sid(sid))) {
log_debug(1, "session with sid %d not found!", sid);
- return MGMT_IPC_ERR_NOT_FOUND;
+ return ISCSI_ERR_SESS_NOT_FOUND;
}
info = &qtask->rsp.u.session_state;
info->conn_state = session->conn[0].state;
info->session_state = session->r_stage;
- mgmt_ipc_write_rsp(qtask, MGMT_IPC_OK);
- return MGMT_IPC_OK;
+ mgmt_ipc_write_rsp(qtask, ISCSI_SUCCESS);
+ return ISCSI_SUCCESS;
}
-static mgmt_ipc_err_e
+static int
mgmt_ipc_cfg_initiatoralias(queue_task_t *qtask)
{
strcpy(qtask->rsp.u.config.var, dconfig->initiator_alias);
- mgmt_ipc_write_rsp(qtask, MGMT_IPC_OK);
- return MGMT_IPC_OK;
+ mgmt_ipc_write_rsp(qtask, ISCSI_SUCCESS);
+ return ISCSI_SUCCESS;
}
-static mgmt_ipc_err_e
+static int
mgmt_ipc_cfg_filename(queue_task_t *qtask)
{
strcpy(qtask->rsp.u.config.var, dconfig->config_file);
- mgmt_ipc_write_rsp(qtask, MGMT_IPC_OK);
- return MGMT_IPC_OK;
+ mgmt_ipc_write_rsp(qtask, ISCSI_SUCCESS);
+ return ISCSI_SUCCESS;
}
-static mgmt_ipc_err_e
+static int
mgmt_ipc_conn_add(queue_task_t *qtask)
{
- return MGMT_IPC_ERR;
+ return ISCSI_ERR;
}
-static mgmt_ipc_err_e
+static int
mgmt_ipc_immediate_stop(queue_task_t *qtask)
{
event_loop_exit(qtask);
- return MGMT_IPC_OK;
+ return ISCSI_SUCCESS;
}
-static mgmt_ipc_err_e
+static int
mgmt_ipc_conn_remove(queue_task_t *qtask)
{
- return MGMT_IPC_ERR;
-}
-
-static mgmt_ipc_err_e
-mgmt_ipc_host_set_param(queue_task_t *qtask)
-{
- struct ipc_msg_set_host_param *hp = &qtask->req.u.set_host_param;
- int err;
-
- err = iscsi_host_set_param(hp->host_no, hp->param, hp->value);
- mgmt_ipc_write_rsp(qtask, err);
- return MGMT_IPC_OK;
+ return ISCSI_ERR;
}
/*
@@ -263,12 +253,11 @@ again:
return argc;
}
-static mgmt_ipc_err_e
-mgmt_ipc_notify_common(queue_task_t *qtask,
- mgmt_ipc_err_e (*handler)(int, char **))
+static int
+mgmt_ipc_notify_common(queue_task_t *qtask, int (*handler)(int, char **))
{
char **argv = NULL;
- int argc, err = MGMT_IPC_ERR;
+ int argc, err = ISCSI_ERR;
argc = mgmt_ipc_parse_strings(qtask, &argv);
if (argc > 0)
@@ -277,54 +266,54 @@ mgmt_ipc_notify_common(queue_task_t *qta
if (argv)
free(argv);
mgmt_ipc_write_rsp(qtask, err);
- return MGMT_IPC_OK;
+ return ISCSI_SUCCESS;
}
/* Replace these dummies as you implement them
elsewhere */
-static mgmt_ipc_err_e
+static int
iscsi_discovery_add_node(int argc, char **argv)
{
- return MGMT_IPC_OK;
+ return ISCSI_SUCCESS;
}
-static mgmt_ipc_err_e
+static int
iscsi_discovery_del_node(int argc, char **argv)
{
- return MGMT_IPC_OK;
+ return ISCSI_SUCCESS;
}
-static mgmt_ipc_err_e
+static int
iscsi_discovery_add_portal(int argc, char **argv)
{
- return MGMT_IPC_OK;
+ return ISCSI_SUCCESS;
}
-static mgmt_ipc_err_e
+static int
iscsi_discovery_del_portal(int argc, char **argv)
{
- return MGMT_IPC_OK;
+ return ISCSI_SUCCESS;
}
-static mgmt_ipc_err_e
+static int
mgmt_ipc_notify_add_node(queue_task_t *qtask)
{
return mgmt_ipc_notify_common(qtask, iscsi_discovery_add_node);
}
-static mgmt_ipc_err_e
+static int
mgmt_ipc_notify_del_node(queue_task_t *qtask)
{
return mgmt_ipc_notify_common(qtask, iscsi_discovery_del_node);
}
-static mgmt_ipc_err_e
+static int
mgmt_ipc_notify_add_portal(queue_task_t *qtask)
{
return mgmt_ipc_notify_common(qtask, iscsi_discovery_add_portal);
}
-static mgmt_ipc_err_e
+static int
mgmt_ipc_notify_del_portal(queue_task_t *qtask)
{
return mgmt_ipc_notify_common(qtask, iscsi_discovery_del_portal);
@@ -433,7 +422,7 @@ mgmt_ipc_destroy_queue_task(queue_task_t
* is for.
*/
void
-mgmt_ipc_write_rsp(queue_task_t *qtask, mgmt_ipc_err_e err)
+mgmt_ipc_write_rsp(queue_task_t *qtask, int err)
{
if (!qtask)
return;
@@ -446,7 +435,8 @@ mgmt_ipc_write_rsp(queue_task_t *qtask,
}
qtask->rsp.err = err;
- write(qtask->mgmt_ipc_fd, &qtask->rsp, sizeof(qtask->rsp));
+ if (write(qtask->mgmt_ipc_fd, &qtask->rsp, sizeof(qtask->rsp)) < 0)
+ log_error("IPC qtask write failed: %s", strerror(errno));
close(qtask->mgmt_ipc_fd);
mgmt_ipc_destroy_queue_task(qtask);
}
@@ -510,7 +500,6 @@ static mgmt_ipc_fn_t * mgmt_ipc_function
[MGMT_IPC_CONFIG_IALIAS] = mgmt_ipc_cfg_initiatoralias,
[MGMT_IPC_CONFIG_FILE] = mgmt_ipc_cfg_filename,
[MGMT_IPC_IMMEDIATE_STOP] = mgmt_ipc_immediate_stop,
-[MGMT_IPC_SET_HOST_PARAM] = mgmt_ipc_host_set_param,
[MGMT_IPC_NOTIFY_ADD_NODE] = mgmt_ipc_notify_add_node,
[MGMT_IPC_NOTIFY_DEL_NODE] = mgmt_ipc_notify_del_node,
[MGMT_IPC_NOTIFY_ADD_PORTAL] = mgmt_ipc_notify_add_portal,
@@ -538,7 +527,7 @@ void mgmt_ipc_handle(int accept_fd)
qtask->mgmt_ipc_fd = fd;
if (!mgmt_peeruser(fd, user) || strncmp(user, "root", PEERUSER_MAX)) {
- err = MGMT_IPC_ERR_ACCESS;
+ err = ISCSI_ERR_ACCESS;
goto err;
}
@@ -556,12 +545,12 @@ void mgmt_ipc_handle(int accept_fd)
/* If the handler returns OK, this means it
* already sent the reply. */
err = handler(qtask);
- if (err == MGMT_IPC_OK)
+ if (err == ISCSI_SUCCESS)
return;
} else {
log_error("unknown request: %s(%d) %u",
__FUNCTION__, __LINE__, command);
- err = MGMT_IPC_ERR_INVALID_REQ;
+ err = ISCSI_ERR_INVALID_MGMT_REQ;
}
err:
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/mgmt_ipc.h open-iscsi-2.0-872-rc4-bnx2i.work/usr/mgmt_ipc.h
--- open-iscsi-2.0-872-rc4-bnx2i/usr/mgmt_ipc.h 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/mgmt_ipc.h 2012-03-05 23:02:46.000000000 -0600
@@ -26,30 +26,6 @@
#define ISCSIADM_NAMESPACE "ISCSIADM_ABSTRACT_NAMESPACE"
#define PEERUSER_MAX 64
-typedef enum mgmt_ipc_err {
- MGMT_IPC_OK = 0,
- MGMT_IPC_ERR = 1,
- MGMT_IPC_ERR_NOT_FOUND = 2,
- MGMT_IPC_ERR_NOMEM = 3,
- MGMT_IPC_ERR_TRANS_FAILURE = 4,
- MGMT_IPC_ERR_LOGIN_FAILURE = 5,
- MGMT_IPC_ERR_IDBM_FAILURE = 6,
- MGMT_IPC_ERR_INVAL = 7,
- MGMT_IPC_ERR_TRANS_TIMEOUT = 8,
- MGMT_IPC_ERR_INTERNAL = 9,
- MGMT_IPC_ERR_LOGOUT_FAILURE = 10,
- MGMT_IPC_ERR_PDU_TIMEOUT = 11,
- MGMT_IPC_ERR_TRANS_NOT_FOUND = 12,
- MGMT_IPC_ERR_ACCESS = 13,
- MGMT_IPC_ERR_TRANS_CAPS = 14,
- MGMT_IPC_ERR_EXISTS = 15,
- MGMT_IPC_ERR_INVALID_REQ = 16,
- MGMT_IPC_ERR_ISNS_UNAVAILABLE = 17,
- MGMT_IPC_ERR_ISCSID_COMM_ERR = 18,
- MGMT_IPC_ERR_FATAL_LOGIN_FAILURE = 19,
- MGMT_IPC_ERR_ISCSID_NOTCONN = 20,
-} mgmt_ipc_err_e;
-
typedef enum iscsiadm_cmd {
MGMT_IPC_UNKNOWN = 0,
MGMT_IPC_SESSION_LOGIN = 1,
@@ -66,11 +42,10 @@ typedef enum iscsiadm_cmd {
MGMT_IPC_SESSION_INFO = 13,
MGMT_IPC_ISNS_DEV_ATTR_QUERY = 14,
MGMT_IPC_SEND_TARGETS = 15,
- MGMT_IPC_SET_HOST_PARAM = 16,
- MGMT_IPC_NOTIFY_ADD_NODE = 17,
- MGMT_IPC_NOTIFY_DEL_NODE = 18,
- MGMT_IPC_NOTIFY_ADD_PORTAL = 19,
- MGMT_IPC_NOTIFY_DEL_PORTAL = 20,
+ MGMT_IPC_NOTIFY_ADD_NODE = 16,
+ MGMT_IPC_NOTIFY_DEL_NODE = 17,
+ MGMT_IPC_NOTIFY_ADD_PORTAL = 18,
+ MGMT_IPC_NOTIFY_DEL_PORTAL = 19,
__MGMT_IPC_MAX_COMMAND
} iscsiadm_cmd_e;
@@ -108,7 +83,7 @@ typedef struct iscsiadm_req {
/* IPC Response */
typedef struct iscsiadm_rsp {
iscsiadm_cmd_e command;
- mgmt_ipc_err_e err;
+ int err; /* ISCSI_ERR value */
union {
#define MGMT_IPC_GETSTATS_BUF_MAX (sizeof(struct iscsi_uevent) + \
@@ -132,10 +107,10 @@ typedef struct iscsiadm_rsp {
} iscsiadm_rsp_t;
struct queue_task;
-typedef mgmt_ipc_err_e mgmt_ipc_fn_t(struct queue_task *);
+typedef int mgmt_ipc_fn_t(struct queue_task *);
struct queue_task;
-void mgmt_ipc_write_rsp(struct queue_task *qtask, mgmt_ipc_err_e err);
+void mgmt_ipc_write_rsp(struct queue_task *qtask, int err);
int mgmt_ipc_listen(void);
void mgmt_ipc_close(int fd);
void mgmt_ipc_handle(int accept_fd);
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/netlink.c open-iscsi-2.0-872-rc4-bnx2i.work/usr/netlink.c
--- open-iscsi-2.0-872-rc4-bnx2i/usr/netlink.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/netlink.c 2012-03-05 23:06:18.000000000 -0600
@@ -33,12 +33,12 @@
#include "types.h"
#include "iscsi_if.h"
-#include "iscsid.h"
#include "log.h"
#include "iscsi_ipc.h"
#include "initiator.h"
#include "iscsi_sysfs.h"
#include "transport.h"
+#include "iscsi_netlink.h"
static int ctrl_fd;
static struct sockaddr_nl src_addr, dest_addr;
@@ -50,23 +50,38 @@ static void *nlm_sendbuf;
static void *nlm_recvbuf;
static void *pdu_sendbuf;
static void *setparam_buf;
+static struct iscsi_ipc_ev_clbk *ipc_ev_clbk;
static int ctldev_handle(void);
-#define NLM_BUF_DEFAULT_MAX \
- (NLMSG_SPACE(ISCSI_DEF_MAX_RECV_SEG_LEN + \
- sizeof(struct iscsi_hdr)))
+#define NLM_BUF_DEFAULT_MAX (NLMSG_SPACE(ISCSI_DEF_MAX_RECV_SEG_LEN + \
+ sizeof(struct iscsi_uevent) + \
+ sizeof(struct iscsi_hdr)))
-#define PDU_SENDBUF_DEFAULT_MAX \
- (ISCSI_DEF_MAX_RECV_SEG_LEN + sizeof(struct iscsi_hdr))
+#define PDU_SENDBUF_DEFAULT_MAX (ISCSI_DEF_MAX_RECV_SEG_LEN + \
+ sizeof(struct iscsi_uevent) + \
+ sizeof(struct iscsi_hdr))
-#define NLM_SETPARAM_DEFAULT_MAX \
- (NI_MAXHOST + 1 + sizeof(struct iscsi_uevent))
+#define NLM_SETPARAM_DEFAULT_MAX (NI_MAXHOST + 1 + sizeof(struct iscsi_uevent))
+
+struct nlattr *iscsi_nla_alloc(uint16_t type, uint16_t len)
+{
+ struct nlattr *attr;
+
+ attr = calloc(1, ISCSI_NLA_TOTAL_LEN(len));
+ if (!attr)
+ return NULL;
+
+ attr->nla_len = ISCSI_NLA_LEN(len);
+ attr->nla_type = type;
+ return attr;
+}
static int
kread(char *data, int count)
{
- log_debug(7, "in %s", __FUNCTION__);
+ log_debug(7, "in %s %u %u %p %p", __FUNCTION__, recvlen, count,
+ data, recvbuf);
memcpy(data, recvbuf + recvlen, count);
recvlen += count;
@@ -107,6 +122,12 @@ nlpayload_read(int ctrl_fd, char *data,
iov.iov_base = nlm_recvbuf;
iov.iov_len = NLMSG_SPACE(count);
+
+ if (iov.iov_len > NLM_BUF_DEFAULT_MAX) {
+ log_error("Cannot read %lu bytes. nlm_recvbuf too small.",
+ iov.iov_len);
+ return -1;
+ }
memset(iov.iov_base, 0, iov.iov_len);
memset(&msg, 0, sizeof(msg));
@@ -142,7 +163,8 @@ nlpayload_read(int ctrl_fd, char *data,
*/
rc = recvmsg(ctrl_fd, &msg, flags);
- memcpy(data, NLMSG_DATA(iov.iov_base), count);
+ if (data)
+ memcpy(data, NLMSG_DATA(iov.iov_base), count);
return rc;
}
@@ -153,7 +175,6 @@ kwritev(enum iscsi_uevent_e type, struct
int i, rc;
struct nlmsghdr *nlh;
struct msghdr msg;
- struct iovec iov;
int datalen = 0;
log_debug(7, "in %s", __FUNCTION__);
@@ -172,27 +193,25 @@ kwritev(enum iscsi_uevent_e type, struct
}
nlh = nlm_sendbuf;
- memset(nlh, 0, NLMSG_SPACE(datalen));
+ memset(nlh, 0, NLMSG_SPACE(0));
+
+ datalen = 0;
+ for (i = 1; i < count; i++)
+ datalen += iovp[i].iov_len;
- nlh->nlmsg_len = NLMSG_SPACE(datalen);
+ nlh->nlmsg_len = datalen + sizeof(*nlh);
nlh->nlmsg_pid = getpid();
nlh->nlmsg_flags = 0;
nlh->nlmsg_type = type;
- datalen = 0;
- for (i = 0; i < count; i++) {
- memcpy(NLMSG_DATA(nlh) + datalen, iovp[i].iov_base,
- iovp[i].iov_len);
- datalen += iovp[i].iov_len;
- }
- iov.iov_base = (void*)nlh;
- iov.iov_len = nlh->nlmsg_len;
+ iovp[0].iov_base = (void *)nlh;
+ iovp[0].iov_len = sizeof(*nlh);
memset(&msg, 0, sizeof(msg));
msg.msg_name= (void*)&dest_addr;
msg.msg_namelen = sizeof(dest_addr);
- msg.msg_iov = &iov;
- msg.msg_iovlen = 1;
+ msg.msg_iov = iovp;
+ msg.msg_iovlen = count;
do {
/*
@@ -253,19 +272,15 @@ kwritev(enum iscsi_uevent_e type, struct
* cleanup. (Dima)
*/
static int
-__kipc_call(void *iov_base, int iov_len)
+__kipc_call(struct iovec *iovp, int count)
{
int rc, iferr;
- struct iovec iov;
- struct iscsi_uevent *ev = iov_base;
+ struct iscsi_uevent *ev = iovp[1].iov_base;
enum iscsi_uevent_e type = ev->type;
log_debug(7, "in %s", __FUNCTION__);
- iov.iov_base = iov_base;
- iov.iov_len = iov_len;
-
- rc = kwritev(type, &iov, 1);
+ rc = kwritev(type, iovp, count);
do {
if ((rc = nlpayload_read(ctrl_fd, (void*)ev,
@@ -325,6 +340,7 @@ ksendtargets(uint64_t transport_handle,
{
int rc, addrlen;
struct iscsi_uevent *ev;
+ struct iovec iov[2];
log_debug(7, "in %s", __FUNCTION__);
@@ -346,7 +362,9 @@ ksendtargets(uint64_t transport_handle,
}
memcpy(setparam_buf + sizeof(*ev), addr, addrlen);
- rc = __kipc_call(ev, sizeof(*ev) + addrlen);
+ iov[1].iov_base = ev;
+ iov[1].iov_len = sizeof(*ev) + addrlen;
+ rc = __kipc_call(iov, 2);
if (rc < 0) {
log_error("sendtargets failed rc%d\n", rc);
return rc;
@@ -361,6 +379,7 @@ kcreate_session(uint64_t transport_handl
{
int rc;
struct iscsi_uevent ev;
+ struct iovec iov[2];
log_debug(7, "in %s", __FUNCTION__);
@@ -381,9 +400,11 @@ kcreate_session(uint64_t transport_handl
ev.u.c_bound_session.ep_handle = ep_handle;
}
- if ((rc = __kipc_call(&ev, sizeof(ev))) < 0) {
+ iov[1].iov_base = &ev;
+ iov[1].iov_len = sizeof(ev);
+ rc = __kipc_call(iov, 2);
+ if (rc < 0)
return rc;
- }
*hostno = ev.r.c_session_ret.host_no;
*out_sid = ev.r.c_session_ret.sid;
@@ -396,6 +417,7 @@ kdestroy_session(uint64_t transport_hand
{
int rc;
struct iscsi_uevent ev;
+ struct iovec iov[2];
log_debug(7, "in %s", __FUNCTION__);
@@ -405,9 +427,11 @@ kdestroy_session(uint64_t transport_hand
ev.transport_handle = transport_handle;
ev.u.d_session.sid = sid;
- if ((rc = __kipc_call(&ev, sizeof(ev))) < 0) {
+ iov[1].iov_base = &ev;
+ iov[1].iov_len = sizeof(ev);
+ rc = __kipc_call(iov, 2);
+ if (rc < 0)
return rc;
- }
return 0;
}
@@ -417,6 +441,7 @@ kunbind_session(uint64_t transport_handl
{
int rc;
struct iscsi_uevent ev;
+ struct iovec iov[2];
log_debug(7, "in %s", __FUNCTION__);
@@ -426,9 +451,11 @@ kunbind_session(uint64_t transport_handl
ev.transport_handle = transport_handle;
ev.u.d_session.sid = sid;
- if ((rc = __kipc_call(&ev, sizeof(ev))) < 0) {
+ iov[1].iov_base = &ev;
+ iov[1].iov_len = sizeof(ev);
+ rc = __kipc_call(iov, 2);
+ if (rc < 0)
return rc;
- }
return 0;
}
@@ -439,6 +466,7 @@ kcreate_conn(uint64_t transport_handle,
{
int rc;
struct iscsi_uevent ev;
+ struct iovec iov[2];
log_debug(7, "in %s", __FUNCTION__);
@@ -449,7 +477,10 @@ kcreate_conn(uint64_t transport_handle,
ev.u.c_conn.cid = cid;
ev.u.c_conn.sid = sid;
- if ((rc = __kipc_call(&ev, sizeof(ev))) < 0) {
+ iov[1].iov_base = &ev;
+ iov[1].iov_len = sizeof(ev);
+ rc = __kipc_call(iov, 2);
+ if (rc < 0) {
log_debug(7, "returned %d", rc);
return rc;
}
@@ -466,6 +497,7 @@ kdestroy_conn(uint64_t transport_handle,
{
int rc;
struct iscsi_uevent ev;
+ struct iovec iov[2];
log_debug(7, "in %s", __FUNCTION__);
@@ -476,9 +508,11 @@ kdestroy_conn(uint64_t transport_handle,
ev.u.d_conn.sid = sid;
ev.u.d_conn.cid = cid;
- if ((rc = __kipc_call(&ev, sizeof(ev))) < 0) {
+ iov[1].iov_base = &ev;
+ iov[1].iov_len = sizeof(ev);
+ rc = __kipc_call(iov, 2);
+ if (rc < 0)
return rc;
- }
return 0;
}
@@ -489,6 +523,7 @@ kbind_conn(uint64_t transport_handle, ui
{
int rc;
struct iscsi_uevent ev;
+ struct iovec iov[2];
log_debug(7, "in %s", __FUNCTION__);
@@ -501,9 +536,11 @@ kbind_conn(uint64_t transport_handle, ui
ev.u.b_conn.transport_eph = transport_eph;
ev.u.b_conn.is_leading = is_leading;
- if ((rc = __kipc_call(&ev, sizeof(ev))) < 0) {
+ iov[1].iov_base = &ev;
+ iov[1].iov_len = sizeof(ev);
+ rc = __kipc_call(iov, 2);
+ if (rc < 0)
return rc;
- }
*retcode = ev.r.retcode;
@@ -515,6 +552,7 @@ ksend_pdu_begin(uint64_t transport_handl
int hdr_size, int data_size)
{
struct iscsi_uevent *ev;
+ int total_xmitlen = sizeof(*ev) + hdr_size + data_size;
log_debug(7, "in %s", __FUNCTION__);
@@ -523,8 +561,13 @@ ksend_pdu_begin(uint64_t transport_handl
exit(-EIO);
}
+ if (total_xmitlen > PDU_SENDBUF_DEFAULT_MAX) {
+ log_error("BUG: Cannot send %d bytes.", total_xmitlen);
+ exit(-EINVAL);
+ }
+
xmitbuf = pdu_sendbuf;
- memset(xmitbuf, 0, sizeof(*ev) + hdr_size + data_size);
+ memset(xmitbuf, 0, total_xmitlen);
xmitlen = sizeof(*ev);
ev = xmitbuf;
memset(ev, 0, sizeof(*ev));
@@ -545,7 +588,7 @@ ksend_pdu_end(uint64_t transport_handle,
{
int rc;
struct iscsi_uevent *ev;
- struct iovec iov;
+ struct iovec iov[2];
log_debug(7, "in %s", __FUNCTION__);
@@ -559,10 +602,11 @@ ksend_pdu_end(uint64_t transport_handle,
exit(-EIO);
}
- iov.iov_base = xmitbuf;
- iov.iov_len = xmitlen;
+ iov[1].iov_base = xmitbuf;
+ iov[1].iov_len = xmitlen;
- if ((rc = __kipc_call(xmitbuf, xmitlen)) < 0)
+ rc = __kipc_call(iov, 2);
+ if (rc < 0)
goto err;
if (ev->r.retcode) {
*retcode = ev->r.retcode;
@@ -592,6 +636,7 @@ kset_host_param(uint64_t transport_handl
struct iscsi_uevent *ev;
char *param_str;
int rc, len;
+ struct iovec iov[2];
log_debug(7, "in %s", __FUNCTION__);
@@ -618,9 +663,11 @@ kset_host_param(uint64_t transport_handl
}
ev->u.set_host_param.len = len = strlen(param_str) + 1;
- if ((rc = __kipc_call(ev, sizeof(*ev) + len)) < 0) {
+ iov[1].iov_base = ev;
+ iov[1].iov_len = sizeof(*ev) + len;
+ rc = __kipc_call(iov, 2);
+ if (rc < 0)
return rc;
- }
return 0;
}
@@ -632,6 +679,7 @@ kset_param(uint64_t transport_handle, ui
struct iscsi_uevent *ev;
char *param_str;
int rc, len;
+ struct iovec iov[2];
log_debug(7, "in %s", __FUNCTION__);
@@ -659,9 +707,11 @@ kset_param(uint64_t transport_handle, ui
}
ev->u.set_param.len = len = strlen(param_str) + 1;
- if ((rc = __kipc_call(ev, sizeof(*ev) + len)) < 0) {
+ iov[1].iov_base = ev;
+ iov[1].iov_len = sizeof(*ev) + len;
+ rc = __kipc_call(iov, 2);
+ if (rc < 0)
return rc;
- }
return 0;
}
@@ -671,6 +721,7 @@ kstop_conn(uint64_t transport_handle, ui
{
int rc;
struct iscsi_uevent ev;
+ struct iovec iov[2];
log_debug(7, "in %s", __FUNCTION__);
@@ -682,9 +733,11 @@ kstop_conn(uint64_t transport_handle, ui
ev.u.stop_conn.cid = cid;
ev.u.stop_conn.flag = flag;
- if ((rc = __kipc_call(&ev, sizeof(ev))) < 0) {
+ iov[1].iov_base = &ev;
+ iov[1].iov_len = sizeof(ev);
+ rc = __kipc_call(iov, 2);
+ if (rc < 0)
return rc;
- }
return 0;
}
@@ -695,6 +748,7 @@ kstart_conn(uint64_t transport_handle, u
{
int rc;
struct iscsi_uevent ev;
+ struct iovec iov[2];
log_debug(7, "in %s", __FUNCTION__);
@@ -705,9 +759,11 @@ kstart_conn(uint64_t transport_handle, u
ev.u.start_conn.sid = sid;
ev.u.start_conn.cid = cid;
- if ((rc = __kipc_call(&ev, sizeof(ev))) < 0) {
+ iov[1].iov_base = &ev;
+ iov[1].iov_len = sizeof(ev);
+ rc = __kipc_call(iov, 2);
+ if (rc < 0)
return rc;
- }
*retcode = ev.r.retcode;
return 0;
@@ -716,18 +772,34 @@ kstart_conn(uint64_t transport_handle, u
static int
krecv_pdu_begin(struct iscsi_conn *conn)
{
+ int rc;
+
log_debug(7, "in %s", __FUNCTION__);
if (recvbuf) {
log_error("recv's begin state machine bug?");
return -EIO;
}
+
+ if (!conn->recv_context) {
+ rc = ipc->ctldev_handle();
+ if (rc == -ENXIO)
+ /* event for some other conn */
+ return -EAGAIN;
+ else if (rc < 0)
+ /* fatal handling error or conn error */
+ return rc;
+ /*
+ * Session create/destroy event for another conn
+ */
+ if (!conn->recv_context)
+ return -EAGAIN;
+ }
+
recvbuf = conn->recv_context->data + sizeof(struct iscsi_uevent);
recvlen = 0;
- log_debug(3, "recv PDU began, pdu handle 0x%p",
- recvbuf);
-
+ log_debug(3, "recv PDU began, pdu handle %p", recvbuf);
return 0;
}
@@ -744,7 +816,7 @@ krecv_pdu_end(struct iscsi_conn *conn)
log_debug(3, "recv PDU finished for pdu handle 0x%p",
recvbuf);
- iscsi_conn_context_put(conn->recv_context);
+ ipc_ev_clbk->put_ev_context(conn->recv_context);
conn->recv_context = NULL;
recvbuf = NULL;
return 0;
@@ -756,6 +828,7 @@ ktransport_ep_connect(iscsi_conn_t *conn
int rc, addrlen;
struct iscsi_uevent *ev;
struct sockaddr *dst_addr = (struct sockaddr *)&conn->saddr;
+ struct iovec iov[2];
log_debug(7, "in %s", __FUNCTION__);
@@ -783,7 +856,10 @@ ktransport_ep_connect(iscsi_conn_t *conn
}
memcpy(setparam_buf + sizeof(*ev), dst_addr, addrlen);
- if ((rc = __kipc_call(ev, sizeof(*ev) + addrlen)) < 0)
+ iov[1].iov_base = ev;
+ iov[1].iov_len = sizeof(*ev) + addrlen;
+ rc = __kipc_call(iov, 2);
+ if (rc < 0)
return rc;
if (!ev->r.ep_connect_ret.handle)
@@ -801,6 +877,7 @@ ktransport_ep_poll(iscsi_conn_t *conn, i
{
int rc;
struct iscsi_uevent ev;
+ struct iovec iov[2];
log_debug(7, "in %s", __FUNCTION__);
@@ -811,7 +888,10 @@ ktransport_ep_poll(iscsi_conn_t *conn, i
ev.u.ep_poll.ep_handle = conn->transport_ep_handle;
ev.u.ep_poll.timeout_ms = timeout_ms;
- if ((rc = __kipc_call(&ev, sizeof(ev))) < 0)
+ iov[1].iov_base = &ev;
+ iov[1].iov_len = sizeof(ev);
+ rc = __kipc_call(iov, 2);
+ if (rc < 0)
return rc;
return ev.r.retcode;
@@ -822,6 +902,7 @@ ktransport_ep_disconnect(iscsi_conn_t *c
{
int rc;
struct iscsi_uevent ev;
+ struct iovec iov[2];
log_debug(7, "in %s", __FUNCTION__);
@@ -834,7 +915,10 @@ ktransport_ep_disconnect(iscsi_conn_t *c
ev.transport_handle = conn->session->t->handle;
ev.u.ep_disconnect.ep_handle = conn->transport_ep_handle;
- if ((rc = __kipc_call(&ev, sizeof(ev))) < 0) {
+ iov[1].iov_base = &ev;
+ iov[1].iov_len = sizeof(ev);
+ rc = __kipc_call(iov, 2);
+ if (rc < 0) {
log_error("connnection %d:%d transport disconnect failed for "
"ep %" PRIu64 " with error %d.", conn->session->id,
conn->id, conn->transport_ep_handle, rc);
@@ -851,6 +935,7 @@ kget_stats(uint64_t transport_handle, ui
struct iscsi_uevent ev;
char nlm_ev[NLMSG_SPACE(sizeof(struct iscsi_uevent))];
struct nlmsghdr *nlh;
+ struct iovec iov[2];
log_debug(7, "in %s", __FUNCTION__);
@@ -861,9 +946,11 @@ kget_stats(uint64_t transport_handle, ui
ev.u.get_stats.sid = sid;
ev.u.get_stats.cid = cid;
- if ((rc = __kipc_call(&ev, sizeof(ev))) < 0) {
+ iov[1].iov_base = &ev;
+ iov[1].iov_len = sizeof(ev);
+ rc = __kipc_call(iov, 2);
+ if (rc < 0)
return rc;
- }
if ((rc = nl_read(ctrl_fd, nlm_ev,
NLMSG_SPACE(sizeof(struct iscsi_uevent)), MSG_PEEK)) < 0) {
@@ -889,12 +976,60 @@ kget_stats(uint64_t transport_handle, ui
return 0;
}
+static int
+kset_net_config(uint64_t transport_handle, uint32_t host_no,
+ struct iovec *iovs, uint32_t param_count)
+{
+ struct iscsi_uevent ev;
+ int rc, ev_len;
+ struct iovec *iov = iovs + 1;
+
+ log_debug(8, "in %s", __FUNCTION__);
+
+ ev_len = sizeof(ev);
+ ev.type = ISCSI_UEVENT_SET_IFACE_PARAMS;
+ ev.transport_handle = transport_handle;
+ ev.u.set_iface_params.host_no = host_no;
+ /* first two iovs for nlmsg hdr and ev */
+ ev.u.set_iface_params.count = param_count - 2;
+
+ iov->iov_base = &ev;
+ iov->iov_len = ev_len;
+ rc = __kipc_call(iovs, param_count);
+ if (rc < 0)
+ return rc;
+
+ return 0;
+}
+
+static int krecv_conn_state(struct iscsi_conn *conn, int *state)
+{
+ int rc;
+
+ rc = ipc->ctldev_handle();
+ if (rc == -ENXIO) {
+ /* event for some other conn */
+ rc = -EAGAIN;
+ goto exit;
+ } else if (rc < 0)
+ /* fatal handling error or conn error */
+ goto exit;
+
+ *state = *(enum iscsi_conn_state *)conn->recv_context->data;
+
+ ipc_ev_clbk->put_ev_context(conn->recv_context);
+ conn->recv_context = NULL;
+
+exit:
+ return rc;
+}
+
static void drop_data(struct nlmsghdr *nlh)
{
int ev_size;
ev_size = nlh->nlmsg_len - NLMSG_ALIGN(sizeof(struct nlmsghdr));
- nlpayload_read(ctrl_fd, setparam_buf, ev_size, 0);
+ nlpayload_read(ctrl_fd, NULL, ev_size, 0);
}
static int ctldev_handle(void)
@@ -905,8 +1040,8 @@ static int ctldev_handle(void)
iscsi_conn_t *conn = NULL;
char nlm_ev[NLMSG_SPACE(sizeof(struct iscsi_uevent))];
struct nlmsghdr *nlh;
- struct iscsi_conn_context *conn_context;
- uint32_t sid = 0, cid = 0;
+ struct iscsi_ev_context *ev_context;
+ uint32_t sid = 0, cid = 0, state = 0;
log_debug(7, "in %s", __FUNCTION__);
@@ -925,13 +1060,15 @@ static int ctldev_handle(void)
/* old kernels sent ISCSI_UEVENT_CREATE_SESSION on creation */
case ISCSI_UEVENT_CREATE_SESSION:
drop_data(nlh);
- iscsi_async_session_creation(ev->r.c_session_ret.host_no,
- ev->r.c_session_ret.sid);
+ if (ipc_ev_clbk->create_session)
+ ipc_ev_clbk->create_session(ev->r.c_session_ret.host_no,
+ ev->r.c_session_ret.sid);
return 0;
case ISCSI_KEVENT_DESTROY_SESSION:
drop_data(nlh);
- iscsi_async_session_destruction(ev->r.d_session.host_no,
- ev->r.d_session.sid);
+ if (ipc_ev_clbk->destroy_session)
+ ipc_ev_clbk->destroy_session(ev->r.d_session.host_no,
+ ev->r.d_session.sid);
return 0;
case ISCSI_KEVENT_RECV_PDU:
sid = ev->r.recv_req.sid;
@@ -941,22 +1078,59 @@ static int ctldev_handle(void)
sid = ev->r.connerror.sid;
cid = ev->r.connerror.cid;
break;
+ case ISCSI_KEVENT_CONN_LOGIN_STATE:
+ sid = ev->r.conn_login.sid;
+ cid = ev->r.conn_login.cid;
+ state = ev->r.conn_login.state;
+ break;
case ISCSI_KEVENT_UNBIND_SESSION:
sid = ev->r.unbind_session.sid;
/* session wide event so cid is 0 */
cid = 0;
break;
+ case ISCSI_KEVENT_HOST_EVENT:
+ switch (ev->r.host_event.code) {
+ case ISCSI_EVENT_LINKUP:
+ log_warning("Host%u: Link Up.\n",
+ ev->r.host_event.host_no);
+ break;
+ case ISCSI_EVENT_LINKDOWN:
+ log_warning("Host%u: Link Down.\n",
+ ev->r.host_event.host_no);
+ break;
+ default:
+ log_debug(7, "Host%u: Unknwon host event: %u.\n",
+ ev->r.host_event.host_no,
+ ev->r.host_event.code);
+ }
+
+ drop_data(nlh);
+ return 0;
default:
- log_error("Unknown kernel event %d. You may want to upgrade "
- "your iscsi tools.", ev->type);
+ if ((ev->type > ISCSI_UEVENT_MAX && ev->type < KEVENT_BASE) ||
+ (ev->type > ISCSI_KEVENT_MAX))
+ log_error("Unknown kernel event %d. You may want to "
+ " upgrade your iscsi tools.", ev->type);
+ else
+ /*
+ * If another app is using the interface we might
+ * see their
+ * stuff. Just drop it.
+ */
+ log_debug(7, "Got unknwon event %d. Dropping.",
+ ev->type);
drop_data(nlh);
- return -EINVAL;
+ return 0;
}
/* verify connection */
session = session_find_by_sid(sid);
if (!session) {
- log_error("Could not verify connection %d:%d. Dropping "
+ /*
+ * this can happen normally when other apps are using the
+ * nl interface.
+ */
+ log_debug(1, "Could not verify connection %d:%d. Dropping "
"event.\n", sid, cid);
drop_data(nlh);
return -ENXIO;
@@ -964,19 +1138,20 @@ static int ctldev_handle(void)
conn = &session->conn[0];
ev_size = nlh->nlmsg_len - NLMSG_ALIGN(sizeof(struct nlmsghdr));
- conn_context = iscsi_conn_context_get(conn, ev_size);
- if (!conn_context) {
+
+ ev_context = ipc_ev_clbk->get_ev_context(conn, ev_size);
+ if (!ev_context) {
/* retry later */
log_error("Can not allocate memory for receive context.");
return -ENOMEM;
}
log_debug(6, "message real length is %d bytes, recv_handle %p",
- nlh->nlmsg_len, conn_context->data);
+ nlh->nlmsg_len, ev_context->data);
- if ((rc = nlpayload_read(ctrl_fd, conn_context->data,
+ if ((rc = nlpayload_read(ctrl_fd, ev_context->data,
ev_size, 0)) < 0) {
- iscsi_conn_context_put(conn_context);
+ ipc_ev_clbk->put_ev_context(ev_context);
log_error("can not read from NL socket, error %d", rc);
/* retry later */
return rc;
@@ -988,26 +1163,34 @@ static int ctldev_handle(void)
*/
switch (ev->type) {
case ISCSI_KEVENT_RECV_PDU:
- iscsi_sched_conn_context(conn_context, conn, 0,
- EV_CONN_RECV_PDU);
+ rc = ipc_ev_clbk->sched_ev_context(ev_context, conn, 0,
+ EV_CONN_RECV_PDU);
break;
case ISCSI_KEVENT_CONN_ERROR:
- memcpy(conn_context->data, &ev->r.connerror.error,
+ memcpy(ev_context->data, &ev->r.connerror.error,
sizeof(ev->r.connerror.error));
- iscsi_sched_conn_context(conn_context, conn, 0,
- EV_CONN_ERROR);
+ rc = ipc_ev_clbk->sched_ev_context(ev_context, conn, 0,
+ EV_CONN_ERROR);
+ break;
+ case ISCSI_KEVENT_CONN_LOGIN_STATE:
+ memcpy(ev_context->data, &ev->r.conn_login.state,
+ sizeof(ev->r.conn_login.state));
+ rc = ipc_ev_clbk->sched_ev_context(ev_context, conn, 0,
+ EV_CONN_LOGIN);
break;
case ISCSI_KEVENT_UNBIND_SESSION:
- iscsi_sched_conn_context(conn_context, conn, 0,
- EV_CONN_STOP);
+ rc = ipc_ev_clbk->sched_ev_context(ev_context, conn, 0,
+ EV_CONN_STOP);
break;
default:
- iscsi_conn_context_put(conn_context);
+ ipc_ev_clbk->put_ev_context(ev_context);
log_error("unknown kernel event %d", ev->type);
return -EEXIST;
}
- return 0;
+ if (rc)
+ ipc_ev_clbk->put_ev_context(ev_context);
+ return rc;
}
static int
@@ -1114,5 +1297,12 @@ struct iscsi_ipc nl_ipc = {
.read = kread,
.recv_pdu_begin = krecv_pdu_begin,
.recv_pdu_end = krecv_pdu_end,
+ .set_net_config = kset_net_config,
+ .recv_conn_state = krecv_conn_state,
};
struct iscsi_ipc *ipc = &nl_ipc;
+
+void ipc_register_ev_callback(struct iscsi_ipc_ev_clbk *ev_clbk)
+{
+ ipc_ev_clbk = ev_clbk;
+}
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/session_info.c open-iscsi-2.0-872-rc4-bnx2i.work/usr/session_info.c
--- open-iscsi-2.0-872-rc4-bnx2i/usr/session_info.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/session_info.c 2012-03-05 23:02:46.000000000 -0600
@@ -13,6 +13,7 @@
#include "initiator.h"
#include "iface.h"
#include "iscsid_req.h"
+#include "iscsi_err.h"
int session_info_create_list(void *data, struct session_info *info)
{
@@ -25,7 +26,7 @@ int session_info_create_list(void *data,
new = calloc(1, sizeof(*new));
if (!new)
- return ENOMEM;
+ return ISCSI_ERR_NOMEM;
memcpy(new, info, sizeof(*new));
INIT_LIST_HEAD(&new->list);
@@ -113,7 +114,7 @@ static int print_iscsi_state(int sid, ch
* anything here since it does not know about it.
*/
if (!err && rsp.u.session_state.conn_state >= 0 &&
- rsp.u.session_state.conn_state <= STATE_CLEANUP_WAIT)
+ rsp.u.session_state.conn_state <= ISCSI_CONN_STATE_CLEANUP_WAIT)
state = conn_state[rsp.u.session_state.conn_state];
printf("%s\t\tiSCSI Connection State: %s\n", prefix,
state ? state : "Unknown");
@@ -223,7 +224,7 @@ static int print_scsi_state(int sid, cha
}
void session_info_print_tree(struct list_head *list, char *prefix,
- unsigned int flags)
+ unsigned int flags, int do_show)
{
struct session_info *curr, *prev = NULL;
@@ -277,6 +278,70 @@ void session_info_print_tree(struct list
printf("%s\t\tSID: %d\n", prefix, curr->sid);
print_iscsi_state(curr->sid, prefix);
}
+ if (flags & SESSION_INFO_ISCSI_TIM) {
+ printf("%s\t\t*********\n", prefix);
+ printf("%s\t\tTimeouts:\n", prefix);
+ printf("%s\t\t*********\n", prefix);
+
+ printf("%s\t\tRecovery Timeout: %d\n", prefix,
+ ((curr->tmo).recovery_tmo));
+
+ if ((curr->tmo).tgt_reset_tmo >= 0)
+ printf("%s\t\tTarget Reset Timeout: %d\n",
+ prefix,
+ ((curr->tmo).tgt_reset_tmo));
+ else
+ printf("%s\t\tTarget Reset Timeout: %s\n",
+ prefix, UNKNOWN_VALUE);
+
+ if ((curr->tmo).lu_reset_tmo >= 0)
+ printf("%s\t\tLUN Reset Timeout: %d\n", prefix,
+ ((curr->tmo).lu_reset_tmo));
+ else
+ printf("%s\t\tLUN Reset Timeout: %s\n", prefix,
+ UNKNOWN_VALUE);
+
+ if ((curr->tmo).lu_reset_tmo >= 0)
+ printf("%s\t\tAbort Timeout: %d\n", prefix,
+ ((curr->tmo).abort_tmo));
+ else
+ printf("%s\t\tAbort Timeout: %s\n", prefix,
+ UNKNOWN_VALUE);
+
+ }
+ if (flags & SESSION_INFO_ISCSI_AUTH) {
+ printf("%s\t\t*****\n", prefix);
+ printf("%s\t\tCHAP:\n", prefix);
+ printf("%s\t\t*****\n", prefix);
+ if (!do_show) {
+ strcpy(curr->chap.password, "********");
+ strcpy(curr->chap.password_in, "********");
+ }
+ if (strlen((curr->chap).username))
+ printf("%s\t\tusername: %s\n", prefix,
+ (curr->chap).username);
+ else
+ printf("%s\t\tusername: %s\n", prefix,
+ UNKNOWN_VALUE);
+ if (strlen((curr->chap).password))
+ printf("%s\t\tpassword: %s\n", prefix,
+ (curr->chap).password);
+ else
+ printf("%s\t\tpassword: %s\n", prefix,
+ UNKNOWN_VALUE);
+ if (strlen((curr->chap).username_in))
+ printf("%s\t\tusername_in: %s\n", prefix,
+ (curr->chap).username_in);
+ else
+ printf("%s\t\tusername_in: %s\n", prefix,
+ UNKNOWN_VALUE);
+ if (strlen((curr->chap).password_in))
+ printf("%s\t\tpassword_in: %s\n", prefix,
+ (curr->chap).password_in);
+ else
+ printf("%s\t\tpassword_in: %s\n", prefix,
+ UNKNOWN_VALUE);
+ }
if (flags & SESSION_INFO_ISCSI_PARAMS)
print_iscsi_params(curr->sid, prefix);
@@ -288,7 +353,7 @@ void session_info_print_tree(struct list
}
}
-int session_info_print(int info_level, struct session_info *info)
+int session_info_print(int info_level, struct session_info *info, int do_show)
{
struct list_head list;
int num_found = 0, err = 0;
@@ -316,17 +381,18 @@ int session_info_print(int info_level, s
flags |= (SESSION_INFO_SCSI_DEVS | SESSION_INFO_HOST_DEVS);
/* fall through */
case 2:
- flags |= SESSION_INFO_ISCSI_PARAMS;
+ flags |= (SESSION_INFO_ISCSI_PARAMS | SESSION_INFO_ISCSI_TIM
+ | SESSION_INFO_ISCSI_AUTH);
/* fall through */
case 1:
INIT_LIST_HEAD(&list);
struct session_link_info link_info;
- flags |= (SESSION_INFO_ISCSI_STATE |SESSION_INFO_IFACE);
+ flags |= (SESSION_INFO_ISCSI_STATE | SESSION_INFO_IFACE);
if (info) {
INIT_LIST_HEAD(&info->list);
list_add_tail(&list, &info->list);
- session_info_print_tree(&list, "", flags);
+ session_info_print_tree(&list, "", flags, do_show);
num_found = 1;
break;
}
@@ -341,18 +407,20 @@ int session_info_print(int info_level, s
if (err || !num_found)
break;
- session_info_print_tree(&list, "", flags);
+ session_info_print_tree(&list, "", flags, do_show);
session_info_free_list(&list);
break;
default:
log_error("Invalid info level %d. Try 0 - 3.", info_level);
- return EINVAL;
+ return ISCSI_ERR_INVAL;
}
if (err) {
log_error("Can not get list of active sessions (%d)", err);
return err;
- } else if (!num_found)
+ } else if (!num_found) {
log_error("No active sessions.");
+ return ISCSI_ERR_NO_OBJS_FOUND;
+ }
return 0;
}
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/session_info.h open-iscsi-2.0-872-rc4-bnx2i.work/usr/session_info.h
--- open-iscsi-2.0-872-rc4-bnx2i/usr/session_info.h 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/session_info.h 2012-03-05 23:02:46.000000000 -0600
@@ -9,12 +9,29 @@
struct list;
+struct session_timeout {
+ int abort_tmo;
+ int lu_reset_tmo;
+ int recovery_tmo;
+ int tgt_reset_tmo;
+};
+
+struct session_CHAP {
+ char username[AUTH_STR_MAX_LEN];
+ char password[AUTH_STR_MAX_LEN];
+ char username_in[AUTH_STR_MAX_LEN];
+ char password_in[AUTH_STR_MAX_LEN];
+};
+
struct session_info {
struct list_head list;
/* local info */
struct iface_rec iface;
int sid;
+ struct session_timeout tmo;
+ struct session_CHAP chap;
+
/* remote info */
char targetname[TARGET_NAME_MAXLEN + 1];
int tpgt;
@@ -37,11 +54,14 @@ struct session_link_info {
#define SESSION_INFO_ISCSI_STATE 0x4
#define SESSION_INFO_SCSI_DEVS 0x8
#define SESSION_INFO_HOST_DEVS 0x10
+#define SESSION_INFO_ISCSI_TIM 0x20
+#define SESSION_INFO_ISCSI_AUTH 0x40
extern int session_info_create_list(void *data, struct session_info *info);
extern void session_info_free_list(struct list_head *list);
-extern int session_info_print(int info_level, struct session_info *match_info);
+extern int session_info_print(int info_level, struct session_info *match_info,
+ int do_show);
extern void session_info_print_tree(struct list_head *list, char *prefix,
- unsigned int flags);
+ unsigned int flags, int do_show);
#endif
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/session_mgmt.c open-iscsi-2.0-872-rc4-bnx2i.work/usr/session_mgmt.c
--- open-iscsi-2.0-872-rc4-bnx2i/usr/session_mgmt.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/session_mgmt.c 2012-03-05 23:02:46.000000000 -0600
@@ -3,7 +3,7 @@
*
* Copyright (C) 2010 Mike Christie
* Copyright (C) 2010 Red Hat, Inc. All rights reserved.
-
+ * Copyright (C) 2011 Dell Inc.
* maintained by open-iscsi@googlegroups.com
*
* This program is free software; you can redistribute it and/or modify
@@ -32,6 +32,7 @@
#include "iscsi_sysfs.h"
#include "log.h"
#include "iscsid_req.h"
+#include "iscsi_err.h"
static void log_login_msg(struct node_rec *rec, int rc)
{
@@ -40,7 +41,7 @@ static void log_login_msg(struct node_re
"portal: %s,%d].", rec->iface.name,
rec->name, rec->conn[0].address,
rec->conn[0].port);
- iscsid_handle_error(rc);
+ iscsi_err_print_msg(rc);
} else
log_info("Login to [iface: %s, target: %s, portal: "
"%s,%d] successful.", rec->iface.name,
@@ -82,6 +83,8 @@ static int iscsid_login_reqs_wait(struct
rec = curr->data;
err = iscsid_req_wait(MGMT_IPC_SESSION_LOGIN, curr->fd);
+ if (err && !ret)
+ ret = err;
log_login_msg(rec, err);
list_del(&curr->list);
free(curr);
@@ -90,19 +93,27 @@ static int iscsid_login_reqs_wait(struct
}
/**
- * iscsi_login_portal - request iscsid to login to portal
- * @data: Unused. Only needed so this can be used in iscsi_login_portals
+ * __iscsi_login_portal - request iscsid to login to portal
+ * @data: If set, copies the session.multiple value to the portal record
+ * so it is propagated to iscsid.
* @list: If async, list to add session to
* @rec: portal rec to log into
*/
-int iscsi_login_portal(void *data, struct list_head *list, struct node_rec *rec)
+static int
+__iscsi_login_portal(void *data, struct list_head *list, struct node_rec *rec)
{
struct iscsid_async_req *async_req = NULL;
int rc = 0, fd;
- log_info("Logging in to [iface: %s, target: %s, portal: %s,%d]",
+ if (data && !rec->session.multiple) {
+ struct node_rec *pattern_rec = data;
+ rec->session.multiple = pattern_rec->session.multiple;
+ }
+
+ log_info("Logging in to [iface: %s, target: %s, portal: %s,%d]%s",
rec->iface.name, rec->name, rec->conn[0].address,
- rec->conn[0].port);
+ rec->conn[0].port,
+ (rec->session.multiple ? " (multiple)" : ""));
if (list) {
async_req = calloc(1, sizeof(*async_req));
@@ -123,11 +134,7 @@ int iscsi_login_portal(void *data, struc
log_login_msg(rec, rc);
if (async_req)
free(async_req);
- /* we raced with another app or instance of iscsiadm */
- if (rc == MGMT_IPC_ERR_EXISTS)
- return 0;
-
- return ENOTCONN;
+ return rc;
}
if (async_req) {
@@ -141,6 +148,63 @@ int iscsi_login_portal(void *data, struc
}
/**
+ * iscsi_login_portal - request iscsid to login to portal multiple
+ * times, based on the session.nr_sessions in the portal record.
+ * @data: If set, session.multiple will cause an additional session to
+ * be created regardless of the value of session.nr_sessions
+ * @list: If async, list to add session to
+ * @rec: portal rec to log into
+ */
+int iscsi_login_portal(void *data, struct list_head *list, struct node_rec *rec)
+{
+ struct node_rec *pattern_rec = data;
+ int rc = 0, session_count = 0, i;
+
+ /*
+ * If pattern_rec->session.multiple is set, just add a single new
+ * session by passing things along to __iscsi_login_portal
+ */
+ if (pattern_rec && pattern_rec->session.multiple)
+ return __iscsi_login_portal(data, list, rec);
+
+ /*
+ * Count the current number of sessions, and only create those
+ * that are missing.
+ */
+ rc = iscsi_sysfs_for_each_session(rec, &session_count,
+ iscsi_match_session_count);
+ if (rc) {
+ log_error("Could not count current number of sessions");
+ goto done;
+ }
+ if (session_count >= rec->session.nr_sessions) {
+ log_debug(1, "%s: %d session%s requested, but %d "
+ "already present.",
+ rec->iface.name, rec->session.nr_sessions,
+ rec->session.nr_sessions == 1 ? "" : "s",
+ session_count);
+ rc = 0;
+ goto done;
+ }
+
+ /*
+ * Ensure the record's 'multiple' flag is set so __iscsi_login_portal
+ * will allow multiple logins.
+ */
+ rec->session.multiple = 1;
+ for (i = session_count; i < rec->session.nr_sessions; ++i) {
+ log_debug(1, "%s: Creating session %d/%d", rec->iface.name,
+ i + 1, rec->session.nr_sessions);
+ int err = __iscsi_login_portal(pattern_rec, list, rec);
+ if (err && !rc)
+ rc = err;
+ }
+
+done:
+ return rc;
+}
+
+/**
* iscsi_login_portal_nowait - request iscsid to login to portal
* @rec: portal rec to log into
*
@@ -152,7 +216,6 @@ int iscsi_login_portal_nowait(struct nod
int err;
INIT_LIST_HEAD(&list);
-
err = iscsi_login_portal(NULL, &list, rec);
if (err > 0)
return err;
@@ -161,20 +224,22 @@ int iscsi_login_portal_nowait(struct nod
}
/**
- * iscsi_login_portals - login into portals on @rec_list,
+ * __iscsi_login_portals - login into portals on @rec_list,
* @data: data to pass to login_fn
* @nr_found: returned with number of portals logged into
* @wait: bool indicating if the fn should wait for the result
* @rec_list: list of portals to log into
+ * @clear_list: If set, delete and free rec_list after iterating through.
* @login_fn: list iter function
*
* This will loop over the list of portals and login. It
* will attempt to login asynchronously, and then wait for
* them to complete if wait is set.
*/
-int iscsi_login_portals(void *data, int *nr_found, int wait,
- struct list_head *rec_list,
- int (* login_fn)(void *, struct list_head *,
+static
+int __iscsi_login_portals(void *data, int *nr_found, int wait,
+ struct list_head *rec_list, int clear_list,
+ int (*login_fn)(void *, struct list_head *,
struct node_rec *))
{
struct node_rec *curr_rec, *tmp;
@@ -191,7 +256,6 @@ int iscsi_login_portals(void *data, int
if (!err)
(*nr_found)++;
}
-
if (wait) {
err = iscsid_login_reqs_wait(&login_list);
if (err && !ret)
@@ -199,13 +263,50 @@ int iscsi_login_portals(void *data, int
} else
iscsid_reqs_close(&login_list);
- list_for_each_entry_safe(curr_rec, tmp, rec_list, list) {
- list_del(&curr_rec->list);
- free(curr_rec);
+ if (clear_list) {
+ list_for_each_entry_safe(curr_rec, tmp, rec_list, list) {
+ list_del(&curr_rec->list);
+ free(curr_rec);
+ }
}
return ret;
}
+/**
+ * iscsi_login_portals - login into portals on @rec_list,
+ * @data: data to pass to login_fn
+ * @nr_found: returned with number of portals logged into
+ * @wait: bool indicating if the fn should wait for the result
+ * @rec_list: list of portals to log into. This list is deleted after
+ * iterating through it.
+ * @login_fn: list iter function
+ *
+ * This will loop over the list of portals and login. It
+ * will attempt to login asynchronously, and then wait for
+ * them to complete if wait is set.
+ */
+int iscsi_login_portals(void *data, int *nr_found, int wait,
+ struct list_head *rec_list,
+ int (*login_fn)(void *, struct list_head *,
+ struct node_rec *))
+{
+ return __iscsi_login_portals(data, nr_found, wait, rec_list,
+ 1, login_fn);
+}
+
+/**
+ * iscsi_login_portals_safe - login into portals on @rec_list, but do not
+ * clear out rec_list.
+ */
+int iscsi_login_portals_safe(void *data, int *nr_found, int wait,
+ struct list_head *rec_list,
+ int (*login_fn)(void *, struct list_head *,
+ struct node_rec *))
+{
+ return __iscsi_login_portals(data, nr_found, wait, rec_list,
+ 0, login_fn);
+}
+
static void log_logout_msg(struct session_info *info, int rc)
{
if (rc) {
@@ -213,7 +314,7 @@ static void log_logout_msg(struct sessio
"portal: %s,%d].", info->sid,
info->targetname,
info->persistent_address, info->port);
- iscsid_handle_error(rc);
+ iscsi_err_print_msg(rc);
} else
log_info("Logout of [sid: %d, target: %s, "
"portal: %s,%d] successful.",
@@ -277,11 +378,7 @@ int iscsi_logout_portal(struct session_i
log_logout_msg(info, rc);
if (async_req)
free(async_req);
-
- if (rc == MGMT_IPC_ERR_NOT_FOUND)
- return 0;
-
- return EIO;
+ return rc;
}
if (async_req) {
@@ -325,10 +422,17 @@ int iscsi_logout_portals(void *data, int
err = iscsi_sysfs_for_each_session(&link_info, nr_found,
session_info_create_list);
- if (err || !*nr_found)
+ if (err && !list_empty(&session_list))
+ log_error("Could not read in all sessions: %s",
+ iscsi_err_to_str(err));
+ else if (err && list_empty(&session_list)) {
+ log_error("Could not read session info.");
return err;
-
+ } else if (list_empty(&session_list))
+ return ISCSI_ERR_NO_OBJS_FOUND;
+ ret = err;
*nr_found = 0;
+
list_for_each_entry(curr_info, &session_list, list) {
err = logout_fn(data, &logout_list, curr_info);
if (err > 0 && !ret)
@@ -337,13 +441,22 @@ int iscsi_logout_portals(void *data, int
(*nr_found)++;
}
+ if (!*nr_found) {
+ ret = ISCSI_ERR_NO_OBJS_FOUND;
+ goto free_list;
+ }
+
if (wait) {
err = iscsid_logout_reqs_wait(&logout_list);
- if (err)
+ if (err && !ret)
ret = err;
} else
iscsid_reqs_close(&logout_list);
+ if (ret)
+ log_error("Could not logout of all requested sessions");
+
+free_list:
session_info_free_list(&session_list);
return ret;
}
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/session_mgmt.h open-iscsi-2.0-872-rc4-bnx2i.work/usr/session_mgmt.h
--- open-iscsi-2.0-872-rc4-bnx2i/usr/session_mgmt.h 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/session_mgmt.h 2012-03-05 23:02:46.000000000 -0600
@@ -10,7 +10,11 @@ extern int iscsi_login_portal(void *data
extern int iscsi_login_portal_nowait(struct node_rec *rec);
extern int iscsi_login_portals(void *data, int *nr_found, int wait,
struct list_head *rec_list,
- int (* login_fn)(void *, struct list_head *,
+ int (*login_fn)(void *, struct list_head *,
+ struct node_rec *));
+extern int iscsi_login_portals_safe(void *data, int *nr_found, int wait,
+ struct list_head *rec_list,
+ int (*login_fn)(void *, struct list_head *,
struct node_rec *));
extern int iscsi_logout_portal(struct session_info *info,
struct list_head *list);
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/strings.c open-iscsi-2.0-872-rc4-bnx2i.work/usr/strings.c
--- open-iscsi-2.0-872-rc4-bnx2i/usr/strings.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/strings.c 2012-03-05 23:03:42.000000000 -0600
@@ -97,11 +97,17 @@ int str_enlarge_data(struct str_buffer *
void str_remove_initial(struct str_buffer *s, int length)
{
- char *remaining = s->buffer + length;
- int amount = s->data_length - length;
+ char *remaining;
+ int amount;
if (s && length) {
- memmove(s->buffer, remaining, amount);
+ remaining = s->buffer + length;
+ amount = s->data_length - length;
+
+ if (amount < 0)
+ amount = 0;
+ if (amount)
+ memmove(s->buffer, remaining, amount);
s->data_length = amount;
s->buffer[amount] = '\0';
}
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/sysfs.c open-iscsi-2.0-872-rc4-bnx2i.work/usr/sysfs.c
--- open-iscsi-2.0-872-rc4-bnx2i/usr/sysfs.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/sysfs.c 2012-03-05 23:02:46.000000000 -0600
@@ -547,7 +547,7 @@ found:
}
-char *sysfs_get_value(char *id, char *subsys, char *param)
+char *sysfs_get_value(const char *id, char *subsys, char *param)
{
char devpath[PATH_SIZE];
char *sysfs_value;
@@ -590,7 +590,7 @@ int sysfs_get_uint(char *id, char *subsy
return 0;
}
-int sysfs_get_int(char *id, char *subsys, char *param, int *value)
+int sysfs_get_int(const char *id, char *subsys, char *param, int *value)
{
char *sysfs_value;
@@ -636,6 +636,34 @@ int sysfs_get_uint64(char *id, char *sub
return 0;
}
+int sysfs_get_uint8(char *id, char *subsys, char *param,
+ uint8_t *value)
+{
+ char *sysfs_value;
+
+ *value = -1;
+ sysfs_value = sysfs_get_value(id, subsys, param);
+ if (!sysfs_value)
+ return EIO;
+
+ *value = (uint8_t)atoi(sysfs_value);
+ return 0;
+}
+
+int sysfs_get_uint16(char *id, char *subsys, char *param,
+ uint16_t *value)
+{
+ char *sysfs_value;
+
+ *value = -1;
+ sysfs_value = sysfs_get_value(id, subsys, param);
+ if (!sysfs_value)
+ return EIO;
+
+ *value = (uint16_t)atoi(sysfs_value);
+ return 0;
+}
+
int sysfs_set_param(char *id, char *subsys, char *attr_name,
char *write_buf, ssize_t buf_size)
{
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/sysfs.h open-iscsi-2.0-872-rc4-bnx2i.work/usr/sysfs.h
--- open-iscsi-2.0-872-rc4-bnx2i/usr/sysfs.h 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/sysfs.h 2012-03-05 23:02:46.000000000 -0600
@@ -51,14 +51,18 @@ extern char *sysfs_attr_get_value(const
extern int sysfs_resolve_link(char *path, size_t size);
extern int sysfs_lookup_devpath_by_subsys_id(char *devpath, size_t len, const char *subsystem, const char *id);
-extern char *sysfs_get_value(char *id, char *subsys, char *param);
+extern char *sysfs_get_value(const char *id, char *subsys, char *param);
extern int sysfs_get_uint(char *id, char *subsys, char *param,
unsigned int *value);
-extern int sysfs_get_int(char *id, char *subsys, char *param, int *value);
+extern int sysfs_get_int(const char *id, char *subsys, char *param, int *value);
extern int sysfs_get_str(char *id, char *subsys, char *param, char *value,
int value_size);
extern int sysfs_get_uint64(char *id, char *subsys, char *param,
uint64_t *value);
+extern int sysfs_get_uint8(char *id, char *subsys, char *param,
+ uint8_t *value);
+extern int sysfs_get_uint16(char *id, char *subsys, char *param,
+ uint16_t *value);
extern int sysfs_set_param(char *id, char *subsys, char *attr_name,
char *write_buf, ssize_t buf_size);
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/usr/transport.c open-iscsi-2.0-872-rc4-bnx2i.work/usr/transport.c
--- open-iscsi-2.0-872-rc4-bnx2i/usr/transport.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/usr/transport.c 2012-03-05 23:06:13.000000000 -0600
@@ -25,8 +25,9 @@
#include "log.h"
#include "iscsi_util.h"
#include "iscsi_sysfs.h"
-#include "cxgb3i.h"
+#include "cxgbi.h"
#include "be2iscsi.h"
+#include "iser.h"
struct iscsi_transport_template iscsi_tcp = {
.name = "tcp",
@@ -41,6 +42,7 @@ struct iscsi_transport_template iscsi_is
.ep_connect = ktransport_ep_connect,
.ep_poll = ktransport_ep_poll,
.ep_disconnect = ktransport_ep_disconnect,
+ .create_conn = iser_create_conn,
};
struct iscsi_transport_template cxgb3i = {
@@ -49,7 +51,16 @@ struct iscsi_transport_template cxgb3i =
.ep_connect = ktransport_ep_connect,
.ep_poll = ktransport_ep_poll,
.ep_disconnect = ktransport_ep_disconnect,
- .create_conn = cxgb3i_create_conn,
+ .create_conn = cxgbi_create_conn,
+};
+
+struct iscsi_transport_template cxgb4i = {
+ .name = "cxgb4i",
+ .set_host_ip = 1,
+ .ep_connect = ktransport_ep_connect,
+ .ep_poll = ktransport_ep_poll,
+ .ep_disconnect = ktransport_ep_disconnect,
+ .create_conn = cxgbi_create_conn,
};
struct iscsi_transport_template bnx2i = {
@@ -70,12 +81,17 @@ struct iscsi_transport_template be2iscsi
struct iscsi_transport_template qla4xxx = {
.name = "qla4xxx",
+ .set_host_ip = 0,
+ .ep_connect = ktransport_ep_connect,
+ .ep_poll = ktransport_ep_poll,
+ .ep_disconnect = ktransport_ep_disconnect,
};
static struct iscsi_transport_template *iscsi_transport_templates[] = {
&iscsi_tcp,
&iscsi_iser,
&cxgb3i,
+ &cxgb4i,
&bnx2i,
&qla4xxx,
&be2iscsi,
@@ -97,6 +113,7 @@ int set_transport_template(struct iscsi_
}
}
- log_error("Could not find uspace transport for %s\n", t->name);
+ log_error("Could not find template for %s. An updated iscsiadm "
+ "is probably needed.\n", t->name);
return ENOSYS;
}
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/utils/fwparam_ibft/fw_entry.c open-iscsi-2.0-872-rc4-bnx2i.work/utils/fwparam_ibft/fw_entry.c
--- open-iscsi-2.0-872-rc4-bnx2i/utils/fwparam_ibft/fw_entry.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/utils/fwparam_ibft/fw_entry.c 2012-03-05 23:02:46.000000000 -0600
@@ -34,6 +34,7 @@
#include "fwparam.h"
#include "idbm_fields.h"
#include "iscsi_net_util.h"
+#include "iscsi_err.h"
/**
* fw_setup_nics - setup nics (ethXs) based on ibft net info
@@ -56,7 +57,7 @@ int fw_setup_nics(void)
ret = fw_get_targets(&targets);
if (ret || list_empty(&targets)) {
printf("Could not setup fw entries.\n");
- return ENODEV;
+ return ISCSI_ERR_NO_OBJS_FOUND;
}
/*
@@ -85,7 +86,10 @@ int fw_setup_nics(void)
}
fw_free_targets(&targets);
- return ret;
+ if (ret)
+ return ISCSI_ERR;
+ else
+ return 0;
}
/**
@@ -196,7 +200,7 @@ static void dump_network(struct boot_con
if (strlen(context->secondary_dns))
printf("%s = %s\n", IFACE_SEC_DNS, context->secondary_dns);
if (strlen(context->vlan))
- printf("%s = %s\n", IFACE_VLAN, context->vlan);
+ printf("%s = %s\n", IFACE_VLAN_ID, context->vlan);
if (strlen(context->iface))
printf("%s = %s\n", IFACE_NETNAME, context->iface);
}
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/utils/fwparam_ibft/fwparam_ppc.c open-iscsi-2.0-872-rc4-bnx2i.work/utils/fwparam_ibft/fwparam_ppc.c
--- open-iscsi-2.0-872-rc4-bnx2i/utils/fwparam_ibft/fwparam_ppc.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/utils/fwparam_ibft/fwparam_ppc.c 2012-03-05 23:02:46.000000000 -0600
@@ -30,6 +30,7 @@
#include "iscsi_obp.h"
#include "prom_parse.h"
#include "sysdeps.h"
+#include "iscsi_err.h"
void* yy_scan_string(const char *str);
int yyparse(struct ofw_dev *ofwdev);
@@ -355,7 +356,7 @@ static int loop_devs(const char *devtree
* Sort the nics into "natural" order. The proc fs
* device-tree has them in somewhat random, or reversed order.
*/
- qsort(niclist, nic_count, sizeof(char *), nic_cmp);
+ qsort(niclist, nic_count, sizeof(char *), (__compar_fn_t)nic_cmp);
snprintf(prefix, sizeof(prefix), "%s/%s", devtree, "aliases");
dev_count = 0;
@@ -449,7 +450,7 @@ int fwparam_ppc_boot_info(struct boot_co
devtree = find_devtree(filename);
if (!devtree)
- return EINVAL;
+ return ISCSI_ERR_INVAL;
/*
* Always search the device-tree to find the capable nic devices.
@@ -459,7 +460,7 @@ int fwparam_ppc_boot_info(struct boot_co
goto free_devtree;
if (find_file(filename) < 1)
- error = ENODEV;
+ error = ISCSI_ERR_NO_OBJS_FOUND;
else {
if (debug)
printf("%s:\n%s\n\n", filename, bootpath_val);
@@ -469,12 +470,12 @@ int fwparam_ppc_boot_info(struct boot_co
*/
if (!strstr(bootpath_val, "iscsi")) {
- error = EINVAL;
+ error = ISCSI_ERR_INVAL;
goto free_devtree;
}
ofwdevs[0] = calloc(1, sizeof(struct ofw_dev));
if (!ofwdevs[0]) {
- error = ENOMEM;
+ error = ISCSI_ERR_NOMEM;
goto free_devtree;
}
@@ -484,7 +485,7 @@ int fwparam_ppc_boot_info(struct boot_co
if (!error) {
context = calloc(1, sizeof(*context));
if (!context)
- error = ENOMEM;
+ error = ISCSI_ERR_NOMEM;
else
fill_context(context, ofwdevs[0]);
}
@@ -524,7 +525,7 @@ int fwparam_ppc_get_targets(struct list_
devtree = find_devtree(filename);
if (!devtree)
- return EINVAL;
+ return ISCSI_ERR_INVAL;
/*
* Always search the device-tree to find the capable nic devices.
@@ -534,7 +535,7 @@ int fwparam_ppc_get_targets(struct list_
goto free_devtree;
if (find_file(filename) < 1)
- error = ENODEV;
+ error = ISCSI_ERR_NO_OBJS_FOUND;
else {
if (debug)
printf("%s:\n%s\n\n", filename, bootpath_val);
@@ -544,12 +545,12 @@ int fwparam_ppc_get_targets(struct list_
*/
if (!strstr(bootpath_val, "iscsi")) {
- error = EINVAL;
+ error = ISCSI_ERR_INVAL;
goto free_devtree;
}
ofwdevs[0] = calloc(1, sizeof(struct ofw_dev));
if (!ofwdevs[0]) {
- error = ENOMEM;
+ error = ISCSI_ERR_NOMEM;
goto free_devtree;
}
@@ -559,7 +560,7 @@ int fwparam_ppc_get_targets(struct list_
if (!error) {
context = calloc(1, sizeof(*context));
if (!context)
- error = ENOMEM;
+ error = ISCSI_ERR_NOMEM;
else {
fill_context(context, ofwdevs[0]);
list_add_tail(&context->list, list);
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/utils/fwparam_ibft/fwparam_sysfs.c open-iscsi-2.0-872-rc4-bnx2i.work/utils/fwparam_ibft/fwparam_sysfs.c
--- open-iscsi-2.0-872-rc4-bnx2i/utils/fwparam_ibft/fwparam_sysfs.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/utils/fwparam_ibft/fwparam_sysfs.c 2012-03-05 23:02:46.000000000 -0600
@@ -36,6 +36,7 @@
#include "fwparam.h"
#include "sysdeps.h"
#include "iscsi_net_util.h"
+#include "iscsi_err.h"
#define ISCSI_BOOT_MAX 255
#define IBFT_SYSFS_ROOT "/sys/firmware/ibft/"
@@ -351,7 +352,7 @@ int fwparam_sysfs_boot_info(struct boot_
*/
dirfd = opendir(ISCSI_LLD_ROOT);
if (!dirfd)
- return errno;
+ return ISCSI_ERR_SYSFS_LOOKUP;
while ((dent = readdir(dirfd))) {
char lld_root[FILENAMESZ];
@@ -364,12 +365,12 @@ int fwparam_sysfs_boot_info(struct boot_
if (strncmp(dent->d_name, ISCSI_LLD_SUBSYS_PREFIX, 10))
continue;
- snprintf(lld_root, FILENAMESZ, ISCSI_LLD_ROOT"%s",
+ snprintf(lld_root, FILENAMESZ, ISCSI_LLD_ROOT"%s/",
dent->d_name);
if (!get_boot_info(context, lld_root, dent->d_name))
goto done;
}
- rc = ENODEV;
+ rc = ISCSI_ERR_NO_OBJS_FOUND;
done:
closedir(dirfd);
return rc;
@@ -401,12 +402,12 @@ static int get_targets(struct list_head
rc = fill_tgt_context(subsys, target_list[i], context);
if (rc)
- break;
+ goto cleanup;
rc = sysfs_get_int(target_list[i], subsys, "nic-assoc",
&nic_idx);
if (rc)
- break;
+ goto cleanup;
for (nic = 0; nic < nic_cnt; nic++) {
int id;
@@ -420,21 +421,31 @@ static int get_targets(struct list_head
if (nic == nic_cnt) {
printf("Invalid nic-assoc of %d. Max id %d.\n",
nic_idx, nic_cnt);
- break;
+ goto cleanup;
}
rc = fill_nic_context(subsys, nic_list[nic], context);
if (rc)
- break;
+ goto cleanup;
fill_initiator_context(subsys, context);
list_add_tail(&context->list, list);
+ continue;
+cleanup:
+ free(context);
+ context = NULL;
}
if (rc) {
if (context)
free(context);
- fw_free_targets(list);
+ /*
+ * If there are some valid targets return them. Most likely,
+ * the driver/ibft-implementation reported partial info
+ * for targets/initiators that were not used for boot.
+ */
+ if (!list_empty(list))
+ rc = 0;
}
deallocate_lists();
@@ -455,7 +466,7 @@ int fwparam_sysfs_get_targets(struct lis
*/
dirfd = opendir(ISCSI_LLD_ROOT);
if (!dirfd) {
- rc = errno;
+ rc = ISCSI_ERR_SYSFS_LOOKUP;
goto done;
}
@@ -463,21 +474,20 @@ int fwparam_sysfs_get_targets(struct lis
char lld_root[FILENAMESZ];
memset(&lld_root, 0 , FILENAMESZ);
-
if (!strcmp(dent->d_name, ".") || !strcmp(dent->d_name, ".."))
continue;
if (strncmp(dent->d_name, ISCSI_LLD_SUBSYS_PREFIX, 10))
continue;
- snprintf(lld_root, FILENAMESZ, ISCSI_LLD_ROOT"%s",
+ snprintf(lld_root, FILENAMESZ, ISCSI_LLD_ROOT"%s/",
dent->d_name);
get_targets(list, lld_root, dent->d_name);
}
closedir(dirfd);
done:
if (!rc && list_empty(list))
- rc = ENODEV;
+ rc = ISCSI_ERR_NO_OBJS_FOUND;
if (rc)
fw_free_targets(list);
return rc;
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/utils/fwparam_ibft/prom_lex.c open-iscsi-2.0-872-rc4-bnx2i.work/utils/fwparam_ibft/prom_lex.c
--- open-iscsi-2.0-872-rc4-bnx2i/utils/fwparam_ibft/prom_lex.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/utils/fwparam_ibft/prom_lex.c 2012-03-05 23:02:46.000000000 -0600
@@ -8,7 +8,7 @@
#define FLEX_SCANNER
#define YY_FLEX_MAJOR_VERSION 2
#define YY_FLEX_MINOR_VERSION 5
-#define YY_FLEX_SUBMINOR_VERSION 33
+#define YY_FLEX_SUBMINOR_VERSION 35
#if YY_FLEX_SUBMINOR_VERSION > 0
#define FLEX_BETA
#endif
@@ -30,7 +30,7 @@
/* C99 systems have <inttypes.h>. Non-C99 systems may or may not. */
-#if __STDC_VERSION__ >= 199901L
+#if defined (__STDC_VERSION__) && __STDC_VERSION__ >= 199901L
/* C99 says to define __STDC_LIMIT_MACROS before including stdint.h,
* if you want the limit (max/min) macros for int types.
@@ -53,7 +53,6 @@ typedef int flex_int32_t;
typedef unsigned char flex_uint8_t;
typedef unsigned short int flex_uint16_t;
typedef unsigned int flex_uint32_t;
-#endif /* ! C99 */
/* Limits of integral types. */
#ifndef INT8_MIN
@@ -84,6 +83,8 @@ typedef unsigned int flex_uint32_t;
#define UINT32_MAX (4294967295U)
#endif
+#endif /* ! C99 */
+
#endif /* ! FLEXINT_H */
#ifdef __cplusplus
@@ -93,11 +94,12 @@ typedef unsigned int flex_uint32_t;
#else /* ! __cplusplus */
-#if __STDC__
+/* C99 requires __STDC__ to be defined as 1. */
+#if defined (__STDC__)
#define YY_USE_CONST
-#endif /* __STDC__ */
+#endif /* defined (__STDC__) */
#endif /* ! __cplusplus */
#ifdef YY_USE_CONST
@@ -139,7 +141,15 @@ typedef unsigned int flex_uint32_t;
/* Size of default input buffer. */
#ifndef YY_BUF_SIZE
+#ifdef __ia64__
+/* On IA-64, the buffer size is 16k, not 8k.
+ * Moreover, YY_BUF_SIZE is 2*YY_READ_BUF_SIZE in the general case.
+ * Ditto for the __ia64__ case accordingly.
+ */
+#define YY_BUF_SIZE 32768
+#else
#define YY_BUF_SIZE 16384
+#endif /* __ia64__ */
#endif
/* The state buf must be large enough to hold one state per character in the main buffer.
@@ -177,14 +187,9 @@ extern FILE *yyin, *yyout;
#define unput(c) yyunput( c, (yytext_ptr) )
-/* The following is because we cannot portably get our hands on size_t
- * (without autoconf's help, which isn't available because we want
- * flex-generated scanners to compile on their own).
- */
-
#ifndef YY_TYPEDEF_YY_SIZE_T
#define YY_TYPEDEF_YY_SIZE_T
-typedef unsigned int yy_size_t;
+typedef size_t yy_size_t;
#endif
#ifndef YY_STRUCT_YY_BUFFER_STATE
@@ -920,7 +925,7 @@ int yy_flex_debug = 0;
#define YY_MORE_ADJ 0
#define YY_RESTORE_YY_MORE_OFFSET
#ifndef YYLMAX
-#define YYLMAX 2048
+#define YYLMAX 8192
#endif
char yytext[YYLMAX];
@@ -964,8 +969,9 @@ char *yytext_ptr;
void dbgprint(const char *item) { fprintf(stderr, "%s: \"%s\" len=%d ", item, yytext, yyleng);}
+#define YY_NO_INPUT 1
/* CHOSEN uses only boot related paths. */
-#line 969 "<stdout>"
+#line 975 "<stdout>"
#define INITIAL 0
@@ -983,6 +989,35 @@ void dbgprint(const char *item) { fprint
static int yy_init_globals (void );
+/* Accessor methods to globals.
+ These are made visible to non-reentrant scanners for convenience. */
+
+int yylex_destroy (void );
+
+int yyget_debug (void );
+
+void yyset_debug (int debug_flag );
+
+YY_EXTRA_TYPE yyget_extra (void );
+
+void yyset_extra (YY_EXTRA_TYPE user_defined );
+
+FILE *yyget_in (void );
+
+void yyset_in (FILE * in_str );
+
+FILE *yyget_out (void );
+
+void yyset_out (FILE * out_str );
+
+int yyget_leng (void );
+
+char *yyget_text (void );
+
+int yyget_lineno (void );
+
+void yyset_lineno (int line_number );
+
/* Macros after this point can all be overridden by user definitions in
* section 1.
*/
@@ -995,8 +1030,6 @@ extern int yywrap (void );
#endif
#endif
- static void yyunput (int c,char *buf_ptr );
-
#ifndef yytext_ptr
static void yy_flex_strncpy (char *,yyconst char *,int );
#endif
@@ -1017,7 +1050,12 @@ static int input (void );
/* Amount of stuff to slurp up with each read. */
#ifndef YY_READ_BUF_SIZE
+#ifdef __ia64__
+/* On IA-64, the buffer size is 16k, not 8k */
+#define YY_READ_BUF_SIZE 16384
+#else
#define YY_READ_BUF_SIZE 8192
+#endif /* __ia64__ */
#endif
/* Copy whatever the last rule matched to the standard output. */
@@ -1025,7 +1063,7 @@ static int input (void );
/* This used to be an fputs(), but since the string might contain NUL's,
* we now use fwrite().
*/
-#define ECHO (void) fwrite( yytext, yyleng, 1, yyout )
+#define ECHO do { if (fwrite( yytext, yyleng, 1, yyout )) {} } while (0)
#endif
/* Gets input and stuffs it into "buf". number of characters read, or YY_NULL,
@@ -1118,10 +1156,10 @@ YY_DECL
register char *yy_cp, *yy_bp;
register int yy_act;
-#line 63 "prom_lex.l"
+#line 65 "prom_lex.l"
-#line 1125 "<stdout>"
+#line 1163 "<stdout>"
if ( !(yy_init) )
{
@@ -1202,78 +1240,78 @@ do_action: /* This label is used only to
case 1:
YY_RULE_SETUP
-#line 65 "prom_lex.l"
+#line 67 "prom_lex.l"
{ upval(CHOSEN); }
YY_BREAK
case 2:
YY_RULE_SETUP
-#line 66 "prom_lex.l"
+#line 68 "prom_lex.l"
{ upval(VDEVICE); }
YY_BREAK
case 3:
YY_RULE_SETUP
-#line 67 "prom_lex.l"
+#line 69 "prom_lex.l"
{ upval(VDEVINST); }
YY_BREAK
case 4:
YY_RULE_SETUP
-#line 68 "prom_lex.l"
+#line 70 "prom_lex.l"
{ upval(VDEVDEV); }
YY_BREAK
case 5:
YY_RULE_SETUP
-#line 69 "prom_lex.l"
+#line 71 "prom_lex.l"
{ upval(VDEVRAW); }
YY_BREAK
case 6:
YY_RULE_SETUP
-#line 70 "prom_lex.l"
+#line 72 "prom_lex.l"
{ upval(OBPQUAL); }
YY_BREAK
case 7:
YY_RULE_SETUP
-#line 71 "prom_lex.l"
+#line 73 "prom_lex.l"
{ upval(BUSNAME); }
YY_BREAK
case 8:
YY_RULE_SETUP
-#line 72 "prom_lex.l"
+#line 74 "prom_lex.l"
{ upval(IPV4); }
YY_BREAK
case 9:
YY_RULE_SETUP
-#line 73 "prom_lex.l"
+#line 75 "prom_lex.l"
{ upval(IQN); }
YY_BREAK
case 10:
YY_RULE_SETUP
-#line 74 "prom_lex.l"
+#line 76 "prom_lex.l"
{ upval(BOOTDEV); }
YY_BREAK
case 11:
YY_RULE_SETUP
-#line 75 "prom_lex.l"
+#line 77 "prom_lex.l"
{ upval(OBPPARM); }
YY_BREAK
case 12:
YY_RULE_SETUP
-#line 76 "prom_lex.l"
+#line 78 "prom_lex.l"
{ upval(HEX4); }
YY_BREAK
case 13:
YY_RULE_SETUP
-#line 77 "prom_lex.l"
+#line 79 "prom_lex.l"
{ upval(HEX16); }
YY_BREAK
case 14:
YY_RULE_SETUP
-#line 78 "prom_lex.l"
+#line 80 "prom_lex.l"
{ upval(FILENAME); }
YY_BREAK
case 15:
/* rule 15 can match eol */
YY_RULE_SETUP
-#line 79 "prom_lex.l"
+#line 81 "prom_lex.l"
{ /* eat all whitespace. */
yylloc.first_column = yylloc.last_column;
yylloc.last_column += yyleng;
@@ -1281,7 +1319,7 @@ YY_RULE_SETUP
YY_BREAK
case 16:
YY_RULE_SETUP
-#line 83 "prom_lex.l"
+#line 85 "prom_lex.l"
{ /* any other single char. */
dbg("??");
yylloc.first_column = yylloc.last_column;
@@ -1290,15 +1328,15 @@ YY_RULE_SETUP
}
YY_BREAK
case YY_STATE_EOF(INITIAL):
-#line 90 "prom_lex.l"
+#line 92 "prom_lex.l"
yyterminate();
YY_BREAK
case 17:
YY_RULE_SETUP
-#line 91 "prom_lex.l"
+#line 93 "prom_lex.l"
ECHO;
YY_BREAK
-#line 1302 "<stdout>"
+#line 1340 "<stdout>"
case YY_END_OF_BUFFER:
{
@@ -1528,7 +1566,7 @@ static int yy_get_next_buffer (void)
/* Read in more data. */
YY_INPUT( (&YY_CURRENT_BUFFER_LVALUE->yy_ch_buf[number_to_move]),
- (yy_n_chars), num_to_read );
+ (yy_n_chars), (size_t) num_to_read );
YY_CURRENT_BUFFER_LVALUE->yy_n_chars = (yy_n_chars);
}
@@ -1552,6 +1590,14 @@ static int yy_get_next_buffer (void)
else
ret_val = EOB_ACT_CONTINUE_SCAN;
+ if ((yy_size_t) ((yy_n_chars) + number_to_move) > YY_CURRENT_BUFFER_LVALUE->yy_buf_size) {
+ /* Extend the array by 50%, plus the number we really need. */
+ yy_size_t new_size = (yy_n_chars) + number_to_move + ((yy_n_chars) >> 1);
+ YY_CURRENT_BUFFER_LVALUE->yy_ch_buf = (char *) yyrealloc((void *) YY_CURRENT_BUFFER_LVALUE->yy_ch_buf,new_size );
+ if ( ! YY_CURRENT_BUFFER_LVALUE->yy_ch_buf )
+ YY_FATAL_ERROR( "out of dynamic memory in yy_get_next_buffer()" );
+ }
+
(yy_n_chars) += number_to_move;
YY_CURRENT_BUFFER_LVALUE->yy_ch_buf[(yy_n_chars)] = YY_END_OF_BUFFER_CHAR;
YY_CURRENT_BUFFER_LVALUE->yy_ch_buf[(yy_n_chars) + 1] = YY_END_OF_BUFFER_CHAR;
@@ -1618,43 +1664,6 @@ static int yy_get_next_buffer (void)
return yy_is_jam ? 0 : yy_current_state;
}
- static void yyunput (int c, register char * yy_bp )
-{
- register char *yy_cp;
-
- yy_cp = (yy_c_buf_p);
-
- /* undo effects of setting up yytext */
- *yy_cp = (yy_hold_char);
-
- if ( yy_cp < YY_CURRENT_BUFFER_LVALUE->yy_ch_buf + 2 )
- { /* need to shift things up to make room */
- /* +2 for EOB chars. */
- register int number_to_move = (yy_n_chars) + 2;
- register char *dest = &YY_CURRENT_BUFFER_LVALUE->yy_ch_buf[
- YY_CURRENT_BUFFER_LVALUE->yy_buf_size + 2];
- register char *source =
- &YY_CURRENT_BUFFER_LVALUE->yy_ch_buf[number_to_move];
-
- while ( source > YY_CURRENT_BUFFER_LVALUE->yy_ch_buf )
- *--dest = *--source;
-
- yy_cp += (int) (dest - source);
- yy_bp += (int) (dest - source);
- YY_CURRENT_BUFFER_LVALUE->yy_n_chars =
- (yy_n_chars) = YY_CURRENT_BUFFER_LVALUE->yy_buf_size;
-
- if ( yy_cp < YY_CURRENT_BUFFER_LVALUE->yy_ch_buf + 2 )
- YY_FATAL_ERROR( "flex scanner push-back overflow" );
- }
-
- *--yy_cp = (char) c;
-
- (yytext_ptr) = yy_bp;
- (yy_hold_char) = *yy_cp;
- (yy_c_buf_p) = yy_cp;
-}
-
#ifndef YY_NO_INPUT
#ifdef __cplusplus
static int yyinput (void)
@@ -1963,7 +1972,9 @@ static void yyensure_buffer_stack (void)
(yy_buffer_stack) = (struct yy_buffer_state**)yyalloc
(num_to_alloc * sizeof(struct yy_buffer_state*)
);
-
+ if ( ! (yy_buffer_stack) )
+ YY_FATAL_ERROR( "out of dynamic memory in yyensure_buffer_stack()" );
+
memset((yy_buffer_stack), 0, num_to_alloc * sizeof(struct yy_buffer_state*));
(yy_buffer_stack_max) = num_to_alloc;
@@ -1981,6 +1992,8 @@ static void yyensure_buffer_stack (void)
((yy_buffer_stack),
num_to_alloc * sizeof(struct yy_buffer_state*)
);
+ if ( ! (yy_buffer_stack) )
+ YY_FATAL_ERROR( "out of dynamic memory in yyensure_buffer_stack()" );
/* zero only the new slots.*/
memset((yy_buffer_stack) + (yy_buffer_stack_max), 0, grow_size * sizeof(struct yy_buffer_state*));
@@ -2025,7 +2038,7 @@ YY_BUFFER_STATE yy_scan_buffer (char *
/** Setup the input buffer state to scan a string. The next call to yylex() will
* scan from a @e copy of @a str.
- * @param str a NUL-terminated string to scan
+ * @param yystr a NUL-terminated string to scan
*
* @return the newly allocated buffer state object.
* @note If you want to scan bytes that may contain NUL values, then use
@@ -2039,8 +2052,8 @@ YY_BUFFER_STATE yy_scan_string (yyconst
/** Setup the input buffer state to scan the given bytes. The next call to yylex() will
* scan from a @e copy of @a bytes.
- * @param bytes the byte buffer to scan
- * @param len the number of bytes in the buffer pointed to by @a bytes.
+ * @param yybytes the byte buffer to scan
+ * @param _yybytes_len the number of bytes in the buffer pointed to by @a bytes.
*
* @return the newly allocated buffer state object.
*/
@@ -2279,7 +2292,7 @@ void yyfree (void * ptr )
#define YYTABLES_NAME "yytables"
-#line 91 "prom_lex.l"
+#line 93 "prom_lex.l"
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/utils/fwparam_ibft/prom_lex.l open-iscsi-2.0-872-rc4-bnx2i.work/utils/fwparam_ibft/prom_lex.l
--- open-iscsi-2.0-872-rc4-bnx2i/utils/fwparam_ibft/prom_lex.l 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/utils/fwparam_ibft/prom_lex.l 2012-03-05 23:02:46.000000000 -0600
@@ -43,6 +43,8 @@ void dbgprint(const char *item) { fprint
%option noyywrap
%option never-interactive
+%option nounput
+%option noinput
VDEVICE vdevice
VDEVINST gscsi
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/utils/open-isns/client.c open-iscsi-2.0-872-rc4-bnx2i.work/utils/open-isns/client.c
--- open-iscsi-2.0-872-rc4-bnx2i/utils/open-isns/client.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/utils/open-isns/client.c 2012-03-05 23:02:46.000000000 -0600
@@ -123,8 +123,10 @@ static isns_security_t *
__create_security_context(const char *name, const char *auth_key,
const char *server_key)
{
+#ifdef WITH_SECURITY
isns_security_t *ctx;
isns_principal_t *princ;
+#endif /* WITH_SECURITY */
if (!isns_config.ic_security)
return NULL;
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/utils/open-isns/db-file.c open-iscsi-2.0-872-rc4-bnx2i.work/utils/open-isns/db-file.c
--- open-iscsi-2.0-872-rc4-bnx2i/utils/open-isns/db-file.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/utils/open-isns/db-file.c 2012-03-05 23:02:46.000000000 -0600
@@ -310,7 +310,7 @@ __dbe_file_load_object(const char *filen
/* Stash away the parent's index; we resolve them later on
* once we've loaded all objects */
- obj->ie_container = (isns_object_t *) ntohl(info.db_parent);
+ obj->ie_container_idx = ntohl(info.db_parent);
isns_object_list_append(result, obj);
@@ -493,7 +493,7 @@ isns_dbe_file_reload(isns_db_t *db)
/* Resolve parent/child relationship for all nodes */
for (i = 0; i < db->id_objects->iol_count; ++i) {
isns_object_t *obj = db->id_objects->iol_data[i];
- uint32_t index = (uint32_t) obj->ie_container;
+ uint32_t index = obj->ie_container_idx;
isns_object_t *parent;
if (index == 0)
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/utils/open-isns/db-policy.c open-iscsi-2.0-872-rc4-bnx2i.work/utils/open-isns/db-policy.c
--- open-iscsi-2.0-872-rc4-bnx2i/utils/open-isns/db-policy.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/utils/open-isns/db-policy.c 2012-03-05 23:03:38.000000000 -0600
@@ -7,8 +7,10 @@
#include <sys/stat.h>
#include <string.h>
#include <unistd.h>
+#ifdef WITH_SECURITY
#include <openssl/pem.h>
#include <openssl/err.h>
+#endif
#include "isns.h"
#include "security.h"
#include "objects.h"
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/utils/open-isns/doc/rfc2608.txt open-iscsi-2.0-872-rc4-bnx2i.work/utils/open-isns/doc/rfc2608.txt
--- open-iscsi-2.0-872-rc4-bnx2i/utils/open-isns/doc/rfc2608.txt 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/utils/open-isns/doc/rfc2608.txt 1969-12-31 18:00:00.000000000 -0600
@@ -1,3027 +0,0 @@
-
-
-
-
-
-
-Network Working Group E. Guttman
-Request for Comments: 2608 C. Perkins
-Updates: 2165 Sun Microsystems
-Category: Standards Track J. Veizades
- @Home Network
- M. Day
- Vinca Corporation
- June 1999
-
-
- Service Location Protocol, Version 2
-
-Status of This Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (1999). All Rights Reserved.
-
-Abstract
-
- The Service Location Protocol provides a scalable framework for the
- discovery and selection of network services. Using this protocol,
- computers using the Internet need little or no static configuration
- of network services for network based applications. This is
- especially important as computers become more portable, and users
- less tolerant or able to fulfill the demands of network system
- administration.
-
-Table of Contents
-
- 1. Introduction 3
- 1.1. Applicability Statement . . . . . . . . . . . . . . . 3
- 2. Terminology 4
- 2.1. Notation Conventions . . . . . . . . . . . . . . . . . 4
- 3. Protocol Overview 5
- 4. URLs used with Service Location 8
- 4.1. Service: URLs . . . . . . . . . . . . . . . . . . . . 9
- 4.2. Naming Authorities . . . . . . . . . . . . . . . . . 10
- 4.3. URL Entries . . . . . . . . . . . . . . . . . . . . . 10
- 5. Service Attributes 10
- 6. Required Features 12
- 6.1. Use of Ports, UDP, and Multicast . . . . . . . . . . 13
-
-
-
-Guttman, et al. Standards Track [Page 1]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- 6.2. Use of TCP . . . . . . . . . . . . . . . . . . . . . 14
- 6.3. Retransmission of SLP messages . . . . . . . . . . . 15
- 6.4. Strings in SLP messages . . . . . . . . . . . . . . . 16
- 6.4.1. Scope Lists in SLP . . . . . . . . . . . . . . 16
- 7. Errors 17
- 8. Required SLP Messages 17
- 8.1. Service Request . . . . . . . . . . . . . . . . . . . 19
- 8.2. Service Reply . . . . . . . . . . . . . . . . . . . . 21
- 8.3. Service Registration . . . . . . . . . . . . . . . . . 22
- 8.4. Service Acknowledgment . . . . . . . . . . . . . . . . 23
- 8.5. Directory Agent Advertisement. . . . . . . . . . . . . 24
- 8.6. Service Agent Advertisement. . . . . . . . . . . . . . 25
- 9. Optional Features 26
- 9.1. Service Location Protocol Extensions . . . . . . . . . 27
- 9.2. Authentication Blocks . . . . . . . . . . . . . . . . 28
- 9.2.1. SLP Message Authentication Rules . . . . . . . 29
- 9.2.2. DSA with SHA-1 in Authentication Blocks . . . 30
- 9.3. Incremental Service Registration . . . . . . . . . . 30
- 9.4. Tag Lists . . . . . . . . . . . . . . . . . . . . . . 31
- 10. Optional SLP Messages 32
- 10.1. Service Type Request . . . . . . . . . . . . . . . . 32
- 10.2. Service Type Reply . . . . . . . . . . . . . . . . . 32
- 10.3. Attribute Request . . . . . . . . . . . . . . . . . . 33
- 10.4. Attribute Reply . . . . . . . . . . . . . . . . . . . 34
- 10.5. Attribute Request/Reply Examples . . . . . . . . . . . 34
- 10.6. Service Deregistration . . . . . . . . . . . . . . . 36
- 11. Scopes 37
- 11.1. Scope Rules . . . . . . . . . . . . . . . . . . . . . 37
- 11.2. Administrative and User Selectable Scopes. . . . . . . 38
- 12. Directory Agents 38
- 12.1. Directory Agent Rules . . . . . . . . . . . . . . . . 39
- 12.2. Directory Agent Discovery . . . . . . . . . . . . . . 39
- 12.2.1. Active DA Discovery . . . . . . . . . . . . . 40
- 12.2.2. Passive DA Advertising . . . . . . . . . . . . 40
- 12.3. Reliable Unicast to DAs and SAs. . . . . . . . . . . . 41
- 12.4. DA Scope Configuration . . . . . . . . . . . . . . . 41
- 12.5. DAs and Authentication Blocks. . . . . . . . . . . . . 41
- 13. Protocol Timing Defaults 42
- 14. Optional Configuration 43
- 15. IANA Considerations 44
- 16. Internationalization Considerations 45
- 17. Security Considerations 46
- A. Appendix: Changes to the Service Location Protocol from
- v1 to v2 48
- B. Appendix: Service Discovery by Type: Minimal SLPv2 Features 48
- C. Appendix: DAAdverts with arbitrary URLs 49
- D. Appendix: SLP Protocol Extensions 50
- D.1. Required Attribute Missing Option . . . . . . . . . . 50
-
-
-
-Guttman, et al. Standards Track [Page 2]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- E. Acknowledgments 50
- F. References 51
- G. Authors' Addresses 53
- H. Full Copyright Statement 54
-
-1. Introduction
-
- The Service Location Protocol (SLP) provides a flexible and scalable
- framework for providing hosts with access to information about the
- existence, location, and configuration of networked services.
- Traditionally, users have had to find services by knowing the name of
- a network host (a human readable text string) which is an alias for a
- network address. SLP eliminates the need for a user to know the name
- of a network host supporting a service. Rather, the user supplies
- the desired type of service and a set of attributes which describe
- the service. Based on that description, the Service Location
- Protocol resolves the network address of the service for the user.
-
- SLP provides a dynamic configuration mechanism for applications in
- local area networks. Applications are modeled as clients that need
- to find servers attached to any of the available networks within an
- enterprise. For cases where there are many different clients and/or
- services available, the protocol is adapted to make use of nearby
- Directory Agents that offer a centralized repository for advertised
- services.
-
- This document updates SLPv1 [RFC 2165], correcting protocol errors,
- adding some enhancements and removing some requirements. This
- specification has two parts. The first describes the required
- features of the protocol. The second describes the extended features
- of the protocol which are optional, and allow greater scalability.
-
-1.1. Applicability Statement
-
- SLP is intended to function within networks under cooperative
- administrative control. Such networks permit a policy to be
- implemented regarding security, multicast routing and organization of
- services and clients into groups which are not be feasible on the
- scale of the Internet as a whole.
-
- SLP has been designed to serve enterprise networks with shared
- services, and it may not necessarily scale for wide-area service
- discovery throughout the global Internet, or in networks where there
- are hundreds of thousands of clients or tens of thousands of
- services.
-
-
-
-
-
-
-Guttman, et al. Standards Track [Page 3]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
-2. Terminology
-
- User Agent (UA)
- A process working on the user's behalf to establish
- contact with some service. The UA retrieves service
- information from the Service Agents or Directory Agents.
-
- Service Agent (SA) A process working on the behalf of one or more
- services to advertise the services.
-
- Directory Agent (DA) A process which collects service
- advertisements. There can only be one DA present per
- given host.
-
- Service Type Each type of service has a unique Service Type
- string.
-
- Naming Authority The agency or group which catalogues given
- Service Types and Attributes. The default Naming
- Authority is IANA.
-
- Scope A set of services, typically making up a logical
- administrative group.
-
- URL A Universal Resource Locator [8].
-
-2.1. Notation Conventions
-
- 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 [9].
-
- Syntax Syntax for string based protocols follow the
- conventions defined for ABNF [11].
-
- Strings All strings are encoded using the UTF-8 [23]
- transformation of the Unicode [6] character set and
- are NOT null terminated when transmitted. Strings
- are preceded by a two byte length field.
-
- <string-list> A comma delimited list of strings with the
- following syntax:
-
- string-list = string / string `,' string-list
-
- In format diagrams, any field ending with a \ indicates a variable
- length field, given by a prior length field in the protocol.
-
-
-
-
-Guttman, et al. Standards Track [Page 4]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
-3. Protocol Overview
-
- The Service Location Protocol supports a framework by which client
- applications are modeled as 'User Agents' and services are advertised
- by 'Service Agents.' A third entity, called a 'Directory Agent'
- provides scalability to the protocol.
-
- The User Agent issues a 'Service Request' (SrvRqst) on behalf of the
- client application, specifying the characteristics of the service
- which the client requires. The User Agent will receive a Service
- Reply (SrvRply) specifying the location of all services in the
- network which satisfy the request.
-
- The Service Location Protocol framework allows the User Agent to
- directly issue requests to Service Agents. In this case the request
- is multicast. Service Agents receiving a request for a service which
- they advertise unicast a reply containing the service's location.
-
- +------------+ ----Multicast SrvRqst----> +---------------+
- | User Agent | | Service Agent |
- +------------+ <----Unicast SrvRply------ +---------------+
-
- In larger networks, one or more Directory Agents are used. The
- Directory Agent functions as a cache. Service Agents send register
- messages (SrvReg) containing all the services they advertise to
- Directory Agents and receive acknowledgements in reply (SrvAck).
- These advertisements must be refreshed with the Directory Agent or
- they expire. User Agents unicast requests to Directory Agents
- instead of Service Agents if any Directory Agents are known.
-
- +-------+ -Unicast SrvRqst-> +-----------+ <-Unicast SrvReg- +--------+
- | User | | Directory | |Service |
- | Agent | | Agent | | Agent |
- +-------+ <-Unicast SrvRply- +-----------+ -Unicast SrvAck-> +--------+
-
- User and Service Agents discover Directory Agents two ways. First,
- they issue a multicast Service Request for the 'Directory Agent'
- service when they start up. Second, the Directory Agent sends an
- unsolicited advertisement infrequently, which the User and Service
- Agents listen for. In either case the Agents receive a DA
- Advertisement (DAAdvert).
-
- +---------------+ --Multicast SrvRqst-> +-----------+
- | User or | <--Unicast DAAdvert-- | Directory |
- | Service Agent | | Agent |
- +---------------+ <-Multicast DAAdvert- +-----------+
-
-
-
-
-
-Guttman, et al. Standards Track [Page 5]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- Services are grouped together using 'scopes'. These are strings
- which identify services which are administratively identified. A
- scope could indicate a location, administrative grouping, proximity
- in a network topology or some other category. Service Agents and
- Directory Agents are always assigned a scope string.
-
- A User Agent is normally assigned a scope string (in which case the
- User Agent will only be able to discover that particular grouping of
- services). This allows a network administrator to 'provision'
- services to users. Alternatively, the User Agent may be configured
- with no scope at all. In that case, it will discover all available
- scopes and allow the client application to issue requests for any
- service available on the network.
-
- +---------+ Multicast +-----------+ Unicast +-----------+
- | Service | <--SrvRqst-- | User | --SrvRqst-> | Directory |
- | Agent | | Agent | | Agent |
- | Scope=X | Unicast | Scope=X,Y | Unicast | Scope=Y |
- +---------+ --SrvRply--> +-----------+ <-SrvRply-- +-----------+
-
- In the above illustration, the User Agent is configured with scopes X
- and Y. If a service is sought in scope X, the request is multicast.
- If it is sought in scope Y, the request is unicast to the DA.
- Finally, if the request is to be made in both scopes, the request
- must be both unicast and multicast.
-
- Service Agents and User Agents may verify digital signatures provided
- with DAAdverts. User Agents and Directory Agents may verify service
- information registered by Service Agents. The keying material to use
- to verify digital signatures is identified using a SLP Security
- Parameter Index, or SLP SPI.
-
- Every host configured to generate a digital signature includes the
- SLP SPI used to verify it in the Authentication Block it transmits.
- Every host which can verify a digital signature must be configured
- with keying material and other parameters corresponding with the SLP
- SPI such that it can perform verifying calculations.
-
- SAs MUST accept multicast service requests and unicast service
- requests. SAs MAY accept other requests (Attribute and Service Type
- Requests). SAs MUST listen for multicast DA Advertisements.
-
- The features described up to this point are required to implement. A
- minimum implementation consists of a User Agent, Service Agent or
- both.
-
- There are several optional features in the protocol. Note that DAs
- MUST support all these message types, but DA support is itself
-
-
-
-Guttman, et al. Standards Track [Page 6]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- optional to deploy on networks using SLP. UAs and SAs MAY support
- these message types. These operations are primarily for interactive
- use (browsing or selectively updating service registrations.) UAs
- and SAs either support them or not depending on the requirements and
- constraints of the environment where they will be used.
-
- Service Type Request A request for all types of service on the
- network. This allows generic service browsers
- to be built.
-
- Service Type Reply A reply to a Service Type Request.
-
- Attribute Request A request for attributes of a given type of
- service or attributes of a given service.
-
- Attribute Reply A reply to an Attribute Request.
-
- Service Deregister A request to deregister a service or some
- attributes of a service.
-
- Service Update A subsequent SrvRqst to an advertisement.
- This allows individual dynamic attributes to
- be updated.
-
- SA Advertisement In the absence of Directory Agents, a User
- agent may request Service Agents in order
- to discover their scope configuration. The
- User Agent may use these scopes in requests.
-
- In the absence of Multicast support, Broadcast MAY be used. The
- location of DAs may be staticly configured, discovered using SLP as
- described above, or configured using DHCP. If a message is too large,
- it may be unicast using TCP.
-
- A SLPv2 implementation SHOULD support SLPv1 [22]. This support
- includes:
-
- 1. SLPv2 DAs are deployed, phasing out SLPv1 DAs.
-
- 2. Unscoped SLPv1 requests are considered to be of DEFAULT scope.
- SLPv1 UAs MUST be reconfigured to have a scope if possible.
-
- 3. There is no way for an SLPv2 DA to behave as an unscoped SLPv1
- DA. SLPv1 SAs MUST be reconfigured to have a scope if possible.
-
- 4. SLPv2 DAs answer SLPv1 requests with SLPv1 replies and SLPv2
- requests with SLPv2 replies.
-
-
-
-
-Guttman, et al. Standards Track [Page 7]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- 5. SLPv2 DAs use registrations from SLPv1 and SLPv2 in the same
- way. That is, incoming requests from agents using either version
- of the protocol will be matched against this common set of
- registered services.
-
- 6. SLPv2 registrations which use Language Tags which are greater
- than 2 characters long will be inaccessible to SLPv1 UAs.
-
- 7. SLPv2 DAs MUST return only service type strings in SrvTypeRply
- messages which conform to SLPv1 service type string syntax, ie.
- they MUST NOT return Service Type strings for abstract service
- types.
-
- 8. SLPv1 SrvRqsts and AttrRqsts by Service Type do not match Service
- URLs with abstract service types. They only match Service URLs
- with concrete service types.
-
- SLPv1 UAs will not receive replies from SLPv2 SAs and SLPv2 UAs will
- not receive replies from SLPv1 SAs. In order to interoperate UAs and
- SAs of different versions require a SLPv2 DA to be present on the
- network which supports both protocols.
-
- The use of abstract service types in SLPv2 presents a backward
- compatibility issue for SLPv1. It is possible that a SLPv1 UA will
- request a service type which is actually an abstract service type.
- Based on the rules above, the SLPv1 UA will never receive an abstract
- Service URL reply. For example, the service type 'service:x' in a
- SLPv1 AttrRqst will not return the attributes of 'service:x:y://orb'.
- If the request was made with SLPv2, it would return the attributes of
- this service.
-
-4. URLs used with Service Location
-
- A Service URL indicates the location of a service. This URL may be
- of the service: scheme [13] (reviewed in section 4.1), or any other
- URL scheme conforming to the URI standard [8], except that URLs
- without address specifications SHOULD NOT be advertised by SLP. The
- service type for an 'generic' URL is its scheme name. For example,
- the service type string for "http://www.srvloc.org" would be "http".
-
- Reserved characters in URLs follow the rules in RFC 2396 [8].
-
-
-
-
-
-
-
-
-
-
-Guttman, et al. Standards Track [Page 8]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
-4.1. Service: URLs
-
- Service URL syntax and semantics are defined in [13]. Any network
- service may be encoded in a Service URL.
-
- This section provides an introduction to Service URLs and an example
- showing a simple application of them, representing standard network
- services.
-
- A Service URL may be of the form:
-
- "service:"<srvtype>"://"<addrspec>
-
- The Service Type of this service: URL is defined to be the string up
- to (but not including) the final `:' before <addrspec>, the address
- specification.
-
- <addrspec> is a hostname (which should be used if possible) or dotted
- decimal notation for a hostname, followed by an optional `:' and
- port number.
-
- A service: scheme URL may be formed with any standard protocol name
- by concatenating "service:" and the reserved port [1] name. For
- example, "service:tftp://myhost" would indicate a tftp service. A
- tftp service on a nonstandard port could be
- "service:tftp://bad.glad.org:8080".
-
- Service Types SHOULD be defined by a "Service Template" [13], which
- provides expected attributes, values and protocol behavior. An
- abstract service type (also described in [13]) has the form
-
- "service:<abstract-type>:<concrete-type>".
-
- The service type string "service:<abstract-type>" matches all
- services of that abstract type. If the concrete type is included
- also, only these services match the request. For example: a SrvRqst
- or AttrRqst which specifies "service:printer" as the Service Type
- will match the URL service:printer:lpr://hostname and
- service:printer:http://hostname. If the requests specified
- "service:printer:http" they would match only the latter URL.
-
- An optional substring MAY follow the last `.' character in the
- <srvtype> (or <abstract-type> in the case of an abstract service type
- URL). This substring is the Naming Authority, as described in Section
- 9.6. Service types with different Naming Authorities are quite
- distinct. In other words, service:x.one and service:x.two are
- different service types, as are service:abstract.one:y and
- service:abstract.two:y.
-
-
-
-Guttman, et al. Standards Track [Page 9]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
-4.2. Naming Authorities
-
- A Naming Authority MAY optionally be included as part of the Service
- Type string. The Naming Authority of a service defines the meaning
- of the Service Types and attributes registered with and provided by
- Service Location. The Naming Authority itself is typically a string
- which uniquely identifies an organization. IANA is the implied
- Naming Authority when no string is appended. "IANA" itself MUST NOT
- be included explicitly.
-
- Naming Authorities may define Service Types which are experimental,
- proprietary or for private use. Using a Naming Authority, one may
- either simply ignore attributes upon registration or create a local-
- use only set of attributes for one's site. The procedure to use is
- to create a 'unique' Naming Authority string and then specify the
- Standard Attribute Definitions as described above. This Naming
- Authority will accompany registration and queries, as described in
- Sections 8.1 and 8.3. Service Types SHOULD be registered with IANA
- to allow for Internet-wide interoperability.
-
-4.3. URL Entries
-
- 0 1 2 3
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Reserved | Lifetime | URL Length |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- |URL len, contd.| URL (variable length) \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- |# of URL auths | Auth. blocks (if any) \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-
- SLP stores URLs in protocol elements called URL Entries, which
- associate a length, a lifetime, and possibly authentication
- information along with the URL. URL Entries, defined as shown above,
- are used in Service Replies and Service Registrations.
-
-5. Service Attributes
-
- A service advertisement is often accompanied by Service Attributes.
- These attributes are used by UAs in Service Requests to select
- appropriate services.
-
- The allowable attributes which may be used are typically specified by
- a Service Template [13] for a particular service type. Services
- which are advertised according to a standard template MUST register
- all service attributes which the standard template requires. URLs
- with schemes other than "service:" MAY be registered with attributes.
-
-
-
-Guttman, et al. Standards Track [Page 10]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- Non-standard attribute names SHOULD begin with "x-", because no
- standard attribute name will ever have those initial characters.
-
- An attribute list is a string encoding of the attributes of a
- service. The following ABNF [11] grammar defines attribute lists:
-
- attr-list = attribute / attribute `,' attr-list
- attribute = `(' attr-tag `=' attr-val-list `)' / attr-tag
- attr-val-list = attr-val / attr-val `,' attr-val-list
- attr-tag = 1*safe-tag
- attr-val = intval / strval / boolval / opaque
- intval = [-]1*DIGIT
- strval = 1*safe-val
- boolval = "true" / "false"
- opaque = "\FF" 1*escape-val
- safe-val = ; Any character except reserved.
- safe-tag = ; Any character except reserved, star and bad-tag.
- reserved = `(' / `)' / `,' / `\' / `!' / `<' / `=' / `>' / `~' / CTL
- escape-val = `\' HEXDIG HEXDIG
- bad-tag = CR / LF / HTAB / `_'
- star = `*'
-
- The <attr-list>, if present, MUST be scanned prior to evaluation for
- all occurrences of the escape character `\'. Reserved characters
- MUST be escaped (other characters MUST NOT be escaped). All escaped
- characters must be restored to their value before attempting string
- matching. For Opaque values, escaped characters are not converted -
- they are interpreted as bytes.
-
- Boolean Strings which have the form "true" or "false" can
- only take one value and may only be compared with
- '='. Booleans are case insensitive when compared.
-
- Integer Strings which take the form [-] 1*<digit> and fall
- in the range "-2147483648" to "2147483647" are
- considered to be Integers. These are compared using
- integer comparison.
-
- String All other Strings are matched using strict lexical
- ordering (see Section 6.4).
-
- Opaque Opaque values are sequences of bytes. These are
- distinguished from Strings since they begin with
- the sequence "\FF". This, unescaped, is an illegal
- UTF-8 encoding, indicating that what follows is a
- sequence of bytes expressed in escape notation which
- constitute the binary value. For example, a '0' byte
- is encoded "\FF\00".
-
-
-
-Guttman, et al. Standards Track [Page 11]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- A string which contains escaped values other than from the reserved
- set of characters is illegal. If such a string is included in an
- <attr-list>, <tag-list> or search filter, the SA or DA which receives
- it MUST return a PARSE_ERROR to the message.
-
- A keyword has only an <attr-tag>, and no values. Attributes can have
- one or multiple values. All values are expressed as strings.
-
- When values have been advertised by a SA or are registered in a DA,
- they can take on implicit typing rules for matching incoming
- requests.
-
- Stored values must be consistent, i.e., x=4,true,sue,\ff\00\00 is
- disallowed. A DA or SA receiving such an <attr-list> MUST return an
- INVALID_REGISTRATION error.
-
-6. Required Features
-
- This section defines the minimal implementation requirements for SAs
- and UAs as well as their interaction with DAs. A DA is not required
- for SLP to function, but if it is present, the UA and SA MUST
- interact with it as defined below.
-
- A minimal implementation may consist of either a UA or SA or both.
- The only required features of a UA are that it can issue SrvRqsts
- according to the rules below and interpret DAAdverts, SAAdverts and
- SrvRply messages. The UA MUST issue requests to DAs as they are
- discovered. An SA MUST reply to appropriate SrvRqsts with SrvRply or
- SAAdvert messages. The SA MUST also register with DAs as they are
- discovered.
-
- UAs perform discovery by issuing Service Request messages. SrvRqst
- messages are issued, using UDP, following these prioritized rules:
-
- 1. A UA issues a request to a DA which it has been configured with
- by DHCP.
-
- 2. A UA issues requests to DAs which it has been statically
- configured with.
-
- 3. UA uses multicast/convergence SrvRqsts to discover DAs, then uses
- that set of DAs. A UA that does not know of any DAs SHOULD retry
- DA discovery, increasing the waiting interval between subsequent
- attempts exponentially (doubling the wait interval each time.)
- The recommended minimum waiting interval is CONFIG_DA_FIND
- seconds.
-
-
-
-
-
-Guttman, et al. Standards Track [Page 12]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- 4. A UA with no knowledge of DAs sends requests using multicast
- convergence to SAs. SAs unicast replies to UAs according to the
- multicast convergence algorithm.
-
- UAs and SAs are configured with a list of scopes to use according to
- these prioritized rules:
-
- 1. With DHCP.
-
- 2. With static configuration. The static configuration may be
- explicitly set to NO SCOPE for UAs, if the User Selectable Scope
- model is used. See section 11.2.
-
- 3. In the absence of configuration, the agent's scope is "DEFAULT".
-
- A UA MUST issue requests with one or more of the scopes it has been
- configured to use.
-
- A UA which has been statically configured with NO SCOPE LIST will use
- DA or SA discovery to determine its scope list dynamically. In this
- case it uses an empty scope list to discover DAs and possibly SAs.
- Then it uses the scope list it obtains from DAAdverts and possibly
- SAAdverts in subsequent requests.
-
- The SA MUST register all its services with any DA it discovers, if
- the DA advertises any of the scopes it has been configured with. A
- SA obtains information about DAs as a UA does. In addition, the SA
- MUST listen for multicast unsolicited DAAdverts. The SA registers by
- sending SrvReg messages to DAs, which reply with SrvReg messages to
- indicate success. SAs register in ALL the scopes they were
- configured to use.
-
-6.1. Use of Ports, UDP, and Multicast
-
- DAs MUST accept unicast requests and multicast directory agent
- discovery service requests (for the service type "service:directory-
- agent").
-
- SAs MUST accept multicast requests and unicast requests both. The SA
- can distinguish between them by whether the REQUEST MCAST flag is set
- in the SLP Message header.
-
- The Service Location Protocol uses multicast for discovering DAs and
- for issuing requests to SAs by default.
-
- The reserved listening port for SLP is 427. This is the destination
- port for all SLP messages. SLP messages MAY be transmitted on an
- ephemeral port. Replies and acknowledgements are sent to the port
-
-
-
-Guttman, et al. Standards Track [Page 13]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- from which the request was issued. The default maximum transmission
- unit for UDP messages is 1400 bytes excluding UDP and other headers.
-
- If a SLP message does not fit into a UDP datagram it MUST be
- truncated to fit, and the OVERFLOW flag is set in the reply message.
- A UA which receives a truncated message MAY open a TCP connection
- (see section 6.2) with the DA or SA and retransmit the request, using
- the same XID. It MAY also attempt to make use of the truncated reply
- or reformulate a more restrictive request which will result in a
- smaller reply.
-
- SLP Requests messages are multicast to The Administratively Scoped
- SLP Multicast [17] address, which is 239.255.255.253. The default
- TTL to use for multicast is 255.
-
- In isolated networks, broadcasts will work in place of multicast. To
- that end, SAs SHOULD and DAs MUST listen for broadcast Service
- Location messages at port 427. This allows UAs which do not support
- multicast the use of Service Location on isolated networks.
-
- Setting multicast TTL to less than 255 (the default) limits the range
- of SLP discovery in a network, and localizes service information in
- the network.
-
-6.2. Use of TCP
-
- A SrvReg or SrvDeReg may be too large to fit into a datagram. To
- send such large SLP messages, a TCP (unicast) connection MUST be
- established.
-
- To avoid the need to implement TCP, one MUST insure that:
-
- - UAs never issue requests larger than the Path MTU. SAs can omit
- TCP support only if they never have to receive unicast requests
- longer than the path MTU.
-
- - UAs can accept replies with the 'OVERFLOW' flag set, and make use
- of the first result included, or reformulate the request.
-
- - Ensure that a SA can send a SrvRply, SrvReg, or SrvDeReg in
- a single datagram. This means limiting the size of URLs,
- the number of attributes and the number of authenticators
- transmitted.
-
- DAs MUST be able to respond to UDP and TCP requests, as well as
- multicast DA Discovery SrvRqsts. SAs MUST be able to respond to TCP
- unless the SA will NEVER receive a request or send a reply which will
- exceed a datagram in size (e.g., some embedded systems).
-
-
-
-Guttman, et al. Standards Track [Page 14]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- A TCP connection MAY be used for a single SLP transaction, or for
- multiple transactions. Since there are length fields in the message
- headers, SLP Agents can send multiple requests along a connection and
- read the return stream for acknowledgments and replies.
-
- The initiating agent SHOULD close the TCP connection. The DA SHOULD
- wait at least CONFIG_CLOSE_CONN seconds before closing an idle
- connection. DAs and SAs SHOULD close an idle TCP connection after
- CONFIG_CLOSE_CONN seconds to ensure robust operation, even when the
- initiating agent neglects to close it. See Section 13 for timing
- rules.
-
-6.3. Retransmission of SLP messages
-
- Requests which fail to elicit a response are retransmitted. The
- initial retransmission occurs after a CONFIG_RETRY wait period.
- Retransmissions MUST be made with exponentially increasing wait
- intervals (doubling the wait each time). This applies to unicast as
- well as multicast SLP requests.
-
- Unicast requests to a DA or SA should be retransmitted until either a
- response (which might be an error) has been obtained, or for
- CONFIG_RETRY_MAX seconds.
-
- Multicast requests SHOULD be reissued over CONFIG_MC_MAX seconds
- until a result has been obtained. UAs need only wait till they
- obtain the first reply which matches their request. That is,
- retransmission is not required if the requesting agent is prepared to
- use the 'first reply' instead of 'as many replies as possible within
- a bounded time interval.'
-
- When SLP SrvRqst, SrvTypeRqst, and AttrRqst messages are multicast,
- they contain a <PRList> of previous responders. Initially the
- <PRList> is empty. When these requests are unicast, the <PRList> is
- always empty.
-
- Any DA or SA which sees its address in the <PRList> MUST NOT respond
- to the request.
-
- The message SHOULD be retransmitted until the <PRList> causes no
- further responses to be elicited or the previous responder list and
- the request will not fit into a single datagram or until
- CONFIG_MC_MAX seconds elapse.
-
- UAs which retransmit a request use the same XID. This allows a DA or
- SA to cache its reply to the original request and then send it again,
- should a duplicate request arrive. This cached information should
- only be held very briefly. XIDs SHOULD be randomly chosen to avoid
-
-
-
-Guttman, et al. Standards Track [Page 15]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- duplicate XIDs in requests if UAs restart frequently.
-
-6.4. Strings in SLP messages
-
- The escape character is a backslash (UTF-8 0x5c) followed by the two
- hexadecimal digits of the escaped character. Only reserved
- characters are escaped. For example, a comma (UTF-8 0x29) is escaped
- as `\29', and a backslash `\' is escaped as `\5c'. String lists used
- in SLP define the comma to be the delimiter between list elements, so
- commas in data strings must be escaped in this manner. Backslashes
- are the escape character so they also must always be escaped when
- included in a string literally.
-
- String comparison for order and equality in SLP MUST be case
- insensitive inside the 0x00-0x7F subrange of UTF-8 (which corresponds
- to ASCII character encoding). Case insensitivity SHOULD be supported
- throughout the entire UTF-8 encoded Unicode [6] character set.
-
- The case insensitivity rule applies to all string matching in SLPv2,
- including Scope strings, SLP SPI strings, service types, attribute
- tags and values in query handling, language tags, previous responder
- lists. Comparisons of URL strings, however, is case sensitive.
-
- White space (SPACE, CR, LF, TAB) internal to a string value is folded
- to a single SPACE character for the sake of string comparisons.
- White space preceding or following a string value is ignored for the
- purposes of string comparison. For example, " Some String "
- matches "SOME STRING".
-
- String comparisons (using comparison operators such as `<=' or `>=')
- are done using lexical ordering in UTF-8 encoded characters, not
- using any language specific rules.
-
- The reserved character `*' may precede, follow or be internal to a
- string value in order to indicate substring matching. The query
- including this character matches any character sequence which
- conforms to the letters which are not wildcarded.
-
-6.4.1. Scope Lists in SLP
-
- Scope Lists in SLPv2 have the following grammar:
-
- scope-list = scope-val / scope-val `,' scope-list
- scope-val = 1*safe
- safe = ; Any character except reserved.
- reserved = `(' / `)' / `,' / `\' / `!' / `<' / `=' / `>' / `~' / CTL
- / `;' / `*' / `+'
- escape-val = `\' HEXDIG HEXDIG
-
-
-
-Guttman, et al. Standards Track [Page 16]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- Scopes which include any reserved characters must replace the escaped
- character with the escaped-val format.
-
-7. Errors
-
- If the Error Code in a SLP reply message is nonzero, the rest of the
- message MAY be truncated. No data is necessarily transmitted or
- should be expected after the header and the error code, except
- possibly for some optional extensions to clarify the error, for
- example as in section D.1.
-
- Errors are only returned for unicast requests. Multicast requests
- are silently discarded if they result in an error.
-
- LANGUAGE_NOT_SUPPORTED = 1: There is data for the service type in
- the scope in the AttrRqst or SrvRqst, but not in the requested
- language.
- PARSE_ERROR = 2: The message fails to obey SLP syntax.
- INVALID_REGISTRATION = 3: The SrvReg has problems -- e.g., a zero
- lifetime or an omitted Language Tag.
- SCOPE_NOT_SUPPORTED = 4: The SLP message did not include a scope in
- its <scope-list> supported by the SA or DA.
- AUTHENTICATION_UNKNOWN = 5: The DA or SA receives a request for an
- unsupported SLP SPI.
- AUTHENTICATION_ABSENT = 6: The DA expected URL and ATTR
- authentication in the SrvReg and did not receive it.
- AUTHENTICATION_FAILED = 7: The DA detected an authentication error in
- an Authentication block.
- VER_NOT_SUPPORTED = 9: Unsupported version number in message header.
- INTERNAL_ERROR = 10: The DA (or SA) is too sick to respond.
- DA_BUSY_NOW = 11: UA or SA SHOULD retry, using exponential back off.
- OPTION_NOT_UNDERSTOOD = 12: The DA (or SA) received an unknown option
- from the mandatory range (see section 9.1).
- INVALID_UPDATE = 13: The DA received a SrvReg without FRESH set, for
- an unregistered service or with inconsistent Service Types.
- MSG_NOT_SUPPORTED = 14: The SA received an AttrRqst or SrvTypeRqst
- and does not support it.
- REFRESH_REJECTED = 15: The SA sent a SrvReg or partial SrvDereg to a
- DA more frequently than the DA's min-refresh-interval.
-
-8. Required SLP Messages
-
- All length fields in SLP messages are in network byte order. Where '
- tuples' are defined, these are sequences of bytes, in the precise
- order listed, in network byte order.
-
- SLP messages all begin with the following header:
-
-
-
-
-Guttman, et al. Standards Track [Page 17]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- 0 1 2 3
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Version | Function-ID | Length |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Length, contd.|O|F|R| reserved |Next Ext Offset|
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Next Extension Offset, contd.| XID |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Language Tag Length | Language Tag \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-
- Message Type Abbreviation Function-ID
-
- Service Request SrvRqst 1
- Service Reply SrvRply 2
- Service Registration SrvReg 3
- Service Deregister SrvDeReg 4
- Service Acknowledge SrvAck 5
- Attribute Request AttrRqst 6
- Attribute Reply AttrRply 7
- DA Advertisement DAAdvert 8
- Service Type Request SrvTypeRqst 9
- Service Type Reply SrvTypeRply 10
- SA Advertisement SAAdvert 11
-
- SAs and UAs MUST support SrvRqst, SrvRply and DAAdvert. SAs MUST
- also support SrvReg, SAAdvert and SrvAck. For UAs and SAs, support
- for other messages are OPTIONAL.
-
- - Length is the length of the entire SLP message, header included.
- - The flags are: OVERFLOW (0x80) is set when a message's length
- exceeds what can fit into a datagram. FRESH (0x40) is set on
- every new SrvReg. REQUEST MCAST (0x20) is set when multicasting
- or broadcasting requests. Reserved bits MUST be 0.
- - Next Extension Offset is set to 0 unless extensions are used.
- The first extension begins at 'offset' bytes, from the message's
- beginning. It is placed after the SLP message data. See
- Section 9.1 for how to interpret unrecognized SLP Extensions.
- - XID is set to a unique value for each unique request. If the
- request is retransmitted, the same XID is used. Replies set
- the XID to the same value as the xid in the request. Only
- unsolicited DAAdverts are sent with an XID of 0.
- - Lang Tag Length is the length in bytes of the Language Tag field.
- - Language Tag conforms to [7]. The Language Tag in a reply MUST
- be the same as the Language Tag in the request. This field must
- be encoded 1*8ALPHA *("-" 1*8ALPHA).
-
-
-
-
-Guttman, et al. Standards Track [Page 18]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- If an option is specified, and not included in the message, the
- receiver MUST respond with a PARSE_ERROR.
-
-8.1. Service Request
-
- 0 1 2 3
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Service Location header (function = SrvRqst = 1) |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | length of <PRList> | <PRList> String \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | length of <service-type> | <service-type> String \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | length of <scope-list> | <scope-list> String \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | length of predicate string | Service Request <predicate> \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | length of <SLP SPI> string | <SLP SPI> String \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-
- In order for a Service to match a SrvRqst, it must belong to at least
- one requested scope, support the requested service type, and match
- the predicate. If the predicate is present, the language of the
- request (ignoring the dialect part of the Language Tag) must match
- the advertised service.
-
- <PRList> is the Previous Responder List. This <string-list> contains
- dotted decimal notation IP (v4) addresses, and is iteratively
- multicast to obtain all possible results (see Section 6.3). UAs
- SHOULD implement this discovery algorithm. SAs MUST use this to
- discover all available DAs in their scope, if they are not already
- configured with DA addresses by some other means.
-
- A SA silently drops all requests which include the SA's address in
- the <PRList>. An SA which has multiple network interfaces MUST check
- if any of the entries in the <PRList> equal any of its interfaces.
- An entry in the PRList which does not conform to an IPv4 dotted
- decimal address is ignored: The rest of the <PRList> is processed
- normally and an error is not returned.
-
- Once a <PRList> plus the request exceeds the path MTU, multicast
- convergence stops. This algorithm is not intended to find all
- instances; it finds 'enough' to provide useful results.
-
- The <scope-list> is a <string-list> of configured scope names. SAs
- and DAs which have been configured with any of the scopes in this
- list will respond. DAs and SAs MUST reply to unicast requests with a
-
-
-
-Guttman, et al. Standards Track [Page 19]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- SCOPE_NOT_SUPPORTED error if the <scope-list> is omitted or fails to
- include a scope they support (see Section 11). The only exceptions
- to this are described in Section 11.2.
-
- The <service-type> string is discussed in Section 4. Normally, a
- SrvRqst elicits a SrvRply. There are two exceptions: If the
- <service-type> is set to "service:directory-agent", DAs respond to
- the SrvRqst with a DAAdvert (see Section 8.5.) If set to
- "service:service-agent", SAs respond with a SAAdvert (see Section
- 8.6.) If this field is omitted, a PARSE_ERROR is returned - as this
- field is REQUIRED.
-
- The <predicate> is a LDAPv3 search filter [14]. This field is
- OPTIONAL. Services may be discovered simply by type and scope.
- Otherwise, services are discovered which satisfy the <predicate>. If
- present, it is compared to each registered service. If the attribute
- in the filter has been registered with multiple values, the filter is
- compared to each value and the results are ORed together, i.e.,
- "(x=3)" matches a registration of (x=1,2,3); "(!(Y=0))" matches
- (y=0,1) since Y can be nonzero. Note the matching is case
- insensitive. Keywords (i.e., attributes without values) are matched
- with a "presence" filter, as in "(keyword=*)".
-
- An incoming request term MUST have the same type as the attribute in
- a registration in order to match. Thus, "(x=33)" will not match '
- x=true', etc. while "(y=foo)" will match 'y=FOO'.
- "(|(x=33)(y=foo))" will be satisfied, even though "(x=33)" cannot be
- satisfied, because of the `|' (boolean disjunction).
-
- Wildcard matching MUST be done with the '=' filter. In any other
- case, a PARSE_ERROR is returned. Request terms which include
- wildcards are interpreted to be Strings. That is, (x=34*) would
- match 'x=34foo', but not 'x=3432' since the first value is a String
- while the second value is an Integer; Strings don't match Integers.
-
- Examples of Predicates follow. <t> indicates the service type of the
- SrvRqst, <s> gives the <scope-list> and <p> is the predicate string.
-
- <t>=service:http <s>=DEFAULT <p>= (empty string)
- This is a minimal request string. It matches all http
- services advertised with the default scope.
-
- <t>=service:pop3 <s>=SALES,DEFAULT <p>=(user=wump)
- This is a request for all pop3 services available in
- the SALES or DEFAULT scope which serve mail to the user
- `wump'.
-
-
-
-
-
-Guttman, et al. Standards Track [Page 20]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- <t>=service:backup <s>=BLDG 32 <p>=(&(q<=3)(speed>=1000))
- This returns the backup service which has a queue length
- less than 3 and a speed greater than 1000. It will
- return this only for services registered with the BLDG 32
- scope.
-
- <t>=service:directory-agent <s>=DEFAULT <p>=
- This returns DAAdverts for all DAs in the DEFAULT scope.
-
- DAs are discovered by sending a SrvRqst with the service type set to
- "service:directory-agent". If a predicate is included in the
- SrvRqst, the DA SHOULD respond only if the predicate can be satisfied
- with the DA's attributes. The <scope-list> MUST contain all scopes
- configured for the UA or SA which is discovering DAs.
-
- The <SLP SPI> string indicates a SLP SPI that the requester has been
- configured with. If this string is omitted, the responder does not
- include any Authentication Blocks in its reply. If it is included,
- the responder MUST return a reply which has an associated
- authentication block with the SLP SPI in the SrvRqst. If no replies
- may be returned because the SLP SPI is not supported, the responder
- returns an AUTHENTICATION_UNKNOWN error.
-
-8.2. Service Reply
-
- 0 1 2 3
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Service Location header (function = SrvRply = 2) |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Error Code | URL Entry count |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | <URL Entry 1> ... <URL Entry N> \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-
- The service reply contains zero or more URL entries (see Section
- 4.3). A service reply with zero URL entries MUST be returned in
- response to a unicast Service Request, if no matching URLs are
- present. A service reply with zero URL entries MUST NOT be sent in
- response to a multicast or broadcast service request (instead, if
- there was no match found or an error processing the request, the
- service reply should not be generated at all).
-
- If the reply overflows, the UA MAY simply use the first URL Entry in
- the list. A URL obtained by SLP may not be cached longer than
- Lifetime seconds, unless there is a URL Authenticator block present.
-
-
-
-
-
-Guttman, et al. Standards Track [Page 21]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- In that case, the cache lifetime is indicated by the Timestamp in the
- URL Authenticator (see Section 9.2).
-
- An authentication block is returned in the URL Entries, including the
- SLP SPI in the SrvRqst. If no SLP SPI was included in the request,
- no Authentication Blocks are returned in the reply. URL
- Authentication Blocks are defined in Section 9.2.1.
-
- If a SrvRply is sent by UDP, a URL Entry MUST NOT be included unless
- it fits entirely without truncation.
-
-8.3. Service Registration
-
- 0 1 2 3
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Service Location header (function = SrvReg = 3) |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | <URL-Entry> \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | length of service type string | <service-type> \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | length of <scope-list> | <scope-list> \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | length of attr-list string | <attr-list> \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- |# of AttrAuths |(if present) Attribute Authentication Blocks...\
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-
- The <entry> is a URL Entry (see section 4.3). The Lifetime defines
- how long a DA can cache the registration. SAs SHOULD reregister
- before this lifetime expires (but SHOULD NOT more often than once per
- second). The Lifetime MAY be set to any value between 0 and 0xffff
- (maximum, around 18 hours). Long-lived registrations remain stale
- longer if the service fails and the SA does not deregister the
- service.
-
- The <service-type> defines the service type of the URL to be
- registered, regardless of the scheme of the URL. The <scope-list>
- MUST contain the names of all scopes configured for the SA, which the
- DA it is registering with supports. The default value for the
- <scope-list> is "DEFAULT" (see Section 11).
-
- The SA MUST register consistently with all DAs. If a SA is
- configured with scopes X and Y and there are three DAs, whose scopes
- are "X", "Y" and "X,Y" respectively, the SA will register the with
- all three DAs in their respective scopes. All future updates and
- deregistrations of the service must be sent to the same set of DAs in
-
-
-
-Guttman, et al. Standards Track [Page 22]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- the same scopes the service was initially registered in.
-
- The <attr-list>, if present, specifies the attributes and values to
- be associated with the URL by the DA (see Section 5).
-
- A SA configured with the ability to sign service registrations MUST
- sign each of the URLs and Attribute Lists using each of the keys it
- is configured to use, and the DA it is registering with accepts.
- (The SA MUST acquire DAAdverts for all DAs it will register with to
- obtain the DA's SLP SPI list and attributes, as described in Section
- 8.5). The SA supplies a SLP SPI in each authentication block
- indicating the SLP SPI configuration required to verify the digital
- signature. The format of the digital signatures used is defined in
- section 9.2.1.
-
- Subsequent registrations of previously registered services MUST
- contain the same list of SLP SPIs as previous ones or else DAs will
- reject them, replying with an AUTHENTICATION_ABSENT error.
-
- A registration with the FRESH flag set will replace *entirely* any
- previous registration for the same URL in the same language. If the
- FRESH flag is not set, the registration is an "incremental"
- registration (see Section 9.3).
-
-8.4. Service Acknowledgment
-
- 0 1 2 3
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Service Location header (function = SrvAck = 5) |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Error Code |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-
- A DA returns a SrvAck to an SA after a SrvReg. It carries only a two
- byte Error Code (see Section 7).
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Guttman, et al. Standards Track [Page 23]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
-8.5. Directory Agent Advertisement
-
- 0 1 2 3
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Service Location header (function = DAAdvert = 8) |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Error Code | DA Stateless Boot Timestamp |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- |DA Stateless Boot Time,, contd.| Length of URL |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- \ URL \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Length of <scope-list> | <scope-list> \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Length of <attr-list> | <attr-list> \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Length of <SLP SPI List> | <SLP SPI List> String \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | # Auth Blocks | Authentication block (if any) \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-
- The Error Code is set to 0 when the DAAdvert is multicast. If the
- DAAdvert is being returned due to a unicast SrvRqst (ie. a request
- without the REQUEST MCAST flag set) the DA returns the same errors a
- SrvRply would.
-
- The <scope-list> of the SrvRqst must either be omitted or include a
- scope which the DA supports. The DA Stateless Boot Timestamp
- indicates the state of the DA (see section 12.1).
-
- The DA MAY include a list of its attributes in the DAAdvert. This
- list SHOULD be kept short, as the DAAdvert must fit into a datagram
- in order to be multicast.
-
- A potential scaling problem occurs in SLPv2 if SAs choose too low a
- Lifetime. In this case, an onerous amount of reregistration occurs
- as more services are deployed. SLPv2 allows DAs to control SAs
- frequency of registration. A DA MAY reissue a DAAdvert with a new
- set of attributes at any time, to change the reregistration behavior
- of SAs. These apply only to subsequent registrations; existing
- service registrations with the DA retain their registered lifetimes.
-
- If the DAAdvert includes the attribute "min-refresh-interval" it MUST
- be set to a single Integer value indicating a number of seconds. If
- this attribute is present SAs MUST NOT refresh any particular service
- advertisement more frequently than this value. If SrvReg with the
- FRESH FLAG not set or SrvDereg with a non-empty tag list updating a
-
-
-
-Guttman, et al. Standards Track [Page 24]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- particular service are received more often than the value for the
- DA's advertised "min-refresh-interval" attribute the DA SHOULD reject
- the message and return a REFRESH_REJECTED error in the SrvAck.
-
- The URL is "service:directory-agent://"<addr> of the DA, where <addr>
- is the dotted decimal numeric address of the DA. The <scope-list> of
- the DA MUST NOT be NULL.
-
- The SLP SPI List is the list of SPIs that the DA is capable of
- verifying. SAs MUST NOT register services with authentication blocks
- for those SLP SPIs which are not on the list. DAs will reject
- service registrations which they cannot verify, returning an
- AUTHENTICATION_UNKNOWN error.
-
- The format of DAAdvert signatures is defined in Section 9.2.1.
-
- The SLP SPI which is used to verify the DAAdvert is included in the
- Authentication Block. When DAAdverts are multicast, they may have to
- transmit multiple DAAdvert Authentication Blocks. If the DA is
- configured to be able to generate signatures for more than one SPI,
- the DA MUST include one Authentication Block for each SPI. If all
- these Authentication Blocks do not fit in a single datagram (to
- multicast or broadcast) the DA MUST send separate DAAdverts so that
- Authentication Blocks for all the SPIs the DA is capable of
- generating are sent.
-
- If the DAAdvert is being sent in response to a SrvRqst, the DAAdvert
- contains only the authentication block with the SLP SPI in the
- SrvRqst, if the DA is configured to be able to produce digital
- signatures using that SLP SPI. If the SrvRqst is unicast to the DA
- (the REQUEST MCAST flag in the header is not set) and an unsupported
- SLP SPI is included, the DA replies with a DAAdvert with the Error
- Code set to an AUTHENTICATION_UNKNOWN error.
-
- UAs SHOULD be configured with SLP SPIs that will allow them to verify
- DA Advertisements. If the UA is configured with SLP SPIs and
- receives a DAAdvert which fails to be verified using one of them, the
- UA MUST discard it.
-
-8.6. Service Agent Advertisement
-
- User Agents MUST NOT solicit SA Advertisements if they have been
- configured to use a particular DA, if they have been configured with
- a <scope-list> or if DAs have been discovered. UAs solicit SA
- Advertisements only when they are explicitly configured to use User
- Selectable scopes (see Section 11.2) in order to discover the scopes
- that SAs support. This allows UAs without scope configuration to
- make use of either DAs or SAs without any functional difference
-
-
-
-Guttman, et al. Standards Track [Page 25]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- except performance.
-
- A SA MAY be configured with attributes, and SHOULD support the
- attribute 'service-type' whose value is all the service types of
- services represented by the SA. SAs MUST NOT respond if the SrvRqst
- predicate is not satisfied. For example, only SAs offering 'nfs'
- services SHOULD respond with a SAAdvert to a SrvRqst for service type
- "service:service-agent" which includes a predicate "(service-
- type=nfs)".
-
- 0 1 2 3
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Service Location header (function = SAAdvert = 11) |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Length of URL | URL \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Length of <scope-list> | <scope-list> \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Length of <attr-list> | <attr-list> \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | # auth blocks | authentication block (if any) \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-
- The SA responds only to multicast SA discovery requests which either
- include no <scope-list> or a scope which they are configured to use.
-
- The SAAdvert MAY include a list of attributes the SA supports. This
- attribute list SHOULD be kept short so that the SAAdvert will not
- exceed the path MTU in size.
-
- The URL is "service:service-agent://"<addr> of the SA, where <addr>
- is the dotted decimal numeric address of the SA. The <scope-list> of
- the SA MUST NOT be null.
-
- The SAAdvert contains one SAAdvert Authentication block for each SLP
- SPI the SA can produce Authentication Blocks for. If the UA can
- verify the Authentication Block of the SAAdvert, and the SAAdvert
- fails to be verified, the UA MUST discard it.
-
-9. Optional Features
-
- The features described in this section are not mandatory. Some are
- useful for interactive use of SLP (where a user rather than a program
- will select services, using a browsing interface for example) and for
- scalability of SLP to larger networks.
-
-
-
-
-
-Guttman, et al. Standards Track [Page 26]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
-9.1. Service Location Protocol Extensions
-
- The format of a Service Location Extension is:
-
- 0 1 2 3
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Extension ID | Next Extension Offset |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Offset, contd.| Extension Data \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-
- Extension IDs are assigned in the following way:
-
- 0x0000-0x3FFF Standardized. Optional to implement. Ignore if
- unrecognized.
- 0x4000-0x7FFF Standardized. Mandatory to implement. A UA or SA
- which receives this option in a reply and does not understand
- it MUST silently discard the reply. A DA or SA which receives
- this option in a request and does not understand it MUST return
- an OPTION_NOT_UNDERSTOOD error.
- 0x8000-0x8FFF For private use (not standardized). Optional to
- implement. Ignore if unrecognized.
- 0x9000-0xFFFF Reserved.
-
- The three byte offset to next extension indicates the position of the
- next extension as offset from the beginning of the SLP message.
-
- The offset value is 0 if there are no extensions following the
- current extension.
-
- If the offset is 0, the length of the current Extension Data is
- determined by subtracting total length of the SLP message as given in
- the SLP message header minus the offset of the current extension.
-
- Extensions defined in this document are in Section D. See section 15
- for procedures that are required when specifying new SLP extensions.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Guttman, et al. Standards Track [Page 27]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
-9.2. Authentication Blocks
-
- 0 1 2 3
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Block Structure Descriptor | Authentication Block Length |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Timestamp |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | SLP SPI String Length | SLP SPI String \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Structured Authentication Block ... \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-
- Authentication blocks are returned with certain SLP messages to
- verify that the contents have not been modified, and have been
- transmitted by an authorized agent. The authentication data
- (contained in the Structured Authentication Block) is typically case
- sensitive. Even though SLP registration data (e.g., attribute
- values) are typically are not case sensitive, the case of the
- registration data has to be preserved by the registering DA so that
- UAs will be able to verify the data used for calculating digital
- signature data.
-
- The Block Structure Descriptor (BSD) identifies the format of the
- Authenticator which follows. BSDs 0x0000-0x7FFF will be maintained
- by IANA. BSDs 0x8000-0x8FFF are for private use.
-
- The Authentication Block Length is the length of the entire block,
- starting with the BSD.
-
- The Timestamp is the time that the authenticator expires (to prevent
- replay attacks.) The Timestamp is a 32-bit unsigned fixed-point
- number of seconds relative to 0h on 1 January 1970. SAs use this
- value to indicate when the validity of the digital signature expires.
- This Timestamp will wrap back to 0 in the year 2106. Once the value
- of the Timestamp wraps, the time at which the Timestamp is relative
- to resets. For example, after 06h28 and 16 seconds 5 February 2106,
- all Timestamp values will be relative to that epoch date.
-
- The SLP Security Parameters Index (SPI) string identifies the key
- length, algorithm parameters and keying material to be used by agents
- to verify the signature data in the Structured Authentication Block.
- The SLP SPI string has the same grammar as the <scope-val> defined in
- Section 6.4.1.
-
- Reserved characters in SLP SPI strings must be escaped using the same
- convention as used throughout SLPv2.
-
-
-
-Guttman, et al. Standards Track [Page 28]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- SLP SPIs deployed in a site MUST be unique. An SLP SPI used for
- BSD=0x0002 must not be the same as used for some other BSD.
-
- All SLP agents MUST implement DSA [20] (BSD=0x0002). SAs MUST
- register services with DSA authentication blocks, and they MAY
- register them with other authentication blocks using other
- algorithms. SAs MUST use DSA authentication blocks in SrvDeReg
- messages and DAs MUST use DSA authentication blocks in unsolicited
- DAAdverts.
-
-9.2.1. SLP Message Authentication Rules
-
- The sections below define how to calculate the value to apply to the
- algorithm identified by the BSD value. The components listed are
- used as if they were a contiguous single byte aligned buffer in the
- order given.
-
- URL
- 16-bit Length of SLP SPI String, SLP SPI String.
- 16-bit Length of URL, URL,
- 32-bit Timestamp.
-
- Attribute List
- 16-bit Length of SLP SPI String, SLP SPI String,
- 16-bit length of <attr-list>, <attr-list>,
- 32-bit Timestamp.
-
- DAAdvert
- 16-bit Length of SLP SPI String, SLP SPI String,
- 32-bit DA Stateless Boot Timestamp,
- 16-bit Length of URL, URL,
- 16-bit Length of <attr-list>, <attr-list>,
- 16-bit Length of DA's <scope-list>, DA's <scope-list>,
- 16-bit Length of DA's <SLP SPI List>, DA's <SLP SPI List>,
- 32-bit Timestamp.
-
- The first SLP SPI is the SLP SPI in the Authentication
- Block. This SLP SPI indicates the keying material and other
- parameters to use to verify the DAAdvert. The SLP SPI List is
- the list of SLP SPIs the DA itself supports, and is able to
- verify.
-
- SAAdvert
- 16-bit Length of SLP SPI String, SLP SPI String,
- 16-bit Length of URL, URL,
- 16-bit Length of <attr-list>, <attr-list>,
- 16-bit Length of <scope-list>, <scope-list>,
- 32-bit Timestamp.
-
-
-
-Guttman, et al. Standards Track [Page 29]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
-9.2.2 DSA with SHA-1 in Authentication Blocks
-
- BSD=0x0002 is defined to be DSA with SHA-1. The signature
- calculation is defined by [20]. The signature format conforms to
- that in the X.509 v3 certificate:
-
- 1. The signature algorithm identifier (an OID)
- 2. The signature value (an octet string)
- 3. The certificate path.
-
- All data is represented in ASN.1 encoding:
-
- id-dsa-with-sha1 ID ::= {
- iso(1) member-body(2) us(840) x9-57 (10040)
- x9cm(4) 3 }
-
- i.e., the ASN.1 encoding of 1.2.840.10040.4.3 followed immediately
- by:
-
- Dss-Sig-Value ::= SEQUENCE {
- r INTEGER,
- s INTEGER }
-
- i.e., the binary ASN.1 encoding of r and s computed using DSA and
- SHA-1. This is followed by a certificate path, as defined by X.509
- [10], [2], [3], [4], [5].
-
- Authentication Blocks for BSD=0x0002 have the following format. In
- the future, BSDs may be assigned which have different formats.
-
- 0 1 2 3
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | ASN.1 encoded DSA signature \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-
-9.3. Incremental Service Registration
-
- Incremental registrations update attribute values for a previously
- registered service. Incremental service registrations are useful
- when only a single attribute has changed, for instance. In an
- incremental registration, the FRESH flag in the SrvReg header is NOT
- set.
-
- The new registration's attributes replace the previous
- registration's, but do not affect attributes which were included
- previously and are not present in the update.
-
-
-
-
-Guttman, et al. Standards Track [Page 30]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- For example, suppose service:x://a.org has been registered with
- attributes A=1, B=2, C=3. If an incremental registration comes for
- service:x://a.org with attributes C=30, D=40, then the attributes for
- the service after the update are A=1, B=2, C=30, D=40.
-
- Incremental registrations MUST NOT be performed for services
- registered with Authentication Blocks. These must be registered with
- ALL attributes, with the FRESH flag in the SrvReg header set. DAs
- which receive such registration messages return an
- AUTHENTICATION_FAILED error.
-
- If the FRESH flag is not set and the DA does not have a prior
- registration for the service, the incremental registration fails with
- error code INVALID_UPDATE.
-
- The SA MUST use the same <scope-list> in an update message as was
- used in the prior registration. If this is not done, the DA returns
- a SCOPE_NOT_SUPPORTED error. In order to change the scope of a
- service advertisement it MUST be deregistered first and reregistered
- with a new <scope-list>.
-
- The SA MUST use the same <service-type> in an update message as was
- used in a prior registration of the same URL. If this is not done,
- the DA returns an INVALID_UPDATE error.
-
-9.4. Tag Lists
-
- Tag lists are used in SrvDeReg and AttrReq messages. The syntax of a
- <tag-list> item is:
-
- tag-filter = simple-tag / substring
- simple-tag = 1*filt-char
- substring = [initial] any [final]
- initial = 1*filt-char
- any = `*' *(filt-char `*')
- final = 1*filt-char
- filt-char = Any character excluding <reserved> and <bad-tag> (see
- grammar in Section 5).
-
- Wild card characters in a <tag-list> item match arbitrary sequences
- of characters. For instance "*bob*" matches "some bob I know",
- "bigbob", "bobby" and "bob".
-
-
-
-
-
-
-
-
-
-Guttman, et al. Standards Track [Page 31]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
-10. Optional SLP Messages
-
- The additional requests provide features for user interaction and for
- efficient updating of service advertisements with dynamic attributes.
-
-10.1. Service Type Request
-
- The Service Type Request (SrvTypeRqst) allows a UA to discover all
- types of service on a network. This is useful for general purpose
- service browsers.
-
- 0 1 2 3
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Service Location header (function = SrvTypeRqst = 9) |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | length of PRList | <PRList> String \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | length of Naming Authority | <Naming Authority String> \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | length of <scope-list> | <scope-list> String \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-
- The <PRList> list and <scope-list> are interpreted as in Section 8.1.
-
- The Naming Authority string, if present in the request, will limit
- the reply to Service Type strings with the specified Naming
- Authority. If the Naming Authority string is absent, the IANA
- registered service types will be returned. If the length of the
- Naming Authority is set to 0xFFFF, the Naming Authority string is
- omitted and ALL Service Types are returned, regardless of Naming
- Authority.
-
-10.2. Service Type Reply
-
- 0 1 2 3
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Service Location header (function = SrvTypeRply = 10) |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Error Code | length of <srvType-list> |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | <srvtype--list> \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-
- The service-type Strings (as described in Section 4.1) are provided
- in <srvtype-list>, which is a <string-list>.
-
-
-
-
-Guttman, et al. Standards Track [Page 32]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- If a service type has a Naming Authority other than IANA it MUST be
- returned following the service type string and a `.' character.
- Service types with the IANA Naming Authority do not include a Naming
- Authority string.
-
-10.3. Attribute Request
-
- The Attribute Request (AttrRqst) allows a UA to discover attributes
- of a given service (by supplying its URL) or for an entire service
- type. The latter feature allows the UA to construct a query for an
- available service by selecting desired features. The UA may request
- that all attributes are returned, or only a subset of them.
-
- 0 1 2 3
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Service Location header (function = AttrRqst = 6) |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | length of PRList | <PRList> String \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | length of URL | URL \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | length of <scope-list> | <scope-list> string \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | length of <tag-list> string | <tag-list> string \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | length of <SLP SPI> string | <SLP SPI> string \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-
- The <PRList>, <scope-list> and <SLP SPI> string are interpreted as in
- Section 8.1.
-
- The URL field can take two forms. It can simply be a Service Type
- (see Section 4.1), such as "http" or "service:tftp". In this case,
- all attributes and the full range of values for each attribute of all
- services of the given Service Type is returned.
-
- The URL field may alternatively be a full URL, such as
- "service:printer:lpr://igore.wco.ftp.com:515/draft" or
- "nfs://max.net/znoo". In this, only the registered attributes for
- the specified URL are returned.
-
- The <tag-list> field is a <string-list> of attribute tags, as defined
- in Section 9.4 which indicates the attributes to return in the
- AttrRply. If <tag-list> is omitted, all attributes are returned.
- <tag-list> MUST be omitted and a full URL MUST be included when
- attributes when a SLP SPI List string is included, otherwise the DA
- will reply with an AUTHENTICATION_FAILED error.
-
-
-
-Guttman, et al. Standards Track [Page 33]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
-10.4. Attribute Reply
-
- 0 1 2 3
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Service Location header (function = AttrRply = 7) |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Error Code | length of <attr-list> |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | <attr-list> \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- |# of AttrAuths | Attribute Authentication Block (if present) \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-
- The format of the <attr-list> and the Authentication Block is as
- specified for SrvReg (see Section 9.2.1).
-
- Attribute replies SHOULD be returned with the original case of the
- string registration intact, as they are likely to be human readable.
- In the case where the AttrRqst was by service type, all attributes
- defined for the service type, and all their values are returned.
-
- Although white space is folded for string matching, attribute tags
- and values MUST be returned with their original white space
- preserved.
-
- Only one copy of each attribute tag or String value should be
- returned, arbitrarily choosing one version (with respect to upper and
- lower case and white space internal to the strings): Duplicate
- attributes and values SHOULD be removed. An arbitrary version of the
- string value and tag name is chosen for the merge. For example:
- "(A=a a,b)" merged with "(a=A A,B)" may yield "(a=a a,B)".
-
-10.5. Attribute Request/Reply Examples
-
- Suppose that printer services have been registered as follows:
-
- Registered Service:
- URL = service:printer:lpr://igore.wco.ftp.com/draft
- scope-list = Development
- Lang. Tag = en
- Attributes = (Name=Igore),(Description=For developers only),
- (Protocol=LPR),(location-description=12th floor),
- (Operator=James Dornan \3cdornan@monster\3e),
- (media-size=na-letter),(resolution=res-600),x-OK
-
- URL = service:printer:lpr://igore.wco.ftp.com/draft
- scope-list = Development
-
-
-
-Guttman, et al. Standards Track [Page 34]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- Lang. Tag = de
- Attributes = (Name=Igore),(Description=Nur fuer Entwickler),
- (Protocol=LPR),(location-description=13te Etage),
- (Operator=James Dornan \3cdornan@monster\3e),
- (media-size=na-letter),(resolution=res-600),x-OK
-
- URL = service:printer:http://not.wco.ftp.com/cgi-bin/pub-prn
- scope-list = Development
- Lang. Tag = en
- Attributes = (Name=Not),(Description=Experimental IPP printer),
- (Protocol=http),(location-description=QA bench),
- (media-size=na-letter),(resolution=other),x-BUSY
-
- Notice the first printer, "Igore" is registered in both English and
- German. The `<' and `>' characters in the Operator attribute value
- which are part of the Email address had to be escaped, as they are
- reserved characters for values.
-
- Attribute tags are not translated, though attribute values may be,
- see [13].
-
- The attribute Request:
-
- URL = service:printer:lpr://igore.wco.ftp.com/draft
- scope-list = Development
- Lang. Tag = de
- tag-list = resolution,loc*
-
- receives the Attribute Reply:
-
- (location-description=13te Etage),(resolution=res-600)
-
- The attribute Request:
-
- URL = service:printer
- scope-list = Development
- Lang. Tag = en
- tag-list = x-*,resolution,protocol
-
- receives an Attribute Reply containing:
-
- (protocols=http,LPR),(resolution=res-600,other),x-OK,x-BUSY
-
- The first request is by service instance and returns the requested
- values, in German. The second request is by abstract service type
- (see Section 4) and returns values from both "Igore" and "Not".
-
-
-
-
-
-Guttman, et al. Standards Track [Page 35]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- An attribute Authentication Block is returned if an authentication
- block with the SLP SPI in the AttrRqst can be returned. Note that
- the <attr-list> returned from a DA with an Authentication Block MUST
- be identical to the <attr-list> registered by a SA, in order for the
- authentication verification calculations to be possible.
-
- A SA or DA only returns an Attribute Authentication Block if the
- AttrRqst included a full URL in the request and no tag list.
-
- If an SLP SPI is specified in a unicast request (the REQUEST MCAST
- flag in the header is not set) and the SA or DA cannot return an
- Authentication Block with that SLP SPI, an AUTHENTICATION_UNKNOWN
- error is returned. The # of Attr Auths field is set to 0 if there no
- Authentication Block is included, or 1 if an Authentication Block
- follows.
-
-10.6. Service Deregistration
-
- A DA deletes a service registration when its Lifetime expires.
- Services SHOULD be deregistered when they are no longer available,
- rather than leaving the registrations to time out.
-
- 0 1 2 3
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Service Location header (function = SrvDeReg = 4) |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Length of <scope-list> | <scope-list> \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | URL Entry \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Length of <tag-list> | <tag-list> \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-
- The <scope-list> is a <string-list> (see section 2.1).
-
- The SA MUST retry if there is no response from the DA, see Section
- 12.3. The DA acknowledges a SrvDeReg with a SrvAck. Once the SA
- receives an acknowledgment indicating success, the service and/or
- attributes are no longer advertised by the DA. The DA deregisters the
- service or service attributes from every scope specified in the
- SrvDeReg which it was previously registered in.
-
- The SA MUST deregister all services with the same scope list used to
- register the service with a DA. If this is not done in the SrvDeReg
- message, the DA returns a SCOPE_NOT_SUPPORTED error. The Lifetime
- field in the URL Entry is ignored for the purposes of the SrvDeReg.
-
-
-
-
-Guttman, et al. Standards Track [Page 36]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- The <tag-list> is a <string-list> of attribute tags to deregister as
- defined in Section 9.4. If no <tag-list> is present, the SrvDeReg
- deregisters the service in all languages it has been registered in.
- If the <tag-list> is present, the SrvDeReg deregisters the attributes
- whose tags are listed in the tag spec. Services registered with
- Authentication Blocks MUST NOT include a <tag-list> in a SrvDeReg
- message: A DA will respond with an AUTHENTICATION_FAILED error in
- this case.
-
- If the service to be deregistered was registered with an
- authentication block or blocks, a URL authentication block for each
- of the SLP SPIs registered must be included in the SrvDeReg.
- Otherwise, the DA returns an AUTHENTICATION_ABSENT error. If the
- message fails to be verified by the DA, an AUTHENTICATION_FAILED
- error is returned by the DA.
-
-11. Scopes
-
- Scopes are sets of services. The primary use of Scopes is to provide
- the ability to create administrative groupings of services. A set of
- services may be assigned a scope by network administrators. A client
- seeking services is configured to use one or more scopes. The user
- will only discover those services which have been configured for him
- or her to use. By configuring UAs and SAs with scopes,
- administrators may provision services. Scopes strings are case
- insensitive. The default SCOPE string is "DEFAULT".
-
- Scopes are the primary means an administrator has to scale SLP
- deployments to larger networks. When DAs with NON-DEFAULT scopes are
- present on the network, further gains can be had by configuring UAs
- and SAs to have a predefined non-default scope. These agents can
- then perform DA discovery and make requests using their scope. This
- will limit the number of replies.
-
-11.1. Scope Rules
-
- SLP messages which fail to contain a scope that the receiving Agent
- is configured to use are dropped (if the request was multicast) or a
- SCOPE_NOT_SUPPORTED error is returned (if the request was unicast).
- Every SrvRqst (except for DA and SA discovery requests), SrvReg,
- AttrRqst, SrvTypeRqst, DAAdvert, and SAAdvert message MUST include a
- <scope-list>.
-
- A UA MUST unicast its SLP messages to a DA which supports the desired
- scope, in preference to multicasting a request to SAs. A UA MAY
- multicast the request if no DA is available in the scope it is
- configured to use.
-
-
-
-
-Guttman, et al. Standards Track [Page 37]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
-11.2. Administrative and User Selectable Scopes
-
- All requests and services are scoped. The two exceptions are
- SrvRqsts for "service:directory-agent" and "service:service-agent".
- These MAY have a zero-length <scope-list> when used to enable the
- user to make scope selections. In this case UAs obtain their scope
- list from DAAdverts (or if DAs are not available, from SAAdverts.)
-
- Otherwise, if SAs and UAs are to use any scope other than the default
- (i.e., "DEFAULT"), the UAs and SAs are configured with lists of
- scopes to use by system administrators, perhaps automatically by way
- of DHCP option 78 or 79 [21]. Such administrative scoping allows
- services to be provisioned, so that users will only see services they
- are intended to see.
-
- User configurable scopes allow a user to discover any service, but
- require them to do their own selection of scope. This is similar to
- the way AppleTalk [12] and SMB [19] networking allow user selection
- of AppleTalk Zone or workgroups.
-
- Note that the two configuration choices are not compatible. One
- model allows administrators control over service provision. The
- other delegates this to users (who may not be prepared to do any
- configuration of their system).
-
-12. Directory Agents
-
- DAs cache service location and attribute information. They exist to
- enhance the performance and scalability of SLP. Multiple DAs provide
- further scalability and robustness of operation, since they can each
- store service information for the same SAs, in case one of the DAs
- fails.
-
- A DA provides a centralized store for service information. This is
- useful in a network with several subnets or with many SLP Agents.
- The DA address can be dynamically configured with UAs and SAs using
- DHCP, or by using static configuration.
-
- SAs configured to use DAs with DHCP or static configuration MUST
- unicast a SrvRqst to the DA, when the SA is initialized. The SrvRqst
- omits the scope list and sets the service type of the request to
- "service:directory-agent". The DA will return a DAAdvert with its
- attributes, SLP SPI list, and other parameters which are essential
- for proper SA to DA communication.
-
- Passive detection of DAs by SAs enables services to be advertised
- consistently among DAs of the same scope. Advertisements expire if
- not renewed, leaving only transient stale registrations in DAs, even
-
-
-
-Guttman, et al. Standards Track [Page 38]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- in the case of a failure of a SA.
-
- A single DA can support many UAs. UAs send the same requests to DAs
- that they would send to SAs and expect the same results. DAs reduce
- the load on SAs, making simpler implementations of SAs possible.
-
- UAs MUST be prepared for the possibility that the service information
- they obtain from DAs is stale.
-
-12.1. Directory Agent Rules
-
- When DAs are present, each SA MUST register its services with DAs
- that support one or more of its scope(s).
-
- UAs MUST unicast requests directly to a DA (when scoping rules
- allow), hence avoiding using the multicast convergence algorithm, to
- obtain service information. This decreases network utilization and
- increases the speed at which UAs can obtain service information.
-
- DAs MUST flush service advertisements once their lifetime expires or
- their URL Authentication Block "Timestamp" of expiration is past.
-
- DAAdverts MUST include DA Stateless Boot Timestamp, in the same
- format as the Authentication Block (see Section 9.2). The Timestamp
- in the Authentication Block indicates the time at which all previous
- registrations were lost (i.e., the last stateless reboot). The
- Timestamp is set to 0 in a DAAdvert to notify UAs and SAs that the DA
- is going down. DAs MUST NOT use equal or lesser Boot Timestamps to
- previous ones, if they go down and restart without service
- registration state. This would mislead SAs to not reregister with
- the DA.
-
- DAs which receive a multicast SrvRqst for the service type
- "service:directory-agent" MUST silently discard it if the <scope-
- list> is (a) not omitted and (b) does not include a scope they are
- configured to use. Otherwise the DA MUST respond with a DAAdvert.
-
- DAs MUST respond to AttrRqst and SrvTypeRqst messages (these are
- OPTIONAL only for SAs, not DAs.)
-
-12.2. Directory Agent Discovery
-
- UAs can discover DAs using static configuration, DHCP options 78 and
- 79, or by multicasting (or broadcasting) Service Requests using the
- convergence algorithm in Section 6.3.
-
-
-
-
-
-
-Guttman, et al. Standards Track [Page 39]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- See Section 6 regarding unsolicited DAAdverts. Section 12.2.2
- describes how SAs may reduce the number of times they must reregister
- with DAs in response to unsolicited DAAdverts.
-
- DAs MUST send unsolicited DAAdverts once per CONFIG_DA_BEAT. An
- unsolicited DAAdvert has an XID of 0. SAs MUST listen for DAAdverts,
- passively, as described in Section 8.5. UAs MAY do this. If they do
- not listen for unsolicited DAAdverts, however, they will not discover
- DAs as they become available. UAs SHOULD, in this case, do periodic
- active DA discovery, see Section 6.
-
- A URL with the scheme "service:directory-agent" indicates the DA's
- location as defined in Section 8.5. For example:
- "service:directory-agent://foobawooba.org".
-
- The following sections suggest timing algorithms which enhance the
- scalability of SLP.
-
-12.2.1. Active DA Discovery
-
- After a UA or SA restarts, its initial DA discovery request SHOULD be
- delayed for some random time uniformly distributed from 0 to
- CONFIG_START_WAIT seconds.
-
- The UA or SA sends the DA Discovery request using a SrvRqst, as
- described in Section 8.1. DA Discovery requests MUST include a
- Previous Responder List. SrvRqsts for Active DA Discovery SHOULD NOT
- be sent more than once per CONFIG_DA_FIND seconds.
-
- After discovering a new DA, a SA MUST wait a random time between 0
- and CONFIG_REG_ACTIVE seconds before registering their services.
-
-12.2.2. Passive DA Advertising
-
- A DA MUST multicast (or broadcast) an unsolicited DAAdvert every
- CONFIG_DA_BEAT seconds. CONFIG_DA_BEAT SHOULD be specified to
- prevent DAAdverts from using more than 1% of the available bandwidth.
-
- All UAs and SAs which receive the unsolicited DAAdvert SHOULD examine
- its DA stateless Boot Timestamp. If it is set to 0, the DA is going
- down and no further messages should be sent to it.
-
- If a SA detects a DA it has never encountered (with a nonzero
- timestamp,) the SA must register with it. SAs MUST examine the
- DAAdvert's timestamp to determine if the DA has had a stateless
- reboot since the SA last registered with it. If so it registers with
- the DA. SAs MUST wait a random interval between 0 and
- CONFIG_REG_PASSIVE before beginning DA registration.
-
-
-
-Guttman, et al. Standards Track [Page 40]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
-12.3. Reliable Unicast to DAs and SAs
-
- If a DA or SA fails to respond to a unicast UDP message in
- CONFIG_RETRY seconds, the message should be retried. The wait
- interval for each subsequent retransmission MUST exponentially
- increase, doubling each time. If a DA or SA fails to respond after
- CONFIG_RETRY_MAX seconds, the sender should consider the receiver to
- have gone down. The UA should use a different DA. If no such DA
- responds, DA discovery should be used to find a new DA. If no DA is
- available, multicast requests to SAs are used.
-
-12.4. DA Scope Configuration
-
- By default, DAs are configured with the "DEFAULT" scope.
- Administrators may add other configured scopes, in order to support
- UAs and SAs in non default scopes. The default configuration MUST
- NOT be removed from the DA unless:
-
- - There are other DAs which support the "DEFAULT" scope, or
-
- - All UAs and SAs have been configured with non-default scopes.
-
- Non-default scopes can be phased-in as the SLP deployment grows.
- Default scopes should be phased out only when the non-default scopes
- are universally configured.
-
- If a DA and SA are coresident on a host (quite possibly implemented
- by the same process), configuration of the host is considerably
- simplified if the SA supports only scopes also supported by the DA.
- That is, the SA SHOULD NOT advertise services in any scopes which are
- not supported by the coresident DA. This means that incoming requests
- can be answered by a single data store; the SA and DA registrations
- do not need to be kept separately.
-
-12.5. DAs and Authentication Blocks
-
- DAs are not configured to sign service registrations or attribute
- lists. They simply cache services registered by Service Agents. DAs
- MUST NOT accept registrations including authentication blocks for SLP
- SPIs which it is not configured with, see Section 8.5.
-
- A DA protects registrations which are made with authentication blocks
- using SLP SPIs it is configured to use. If a service S is
- registered, a subsequent registration (which will replace the
- adertisement) or a deregistration (which will remove it) MUST include
- an Authentication Block with the corresponding SLP SPI, see Section
- 8.3 and Section 10.6.
-
-
-
-
-Guttman, et al. Standards Track [Page 41]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- Example:
-
- A DA is configured to be able to verify Authentication Blocks with
- SLP SPIs "X,Y", that is X and Y.
-
- An SA registers a service with an Authentication Block with SPI "Z".
- The DA stores the registration, but discards the Authentication
- Block. If a UA requests a service with an SLP SPI string "Z", the DA
- will respond with an AUTHENTICATION_UNKNOWN error.
-
- An SA registers a service S with Authentication Blocks including SLP
- SPIs "X" and "Y". If a UA requests a service with an SLP SPI string
- "X" the DA will be able to return S (if the service type, language,
- scope and predicate of the SrvRqst match S) The DA will also return
- the Authentication Block with SLP SPI set to "X". If the DA receives
- a subsequent SrvDeReg for S (which will remove the advertisement) or
- a subsequent SrvReg for S (which will replace it), the message must
- include two URL Authentication Blocks, one each for SPIs "X" and "Y".
- If either of these were absent, the DA would return an
- AUTHENTICATION_ABSENT error.
-
-13. Protocol Timing Defaults
-
-Interval name Section Default Value Meaning
-------------------- ------- ------------- ------------------------
-CONFIG_MC_MAX 6.3 15 seconds Max time to wait for a
- complete multicast query
- response (all values.)
-CONFIG_START_WAIT 12.2.1 3 seconds Wait to perform DA
- discovery on reboot.
-CONFIG_RETRY 12.3 2 seconds Wait interval before
- initial retransmission
- of multicast or unicast
- requests.
-CONFIG_RETRY_MAX 12.3 15 seconds Give up on unicast
- request retransmission.
-CONFIG_DA_BEAT 12.2.2 3 hours DA Heartbeat, so that SAs
- passively detect new DAs.
-CONFIG_DA_FIND 12.3 900 seconds Minimum interval to wait
- before repeating Active
- DA discovery.
-CONFIG_REG_PASSIVE 12.2 1-3 seconds Wait to register services
- on passive DA discovery.
-CONFIG_REG_ACTIVE 8.3 1-3 seconds Wait to register services
- on active DA discovery.
-CONFIG_CLOSE_CONN 6.2 5 minutes DAs and SAs close idle
- connections.
-
-
-
-
-Guttman, et al. Standards Track [Page 42]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
-14. Optional Configuration
-
- Broadcast Only
- Any SLP agent SHOULD be configurable to use broadcast
- only. See Sections 6.1 and 12.2.
-
- Predefined DA
- A UA or SA SHOULD be configurable to use a predefined DA.
-
- No DA Discovery
- The UA or SA SHOULD be configurable to ONLY use
- predefined and DHCP-configured DAs and perform no active
- or passive DA discovery.
-
- Multicast TTL
- The default multicast TTL is 255. Agents SHOULD be
- configurable to use other values. A lower value will
- focus the multicast convergence algorithm on smaller
- subnetworks, decreasing the number of responses and
- increases the performance of service location. This
- may result in UAs obtaining different results for the
- identical requests depending on where they are connected
- to the network.
-
- Timing Values
- Time values other than the default MAY be configurable.
- See Section 13.
-
- Scopes
- A UA MAY be configurable to support User Selectable
- scopes by omitting all predefined scopes. See
- Section 11.2. A UA or SA MUST be configurable to use
- specific scopes by default. Additionally, a UA or SA
- MUST be configurable to use specific scopes for requests
- for and registrations of specific service types. The
- scope or scopes of a DA MUST be configurable. The
- default value for a DA is to have the scope "DEFAULT" if
- not otherwise configured.
-
- DHCP Configuration
- DHCP options 78 and 79 may be used to configure SLP. If
- DA locations are configured using DHCP, these SHOULD
- be used in preference to DAs discovered actively or
- passively. One or more of the scopes configured using
- DHCP MUST be used in requests. The entire configured
- <scope-list> MUST be used in registration and DA
- configuration messages.
-
-
-
-
-Guttman, et al. Standards Track [Page 43]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- Service Template
- UAs and SAs MAY be configured by using Service Templates.
- Besides simplifying the specification of attribute
- values, this also allows them to enforce the inclusion
- of 'required' attributes in SrvRqst, SrvReg and SrvDeReg
- messages. DAs MAY be configured with templates to
- allow them to WARN UAs and SAs in these cases. See
- Section 10.4.
-
- SLP SPI for service discovery
- Agents SHOULD be configurable to support SLP SPIs using
- the following parameters: BSD=2 (DSA with SHA-1) and
- a public key identified by the SLP SPI String. In
- the future, when a Public Key Infrastructure exists,
- SLP Agents may be able to obtain public keys and
- cryptographic parameters corresponding to the names used
- in SLP SPI Strings.
-
- Note that if the SLP SPI string chosen is identical
- to a scope string, it is effectively the same as a
- Protected Scope in SLPv1. Namely, every SA advertising
- in that scope would be configured with the same Private
- Key. Every DA and UA of that scope would be configured
- with the appropriate Public Key to verify signatures
- produced by those SAs. This is a convenient way to
- configure SLP deployments in the absence of a Public Key
- Infrastructure. Currently, it would be too difficult to
- manage the keying of UAs and DAs if each SA had its own
- key.
-
- SLP SPI for Directory Agent discovery
- Agents SHOULD be configurable to support SLP SPIs as
- above, to be used when discovering DAs. This SPI SHOULD
- be sent in SrvRqsts to discover DAs and be used to verify
- multicast DAAdvert messages.
-
- SA and DA Private Key
- SAs and DAs which can generate digital signatures require
- a Private Key and a corresponding SLP SPI indentifier
- to include in the Authentication Block. The SLP SPI
- identifies the Public Key to use to verify the digital
- signature in the Authentication Block.
-
-15. IANA Considerations
-
- SLP includes four sets of identifiers which may be registered with
- IANA. The policies for these registrations (See [18]) are noted in
- each case.
-
-
-
-Guttman, et al. Standards Track [Page 44]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- The Block Structure Descriptor (BSD) identifies the format of the
- Authenticator which follows. BSDs 0x8000-0x8FFF are for Private Use.
-
- Further Block Structured Descriptor (BSD) values, from the range
- 0x0003-0x7FFF may be standardized in the future by submitting a
- document which describes:
-
- - The data format of the Structured Authenticator block.
-
- - Which cryptographic algorithm to use (including a reference
- to a technical specification of the algorithm.)
-
- - The format of any keying material required for
- preconfiguring UAs, DAs and SAs. Also include any
- considerations regarding key distribution.
-
- - Security considerations to alert others to the strengths and
- weaknesses of the approach.
-
- The IANA will assign Cryptographic BSD numbers on the basis of IETF
- Consenus.
-
- New function-IDs, in the range 12-255, may be standardized by the
- method of IETF Consensus.
-
- New SLP Extensions with types in the range 2-65535 may be registered
- following review by a Designated Expert.
-
- New error numbers in the range 15-65535 are assigned on the basis of
- a Standards Action.
-
- Protocol elements used with Service Location Protocol may also
- require IANA registration actions. SLP is used in conjunction with
- "service:" URLs and Service Templates [13]. These are standardized
- by review of a Designated Expert and a mailing list (See [13].)
-
-16. Internationalization Considerations
-
- SLP messages support the use of multiple languages by providing a
- Language Tag field in the common message header (see Section 8).
-
- Services MAY be registered in multiple languages. This provides
- attributes so that users with different language skills may select
- services interactively.
-
- Attribute tags are not translated. Attribute values may be
- translated unless the Service Template [13] defines the attribute
- values to be 'literal'.
-
-
-
-Guttman, et al. Standards Track [Page 45]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- A service which is registered in multiple languages may be queried in
- multiple languages. The language of the SrvRqst or AttrRqst is used
- to satisfy the request. If the requested language is not supported,
- a LANGUAGE_NOT_SUPPORTED error is returned. SrvRply and AttrRply
- messages are always in the same language of the request.
-
- A DA or SA MAY be configured with translations of Service Templates
- [13] for the same service type. This will allow the DA or SA to
- translate a request (say in Italian) to the language of the service
- advertisement (say in English) and then translate the reply back to
- Italian. Similarly, a UA MAY use templates to translate outgoing
- requests and incoming replies.
-
- The dialect field in the Language Tag MAY be used: Requests which
- can be fulfilled by matching a language and dialect will be preferred
- to those which match only the language portion. Otherwise, dialects
- have no effect on matching requests.
-
-17. Security Considerations
-
- SLP provides for authentication of service URLs and service
- attributes. This provides UAs and DAs with knowledge of the
- integrity of service URLs and attributes included in SLP messages.
- The only systems which can generate digital signatures are those
- which have been configured by administrators in advance. Agents
- which verify signed data may assume it is 'trustworthy' inasmuch as
- administrators have ensured the cryptographic keying of SAs and DAs
- reflects 'trustworthiness.'
-
- Service Location does not provide confidentiality. Because the
- objective of this protocol is to advertise services to a community of
- users, confidentiality might not generally be needed when this
- protocol is used in non-sensitive environments. Specialized schemes
- might be able to provide confidentiality, if needed in the future.
- Sites requiring confidentiality should implement the IP Encapsulating
- Security Payload (ESP) [3] to provide confidentiality for Service
- Location messages.
-
- If Agents are not configured to generate Authentication Blocks and
- Agents are not configured to verify them, an adversary might easily
- use this protocol to advertise services on servers controlled by the
- adversary and thereby gain access to users' private information.
- Further, an adversary using this protocol will find it much easier to
- engage in selective denial of service attacks. Sites that are in
- potentially hostile environments (e.g., are directly connected to the
- Internet) should consider the advantages of distributing keys
- associated with SLP SPIs prior to deploying the sensitive directory
- agents or service agents.
-
-
-
-Guttman, et al. Standards Track [Page 46]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- SLP is useful as a bootstrap protocol. It may be used in
- environments in which no preconfiguration is possible. In such
- situations, a certain amount of "blind faith" is required: Without
- any prior configuration it is impossible to use any of the security
- mechanisms described above. SLP will make use of the mechanisms
- provided by the Security Area of the IETF for key distribution as
- they become available. At this point it would only be possible to
- gain the benefits associated with the use of Authentication Blocks if
- cryptographic information and SLP SPIs can be preconfigured with the
- end systems before they use SLP.
-
- SLPv2 enables a number of security policies with the mechanisms it
- includes. A SLPv2 UA could, for instance, reject any SLP message
- which did not carry an authentication block which it could verify.
- This is not the only policy which is possible to implement.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Guttman, et al. Standards Track [Page 47]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
-A. Appendix: Changes to the Service Location Protocol from v1 to v2
-
- SLP version 2 (SLPv2) corrects race conditions present in SLPv1 [22].
- In addition, authentication has been reworked to provide more
- flexibility and protection (especially for DA Advertisements). SLPv2
- also changes the formats and definition of many flags and values and
- reduces the number of 'required features.' SLPv2 clarifies and
- changes the use of 'Scopes', eliminating support for 'unscoped
- directory agents' and 'unscoped requests'. SLPv2 uses LDAPv3
- compatible string encodings of attributes and search filters. Other
- changes (such as Language and Character set handling) adopt practices
- recommended by the Internet Engineering Steering Group.
-
- Effort has been made to make SLPv2 operate the same whether DAs are
- present or not. For this reason, a new message (the SAAdvert) has
- been added. This allows UAs to discover scope information in the
- absence of administrative configuration and DAs. This was not
- possible in SLPv1.
-
- SLPv2 is incompatible in some respects with SLPv1. If a DA which
- supports both SLPv1 and SLPv2 with the same scope is present,
- services advertised by SAs using either version of the protocol will
- be available to both SLPv1 and SLPv2 UAs. SLPv1 DAs SHOULD be phased
- out and replace with SLPv2 DAs which support both versions of the
- protocol.
-
- SLPv1 allows services to be advertised and requested without a scope.
- Further, DAs can be configured without a scope. This is incompatible
- with SLPv2 and presents scalability problems. To facilitate this
- forward migration, SLPv1 agents MUST use scopes for all registrations
- and requests. SLPv1 DAs MUST be configured with a scope list. This
- constitutes a revision of RFC 2165 [22].
-
-B. Appendix: Service Discovery by Type: Minimal SLPv2 Features
-
- Service Agents may advertise services without attributes. This will
- enable only discovery of services by type. Service types discovered
- this way will have a Service Template [13] defined which specifies
- explicitly that no attributes are associated with the service
- advertisement. Service types associated with Service Templates which
- specify attributes MUST NOT be advertised by SAs which do not support
- attributes.
-
- While discovery of service by service type is a subset of the
- features possible using SLPv2 this form of discovery is consistent
- with the current generation of products that allow simple browsing of
- all services in a 'zone' or 'workgroup' by type. In some cases,
- attribute discovery, security and feature negotiation is handled by
-
-
-
-Guttman, et al. Standards Track [Page 48]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- application layer protocols - all that is required is the basic
- discovery of services that support a certain service.
-
- UAs requesting only service of that service type would only need to
- support service type and scope fields of the Service Request. UAs
- would still perform DA discovery and unicast SLPv2 SrvRqst messages
- to DAs in their scope once they were discovered instead of
- multicasting them.
-
- SAs would also perform DA discovery and use a SLPv2 SrvReg to
- register all their advertised services with SLPv2 DAs in their scope.
- These advertisements would needless to say contain no attribute
- string.
-
- These minimal SAs could ignore the Language Tag in requests since
- SrvRqst messages would contain no attributes, hence no strings would
- be internationalized. Further, any non-null predicate string would
- fail to match a service advertisement with no attributes, so these
- SAs would not have to parse and interpret search filters. Overflow
- will never occur in SrvRqst, SrvRply or SrvReg messages so TCP
- message handling would not have to be implemented. Finally, all
- AttrRqst messages could be dropped by the SA, since no attributes are
- supported.
-
-C. Appendix: DAAdverts with arbitrary URLs
-
- Using Active DA Discovery, a SrvRqst with its service type field set
- to "service:directory-agent". DAs will respond with a DAAdvert
- containing a URL with the "service:directory-agent:" scheme. This is
- the same DAAdvert that such a DA would multicast in unsolicited DA
- advertisements.
-
- A UA or SA which receives an unsolicited DAAdvert MUST examine the
- URL to determine if it has a recognized scheme. If the UA or SA does
- not recognize the DAAdvert's URL scheme, the DAAdvert is silently
- discarded. This document specifies only how to use URLs with the
- "service:directory-agent:" scheme.
-
- This provides the possibility for forward compatibility with future
- versions of SLP and enables other services to advertise their ability
- to serve as a clearinghouse for service location information.
-
- For example, if LDAPv3 [15] is used for service registration and
- discovery by a set of end systems, they could interpret a LDAP URL
- [16] to passively discover the LDAP server to use for this purpose.
- This document does not specify how this is done: SLPv2 agents
- without further support would simply discard this DAAdvert.
-
-
-
-
-Guttman, et al. Standards Track [Page 49]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
-D. Appendix: SLP Protocol Extensions
-
-D.1. Required Attribute Missing Option
-
- 0 1 2 3
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Extension Type = 0x0001 | Extension Length |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Template IDVer Length | Template IDVer String \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- |Required Attr <tag-list> Length| Required Attr <tag-list> \
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-
- Required attributes and the format of the IDVer string are defined by
- [13].
-
- If a SA or DA receives a SrvRqst or a SrvReg which fails to include a
- Required Attribute for the requested Service Type (according to the
- Service Template), it MAY return the Required Attribute Extension in
- addition to the reply corresponding to the message. The sender
- SHOULD reissue the message with a search filter including the
- attributes listed in the returned Required Attribute Extension.
- Similarly, the Required Attribute Extension may be returned in
- response to a SrvDereg message that contains a required attribute
- tag.
-
- The Template IDVer String is the name and version number string of
- the Service Template which defines the given attribute as required.
- It SHOULD be included, but can be omitted if a given SA or DA has
- been individually configured to have 'required attributes.'
-
- The Required Attribute <tag-list> MUST NOT include wild cards.
-
-E. Acknowledgments
-
- This document incorporates ideas from work on several discovery
- protocols, including RDP by Perkins and Harjono, and PDS by Michael
- Day. We are grateful for contributions by Ye Gu and Peter Ford.
- John Veizades was instrumental in the standardization of the Service
- Location Protocol. Implementors at Novell, Axis Communications and
- Sun Microsystems have contributed significantly to make this a much
- clearer and more consistent document.
-
-
-
-
-
-
-
-
-Guttman, et al. Standards Track [Page 50]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
-F. References
-
- [1] Port numbers, July 1997.
- ftp://ftp.isi.edu/in-notes/iana/assignments/port-numbers.
-
- [2] ISO/IEC JTC1/SC 21. Certificate Extensions. Draft Amendment
- DAM 4 to ISO/IEC 9594-2, December 1996.
-
- [3] ISO/IEC JTC1/SC 21. Certificate Extensions. Draft Amendment
- DAM 2 to ISO/IEC 9594-6, December 1996.
-
- [4] ISO/IEC JTC1/SC 21. Certificate Extensions. Draft Amendment
- DAM 1 to ISO/IEC 9594-7, December 1996.
-
- [5] ISO/IEC JTC1/SC 21. Certificate Extensions. Draft Amendment
- DAM 1 to ISO/IEC 9594-8, December 1996.
-
- [6] Unicode Technical Report #8. The Unicode Standard, version 2.1.
- Technical report, The Unicode Consortium, 1998.
-
- [7] Alvestrand, H., "Tags for the Identification of Languages",
- RFC 1766, March 1995.
-
- [8] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform
- Resource Identifiers (URI): Generic Syntax", RFC 2396,
- August 1998.
-
- [9] Bradner, S., "Key Words for Use in RFCs to Indicate Requirement
- Levels", BCP 14, RFC 2119, March 1997.
-
- [10] CCITT. The Directory Authentication Framework. Recommendation
- X.509, 1988.
-
- [11] Crocker, D. and P. Overell, "Augmented BNF for Syntax
- Specifications: ABNF", RFC 2234, November 1997.
-
- [12] S. Gursharan, R. Andrews, and A. Oppenheimer. Inside AppleTalk.
- Addison-Wesley, 1990.
-
- [13] Guttman, E., Perkins, C. and J. Kempf, "Service Templates and
- service: Schemes", RFC 2609, June 1999.
-
- [14] Howes, T., "The String Representation of LDAP Search Filters",
- RFC 2254, December 1997.
-
- [15] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory
- Access Protocol (v3)", RFC 2251, December 1997.
-
-
-
-
-Guttman, et al. Standards Track [Page 51]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
- [16] Howes, T. and M. Smith, "The LDAP URL Format", RFC 2255,
- December 1997.
-
- [17] Meyer, D., "Administratively Scoped IP Multicast", RFC 2365,
- July 1998.
-
- [18] Narten, T. and H. Alvestrand, "Guidelines for Writing
- an IANA Considerations Section in RFCs, BCP 26, RFC 2434,
- October 1998.
-
- [19] Microsoft Networks. SMB File Sharing Protocol Extensions 3.0,
- Document Version 1.09, November 1989.
-
- [20] National Institute of Standards and Technology. Digital
- signature standard. Technical Report NIST FIPS PUB 186, U.S.
- Department of Commerce, May 1994.
-
- [21] Perkins, C. and E. Guttman, "DHCP Options for Service Location
- Protocol", RFC 2610, June 1999.
-
- [22] Veizades, J., Guttman, E., Perkins, C. and S. Kaplan, "Service
- Location Protocol", RFC 2165, July 1997.
-
- [23] Yergeau, F., "UTF-8, a transformation format of ISO 10646",
- RFC 2279, January 1998.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Guttman, et al. Standards Track [Page 52]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
-G. Authors' Addresses
-
- Erik Guttman
- Sun Microsystems
- Bahnstr. 2
- 74915 Waibstadt
- Germany
-
- Phone: +49 7263 911 701
- EMail: Erik.Guttman@sun.com
-
-
- Charles Perkins
- Sun Microsystems
- 901 San Antonio Road
- Palo Alto, CA 94040
- USA
-
- Phone: +1 650 786 6464
- EMail: cperkins@sun.com
-
-
- John Veizades
- @Home Network
- 425 Broadway
- Redwood City, CA 94043
- USA
-
- Phone: +1 650 569 5243
- EMail: veizades@home.net
-
-
- Michael Day
- Vinca Corporation.
- 1201 North 800 East
- Orem, Utah 84097 USA
-
- Phone: +1 801 376-5083
- EMail: mday@vinca.com
-
-
-
-
-
-
-
-
-
-
-
-
-Guttman, et al. Standards Track [Page 53]
-
-RFC 2608 Service Location Protocol, Version 2 June 1999
-
-
-H. Full Copyright Statement
-
- Copyright (C) The Internet Society (1999). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE."
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Guttman, et al. Standards Track [Page 54]
-
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/utils/open-isns/doc/rfc3279.txt open-iscsi-2.0-872-rc4-bnx2i.work/utils/open-isns/doc/rfc3279.txt
--- open-iscsi-2.0-872-rc4-bnx2i/utils/open-isns/doc/rfc3279.txt 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/utils/open-isns/doc/rfc3279.txt 1969-12-31 18:00:00.000000000 -0600
@@ -1,1515 +0,0 @@
-
-
-
-
-
-
-Network Working Group W. Polk
-Request for Comments: 3279 NIST
-Obsoletes: 2528 R. Housley
-Category: Standards Track RSA Laboratories
- L. Bassham
- NIST
- April 2002
-
- Algorithms and Identifiers for the
- Internet X.509 Public Key Infrastructure
- Certificate and Certificate Revocation List (CRL) Profile
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2002). All Rights Reserved.
-
-Abstract
-
- This document specifies algorithm identifiers and ASN.1 encoding
- formats for digital signatures and subject public keys used in the
- Internet X.509 Public Key Infrastructure (PKI). Digital signatures
- are used to sign certificates and certificate revocation list (CRLs).
- Certificates include the public key of the named subject.
-
-Table of Contents
-
- 1 Introduction . . . . . . . . . . . . . . . . . . . . . . 2
- 2 Algorithm Support . . . . . . . . . . . . . . . . . . . . 3
- 2.1 One-Way Hash Functions . . . . . . . . . . . . . . . . 3
- 2.1.1 MD2 One-Way Hash Functions . . . . . . . . . . . . . 3
- 2.1.2 MD5 One-Way Hash Functions . . . . . . . . . . . . . 4
- 2.1.3 SHA-1 One-Way Hash Functions . . . . . . . . . . . . 4
- 2.2 Signature Algorithms . . . . . . . . . . . . . . . . . 4
- 2.2.1 RSA Signature Algorithm . . . . . . . . . . . . . . . 5
- 2.2.2 DSA Signature Algorithm . . . . . . . . . . . . . . . 6
- 2.2.3 Elliptic Curve Digital Signature Algorithm . . . . . 7
- 2.3 Subject Public Key Algorithms . . . . . . . . . . . . . 7
- 2.3.1 RSA Keys . . . . . . . . . . . . . . . . . . . . . . 8
- 2.3.2 DSA Signature Keys . . . . . . . . . . . . . . . . . 9
- 2.3.3 Diffie-Hellman Key Exchange Keys . . . . . . . . . . 10
-
-
-
-Polk, et al. Standards Track [Page 1]
-
-RFC 3279 Algorithms and Identifiers April 2002
-
-
- 2.3.4 KEA Public Keys . . . . . . . . . . . . . . . . . . . 11
- 2.3.5 ECDSA and ECDH Public Keys . . . . . . . . . . . . . 13
- 3 ASN.1 Module . . . . . . . . . . . . . . . . . . . . . . 18
- 4 References . . . . . . . . . . . . . . . . . . . . . . . 24
- 5 Security Considerations . . . . . . . . . . . . . . . . . 25
- 6 Intellectual Property Rights . . . . . . . . . . . . . . 26
- 7 Author Addresses . . . . . . . . . . . . . . . . . . . . 26
- 8 Full Copyright Statement . . . . . . . . . . . . . . . . 27
-
-1 Introduction
-
- 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].
-
- This document specifies algorithm identifiers and ASN.1 [X.660]
- encoding formats for digital signatures and subject public keys used
- in the Internet X.509 Public Key Infrastructure (PKI). This
- specification supplements [RFC 3280], "Internet X.509 Public Key
- Infrastructure: Certificate and Certificate Revocation List (CRL)
- Profile." Implementations of this specification MUST also conform to
- RFC 3280.
-
- This specification defines the contents of the signatureAlgorithm,
- signatureValue, signature, and subjectPublicKeyInfo fields within
- Internet X.509 certificates and CRLs.
-
- This document identifies one-way hash functions for use in the
- generation of digital signatures. These algorithms are used in
- conjunction with digital signature algorithms.
-
- This specification describes the encoding of digital signatures
- generated with the following cryptographic algorithms:
-
- * Rivest-Shamir-Adelman (RSA);
- * Digital Signature Algorithm (DSA); and
- * Elliptic Curve Digital Signature Algorithm (ECDSA).
-
- This document specifies the contents of the subjectPublicKeyInfo
- field in Internet X.509 certificates. For each algorithm, the
- appropriate alternatives for the the keyUsage extension are provided.
- This specification describes encoding formats for public keys used
- with the following cryptographic algorithms:
-
- * Rivest-Shamir-Adelman (RSA);
- * Digital Signature Algorithm (DSA);
- * Diffie-Hellman (DH);
- * Key Encryption Algorithm (KEA);
-
-
-
-Polk, et al. Standards Track [Page 2]
-
-RFC 3279 Algorithms and Identifiers April 2002
-
-
- * Elliptic Curve Digital Signature Algorithm (ECDSA); and
- * Elliptic Curve Diffie-Hellman (ECDH).
-
-2 Algorithm Support
-
- This section describes cryptographic algorithms which may be used
- with the Internet X.509 certificate and CRL profile [RFC 3280]. This
- section describes one-way hash functions and digital signature
- algorithms which may be used to sign certificates and CRLs, and
- identifies object identifiers (OIDs) for public keys contained in a
- certificate.
-
- Conforming CAs and applications MUST, at a minimum, support digital
- signatures and public keys for one of the specified algorithms. When
- using any of the algorithms identified in this specification,
- conforming CAs and applications MUST support them as described.
-
-2.1 One-way Hash Functions
-
- This section identifies one-way hash functions for use in the
- Internet X.509 PKI. One-way hash functions are also called message
- digest algorithms. SHA-1 is the preferred one-way hash function for
- the Internet X.509 PKI. However, PEM uses MD2 for certificates [RFC
- 1422] [RFC 1423] and MD5 is used in other legacy applications. For
- these reasons, MD2 and MD5 are included in this profile. The data
- that is hashed for certificate and CRL signing is fully described in
- [RFC 3280].
-
-2.1.1 MD2 One-way Hash Function
-
- MD2 was developed by Ron Rivest for RSA Security. RSA Security has
- recently placed the MD2 algorithm in the public domain. Previously,
- RSA Data Security had granted license for use of MD2 for non-
- commercial Internet Privacy-Enhanced Mail (PEM). MD2 may continue to
- be used with PEM certificates, but SHA-1 is preferred. MD2 produces
- a 128-bit "hash" of the input. MD2 is fully described in [RFC 1319].
-
- At the Selected Areas in Cryptography '95 conference in May 1995,
- Rogier and Chauvaud presented an attack on MD2 that can nearly find
- collisions [RC95]. Collisions occur when one can find two different
- messages that generate the same message digest. A checksum operation
- in MD2 is the only remaining obstacle to the success of the attack.
- For this reason, the use of MD2 for new applications is discouraged.
- It is still reasonable to use MD2 to verify existing signatures, as
- the ability to find collisions in MD2 does not enable an attacker to
- find new messages having a previously computed hash value.
-
-
-
-
-
-Polk, et al. Standards Track [Page 3]
-
-RFC 3279 Algorithms and Identifiers April 2002
-
-
-2.1.2 MD5 One-way Hash Function
-
- MD5 was developed by Ron Rivest for RSA Security. RSA Security has
- placed the MD5 algorithm in the public domain. MD5 produces a 128-
- bit "hash" of the input. MD5 is fully described in [RFC 1321].
-
- Den Boer and Bosselaers [DB94] have found pseudo-collisions for MD5,
- but there are no other known cryptanalytic results. The use of MD5
- for new applications is discouraged. It is still reasonable to use
- MD5 to verify existing signatures.
-
-2.1.3 SHA-1 One-way Hash Function
-
- SHA-1 was developed by the U.S. Government. SHA-1 produces a 160-bit
- "hash" of the input. SHA-1 is fully described in [FIPS 180-1]. RFC
- 3174 [RFC 3174] also describes SHA-1, and it provides an
- implementation of the algorithm.
-
-2.2 Signature Algorithms
-
- Certificates and CRLs conforming to [RFC 3280] may be signed with any
- public key signature algorithm. The certificate or CRL indicates the
- algorithm through an algorithm identifier which appears in the
- signatureAlgorithm field within the Certificate or CertificateList.
- This algorithm identifier is an OID and has optionally associated
- parameters. This section identifies algorithm identifiers and
- parameters that MUST be used in the signatureAlgorithm field in a
- Certificate or CertificateList.
-
- Signature algorithms are always used in conjunction with a one-way
- hash function.
-
- This section identifies OIDS for RSA, DSA, and ECDSA. The contents
- of the parameters component for each algorithm vary; details are
- provided for each algorithm.
-
- The data to be signed (e.g., the one-way hash function output value)
- is formatted for the signature algorithm to be used. Then, a private
- key operation (e.g., RSA encryption) is performed to generate the
- signature value. This signature value is then ASN.1 encoded as a BIT
- STRING and included in the Certificate or CertificateList in the
- signature field.
-
-
-
-
-
-
-
-
-
-Polk, et al. Standards Track [Page 4]
-
-RFC 3279 Algorithms and Identifiers April 2002
-
-
-2.2.1 RSA Signature Algorithm
-
- The RSA algorithm is named for its inventors: Rivest, Shamir, and
- Adleman. This profile includes three signature algorithms based on
- the RSA asymmetric encryption algorithm. The signature algorithms
- combine RSA with either the MD2, MD5, or the SHA-1 one-way hash
- functions.
-
- The signature algorithm with SHA-1 and the RSA encryption algorithm
- is implemented using the padding and encoding conventions described
- in PKCS #1 [RFC 2313]. The message digest is computed using the
- SHA-1 hash algorithm.
-
- The RSA signature algorithm, as specified in PKCS #1 [RFC 2313]
- includes a data encoding step. In this step, the message digest and
- the OID for the one-way hash function used to compute the digest are
- combined. When performing the data encoding step, the md2, md5, and
- id-sha1 OIDs MUST be used to specify the MD2, MD5, and SHA-1 one-way
- hash functions, respectively:
-
- md2 OBJECT IDENTIFIER ::= {
- iso(1) member-body(2) US(840) rsadsi(113549)
- digestAlgorithm(2) 2 }
-
- md5 OBJECT IDENTIFIER ::= {
- iso(1) member-body(2) US(840) rsadsi(113549)
- digestAlgorithm(2) 5 }
-
- id-sha1 OBJECT IDENTIFIER ::= {
- iso(1) identified-organization(3) oiw(14) secsig(3)
- algorithms(2) 26 }
-
- The signature algorithm with MD2 and the RSA encryption algorithm is
- defined in PKCS #1 [RFC 2313]. As defined in PKCS #1 [RFC 2313], the
- ASN.1 OID used to identify this signature algorithm is:
-
- md2WithRSAEncryption OBJECT IDENTIFIER ::= {
- iso(1) member-body(2) us(840) rsadsi(113549) pkcs(1)
- pkcs-1(1) 2 }
-
- The signature algorithm with MD5 and the RSA encryption algorithm is
- defined in PKCS #1 [RFC 2313]. As defined in PKCS #1 [RFC 2313], the
- ASN.1 OID used to identify this signature algorithm is:
-
- md5WithRSAEncryption OBJECT IDENTIFIER ::= {
- iso(1) member-body(2) us(840) rsadsi(113549) pkcs(1)
- pkcs-1(1) 4 }
-
-
-
-
-Polk, et al. Standards Track [Page 5]
-
-RFC 3279 Algorithms and Identifiers April 2002
-
-
- The ASN.1 object identifier used to identify this signature algorithm
- is:
-
- sha-1WithRSAEncryption OBJECT IDENTIFIER ::= {
- iso(1) member-body(2) us(840) rsadsi(113549) pkcs(1)
- pkcs-1(1) 5 }
-
- When any of these three OIDs appears within the ASN.1 type
- AlgorithmIdentifier, the parameters component of that type SHALL be
- the ASN.1 type NULL.
-
- The RSA signature generation process and the encoding of the result
- is described in detail in PKCS #1 [RFC 2313].
-
-2.2.2 DSA Signature Algorithm
-
- The Digital Signature Algorithm (DSA) is defined in the Digital
- Signature Standard (DSS). DSA was developed by the U.S. Government,
- and DSA is used in conjunction with the SHA-1 one-way hash function.
- DSA is fully described in [FIPS 186]. The ASN.1 OID used to identify
- this signature algorithm is:
-
- id-dsa-with-sha1 OBJECT IDENTIFIER ::= {
- iso(1) member-body(2) us(840) x9-57 (10040)
- x9cm(4) 3 }
-
- When the id-dsa-with-sha1 algorithm identifier appears as the
- algorithm field in an AlgorithmIdentifier, the encoding SHALL omit
- the parameters field. That is, the AlgorithmIdentifier SHALL be a
- SEQUENCE of one component: the OBJECT IDENTIFIER id-dsa-with-sha1.
-
- The DSA parameters in the subjectPublicKeyInfo field of the
- certificate of the issuer SHALL apply to the verification of the
- signature.
-
- When signing, the DSA algorithm generates two values. These values
- are commonly referred to as r and s. To easily transfer these two
- values as one signature, they SHALL be ASN.1 encoded using the
- following ASN.1 structure:
-
- Dss-Sig-Value ::= SEQUENCE {
- r INTEGER,
- s INTEGER }
-
-
-
-
-
-
-
-
-Polk, et al. Standards Track [Page 6]
-
-RFC 3279 Algorithms and Identifiers April 2002
-
-
-2.2.3 ECDSA Signature Algorithm
-
- The Elliptic Curve Digital Signature Algorithm (ECDSA) is defined in
- [X9.62]. The ASN.1 object identifiers used to identify ECDSA are
- defined in the following arc:
-
- ansi-X9-62 OBJECT IDENTIFIER ::= {
- iso(1) member-body(2) us(840) 10045 }
-
- id-ecSigType OBJECT IDENTIFIER ::= {
- ansi-X9-62 signatures(4) }
-
- ECDSA is used in conjunction with the SHA-1 one-way hash function.
- The ASN.1 object identifier used to identify ECDSA with SHA-1 is:
-
- ecdsa-with-SHA1 OBJECT IDENTIFIER ::= {
- id-ecSigType 1 }
-
- When the ecdsa-with-SHA1 algorithm identifier appears as the
- algorithm field in an AlgorithmIdentifier, the encoding MUST omit the
- parameters field. That is, the AlgorithmIdentifier SHALL be a
- SEQUENCE of one component: the OBJECT IDENTIFIER ecdsa-with-SHA1.
-
- The elliptic curve parameters in the subjectPublicKeyInfo field of
- the certificate of the issuer SHALL apply to the verification of the
- signature.
-
- When signing, the ECDSA algorithm generates two values. These values
- are commonly referred to as r and s. To easily transfer these two
- values as one signature, they MUST be ASN.1 encoded using the
- following ASN.1 structure:
-
- Ecdsa-Sig-Value ::= SEQUENCE {
- r INTEGER,
- s INTEGER }
-
-2.3 Subject Public Key Algorithms
-
- Certificates conforming to [RFC 3280] may convey a public key for any
- public key algorithm. The certificate indicates the algorithm
- through an algorithm identifier. This algorithm identifier is an OID
- and optionally associated parameters.
-
- This section identifies preferred OIDs and parameters for the RSA,
- DSA, Diffie-Hellman, KEA, ECDSA, and ECDH algorithms. Conforming CAs
- MUST use the identified OIDs when issuing certificates containing
-
-
-
-
-
-Polk, et al. Standards Track [Page 7]
-
-RFC 3279 Algorithms and Identifiers April 2002
-
-
- public keys for these algorithms. Conforming applications supporting
- any of these algorithms MUST, at a minimum, recognize the OID
- identified in this section.
-
-2.3.1 RSA Keys
-
- The OID rsaEncryption identifies RSA public keys.
-
- pkcs-1 OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840)
- rsadsi(113549) pkcs(1) 1 }
-
- rsaEncryption OBJECT IDENTIFIER ::= { pkcs-1 1}
-
- The rsaEncryption OID is intended to be used in the algorithm field
- of a value of type AlgorithmIdentifier. The parameters field MUST
- have ASN.1 type NULL for this algorithm identifier.
-
- The RSA public key MUST be encoded using the ASN.1 type RSAPublicKey:
-
- RSAPublicKey ::= SEQUENCE {
- modulus INTEGER, -- n
- publicExponent INTEGER } -- e
-
- where modulus is the modulus n, and publicExponent is the public
- exponent e. The DER encoded RSAPublicKey is the value of the BIT
- STRING subjectPublicKey.
-
- This OID is used in public key certificates for both RSA signature
- keys and RSA encryption keys. The intended application for the key
- MAY be indicated in the key usage field (see [RFC 3280]). The use of
- a single key for both signature and encryption purposes is not
- recommended, but is not forbidden.
-
- If the keyUsage extension is present in an end entity certificate
- which conveys an RSA public key, any combination of the following
- values MAY be present:
-
- digitalSignature;
- nonRepudiation;
- keyEncipherment; and
- dataEncipherment.
-
- If the keyUsage extension is present in a CA or CRL issuer
- certificate which conveys an RSA public key, any combination of the
- following values MAY be present:
-
- digitalSignature;
- nonRepudiation;
-
-
-
-Polk, et al. Standards Track [Page 8]
-
-RFC 3279 Algorithms and Identifiers April 2002
-
-
- keyEncipherment;
- dataEncipherment;
- keyCertSign; and
- cRLSign.
-
- However, this specification RECOMMENDS that if keyCertSign or cRLSign
- is present, both keyEncipherment and dataEncipherment SHOULD NOT be
- present.
-
-2.3.2 DSA Signature Keys
-
- The Digital Signature Algorithm (DSA) is defined in the Digital
- Signature Standard (DSS) [FIPS 186]. The DSA OID supported by this
- profile is:
-
- id-dsa OBJECT IDENTIFIER ::= {
- iso(1) member-body(2) us(840) x9-57(10040) x9cm(4) 1 }
-
- The id-dsa algorithm syntax includes optional domain parameters.
- These parameters are commonly referred to as p, q, and g. When
- omitted, the parameters component MUST be omitted entirely. That is,
- the AlgorithmIdentifier MUST be a SEQUENCE of one component: the
- OBJECT IDENTIFIER id-dsa.
-
- If the DSA domain parameters are present in the subjectPublicKeyInfo
- AlgorithmIdentifier, the parameters are included using the following
- ASN.1 structure:
-
- Dss-Parms ::= SEQUENCE {
- p INTEGER,
- q INTEGER,
- g INTEGER }
-
- The AlgorithmIdentifier within subjectPublicKeyInfo is the only place
- within a certificate where the parameters may be used. If the DSA
- algorithm parameters are omitted from the subjectPublicKeyInfo
- AlgorithmIdentifier and the CA signed the subject certificate using
- DSA, then the certificate issuer's DSA parameters apply to the
- subject's DSA key. If the DSA domain parameters are omitted from the
- SubjectPublicKeyInfo AlgorithmIdentifier and the CA signed the
- subject certificate using a signature algorithm other than DSA, then
- the subject's DSA domain parameters are distributed by other means.
- If the subjectPublicKeyInfo AlgorithmIdentifier field omits the
- parameters component, the CA signed the subject with a signature
- algorithm other than DSA, and the subject's DSA parameters are not
- available through other means, then clients MUST reject the
- certificate.
-
-
-
-
-Polk, et al. Standards Track [Page 9]
-
-RFC 3279 Algorithms and Identifiers April 2002
-
-
- The DSA public key MUST be ASN.1 DER encoded as an INTEGER; this
- encoding shall be used as the contents (i.e., the value) of the
- subjectPublicKey component (a BIT STRING) of the SubjectPublicKeyInfo
- data element.
-
- DSAPublicKey ::= INTEGER -- public key, Y
-
- If the keyUsage extension is present in an end entity certificate
- which conveys a DSA public key, any combination of the following
- values MAY be present:
-
- digitalSignature;
- nonRepudiation;
-
- If the keyUsage extension is present in a CA or CRL issuer
- certificate which conveys a DSA public key, any combination of the
- following values MAY be present:
-
- digitalSignature;
- nonRepudiation;
- keyCertSign; and
- cRLSign.
-
-2.3.3 Diffie-Hellman Key Exchange Keys
-
- The Diffie-Hellman OID supported by this profile is defined in
- [X9.42].
-
- dhpublicnumber OBJECT IDENTIFIER ::= { iso(1) member-body(2)
- us(840) ansi-x942(10046) number-type(2) 1 }
-
- The dhpublicnumber OID is intended to be used in the algorithm field
- of a value of type AlgorithmIdentifier. The parameters field of that
- type, which has the algorithm-specific syntax ANY DEFINED BY
- algorithm, have the ASN.1 type DomainParameters for this algorithm.
-
- DomainParameters ::= SEQUENCE {
- p INTEGER, -- odd prime, p=jq +1
- g INTEGER, -- generator, g
- q INTEGER, -- factor of p-1
- j INTEGER OPTIONAL, -- subgroup factor
- validationParms ValidationParms OPTIONAL }
-
- ValidationParms ::= SEQUENCE {
- seed BIT STRING,
- pgenCounter INTEGER }
-
-
-
-
-
-Polk, et al. Standards Track [Page 10]
-
-RFC 3279 Algorithms and Identifiers April 2002
-
-
- The fields of type DomainParameters have the following meanings:
-
- p identifies the prime p defining the Galois field;
-
- g specifies the generator of the multiplicative subgroup of order
- g;
-
- q specifies the prime factor of p-1;
-
- j optionally specifies the value that satisfies the equation
- p=jq+1 to support the optional verification of group parameters;
-
- seed optionally specifies the bit string parameter used as the
- seed for the domain parameter generation process; and
-
- pgenCounter optionally specifies the integer value output as part
- of the of the domain parameter prime generation process.
-
- If either of the domain parameter generation components (pgenCounter
- or seed) is provided, the other MUST be present as well.
-
- The Diffie-Hellman public key MUST be ASN.1 encoded as an INTEGER;
- this encoding shall be used as the contents (i.e., the value) of the
- subjectPublicKey component (a BIT STRING) of the SubjectPublicKeyInfo
- data element.
-
- DHPublicKey ::= INTEGER -- public key, y = g^x mod p
-
- If the keyUsage extension is present in a certificate which conveys a
- DH public key, the following values may be present:
-
- keyAgreement;
- encipherOnly; and
- decipherOnly.
-
- If present, the keyUsage extension MUST assert keyAgreement and MAY
- assert either encipherOnly and decipherOnly. The keyUsage extension
- MUST NOT assert both encipherOnly and decipherOnly.
-
-2.3.4 KEA Public Keys
-
- This section identifies the preferred OID and parameters for the
- inclusion of a KEA public key in a certificate. The Key Exchange
- Algorithm (KEA) is a key agreement algorithm. Two parties may
- generate a "pairwise key" if and only if they share the same KEA
- parameters. The KEA parameters are not included in a certificate;
- instead a domain identifier is supplied in the parameters field.
-
-
-
-
-Polk, et al. Standards Track [Page 11]
-
-RFC 3279 Algorithms and Identifiers April 2002
-
-
- When the SubjectPublicKeyInfo field contains a KEA key, the algorithm
- identifier and parameters SHALL be as defined in [SDN.701r]:
-
- id-keyExchangeAlgorithm OBJECT IDENTIFIER ::=
- { 2 16 840 1 101 2 1 1 22 }
-
- KEA-Parms-Id ::= OCTET STRING
-
- CAs MUST populate the parameters field of the AlgorithmIdentifier
- within the SubjectPublicKeyInfo field of each certificate containing
- a KEA public key with an 80-bit parameter identifier (OCTET STRING),
- also known as the domain identifier. The domain identifier is
- computed in three steps:
-
- (1) the KEA domain parameters (p, q, and g) are DER encoded using
- the Dss-Parms structure;
-
- (2) a 160-bit SHA-1 hash is generated from the parameters; and
-
- (3) the 160-bit hash is reduced to 80-bits by performing an
- "exclusive or" of the 80 high order bits with the 80 low order
- bits.
-
- The resulting value is encoded such that the most significant byte of
- the 80-bit value is the first octet in the octet string. The Dss-
- Parms is provided above in Section 2.3.2.
-
- A KEA public key, y, is conveyed in the subjectPublicKey BIT STRING
- such that the most significant bit (MSB) of y becomes the MSB of the
- BIT STRING value field and the least significant bit (LSB) of y
- becomes the LSB of the BIT STRING value field. This results in the
- following encoding:
-
- BIT STRING tag;
- BIT STRING length;
- 0 (indicating that there are zero unused bits in the final octet
- of y); and
- BIT STRING value field including y.
-
- The key usage extension may optionally appear in a KEA certificate.
- If a KEA certificate includes the keyUsage extension, only the
- following values may be asserted:
-
- keyAgreement;
- encipherOnly; and
- decipherOnly.
-
-
-
-
-
-Polk, et al. Standards Track [Page 12]
-
-RFC 3279 Algorithms and Identifiers April 2002
-
-
- If present, the keyUsage extension MUST assert keyAgreement and MAY
- assert either encipherOnly and decipherOnly. The keyUsage extension
- MUST NOT assert both encipherOnly and decipherOnly.
-
-2.3.5 ECDSA and ECDH Keys
-
- This section identifies the preferred OID and parameter encoding for
- the inclusion of an ECDSA or ECDH public key in a certificate. The
- Elliptic Curve Digital Signature Algorithm (ECDSA) is defined in
- [X9.62]. ECDSA is the elliptic curve mathematical analog of the
- Digital Signature Algorithm [FIPS 186]. The Elliptic Curve Diffie
- Hellman (ECDH) algorithm is a key agreement algorithm defined in
- [X9.63].
-
- ECDH is the elliptic curve mathematical analog of the Diffie-Hellman
- key agreement algorithm as specified in [X9.42]. The ECDSA and ECDH
- specifications use the same OIDs and parameter encodings. The ASN.1
- object identifiers used to identify these public keys are defined in
- the following arc:
-
- ansi-X9-62 OBJECT IDENTIFIER ::=
- { iso(1) member-body(2) us(840) 10045 }
-
- When certificates contain an ECDSA or ECDH public key, the
- id-ecPublicKey algorithm identifier MUST be used. The id-ecPublicKey
- algorithm identifier is defined as follows:
-
- id-public-key-type OBJECT IDENTIFIER ::= { ansi-X9.62 2 }
-
- id-ecPublicKey OBJECT IDENTIFIER ::= { id-publicKeyType 1 }
-
- This OID is used in public key certificates for both ECDSA signature
- keys and ECDH encryption keys. The intended application for the key
- may be indicated in the key usage field (see [RFC 3280]). The use of
- a single key for both signature and encryption purposes is not
- recommended, but is not forbidden.
-
- ECDSA and ECDH require use of certain parameters with the public key.
- The parameters may be inherited from the issuer, implicitly included
- through reference to a "named curve," or explicitly included in the
- certificate.
-
- EcpkParameters ::= CHOICE {
- ecParameters ECParameters,
- namedCurve OBJECT IDENTIFIER,
- implicitlyCA NULL }
-
-
-
-
-
-Polk, et al. Standards Track [Page 13]
-
-RFC 3279 Algorithms and Identifiers April 2002
-
-
- When the parameters are inherited, the parameters field SHALL contain
- implictlyCA, which is the ASN.1 value NULL. When parameters are
- specified by reference, the parameters field SHALL contain the
- named-Curve choice, which is an object identifier. When the
- parameters are explicitly included, they SHALL be encoded in the
- ASN.1 structure ECParameters:
-
- ECParameters ::= SEQUENCE {
- version ECPVer, -- version is always 1
- fieldID FieldID, -- identifies the finite field over
- -- which the curve is defined
- curve Curve, -- coefficients a and b of the
- -- elliptic curve
- base ECPoint, -- specifies the base point P
- -- on the elliptic curve
- order INTEGER, -- the order n of the base point
- cofactor INTEGER OPTIONAL -- The integer h = #E(Fq)/n
- }
-
- ECPVer ::= INTEGER {ecpVer1(1)}
-
- Curve ::= SEQUENCE {
- a FieldElement,
- b FieldElement,
- seed BIT STRING OPTIONAL }
-
- FieldElement ::= OCTET STRING
-
- ECPoint ::= OCTET STRING
-
- The value of FieldElement SHALL be the octet string representation of
- a field element following the conversion routine in [X9.62], Section
- 4.3.3. The value of ECPoint SHALL be the octet string representation
- of an elliptic curve point following the conversion routine in
- [X9.62], Section 4.3.6. Note that this octet string may represent an
- elliptic curve point in compressed or uncompressed form.
-
- Implementations that support elliptic curve according to this
- specification MUST support the uncompressed form and MAY support the
- compressed form.
-
- The components of type ECParameters have the following meanings:
-
- version specifies the version number of the elliptic curve
- parameters. It MUST have the value 1 (ecpVer1).
-
-
-
-
-
-
-Polk, et al. Standards Track [Page 14]
-
-RFC 3279 Algorithms and Identifiers April 2002
-
-
- fieldID identifies the finite field over which the elliptic curve
- is defined. Finite fields are represented by values of the
- parameterized type FieldID, constrained to the values of the
- objects defined in the information object set FieldTypes.
- Additional detail regarding fieldID is provided below.
-
- curve specifies the coefficients a and b of the elliptic curve E.
- Each coefficient is represented as a value of type FieldElement,
- an OCTET STRING. seed is an optional parameter used to derive the
- coefficients of a randomly generated elliptic curve.
-
- base specifies the base point P on the elliptic curve. The base
- point is represented as a value of type ECPoint, an OCTET STRING.
-
- order specifies the order n of the base point.
-
- cofactor is the integer h = #E(Fq)/n. This parameter is specified
- as OPTIONAL. However, the cofactor MUST be included in ECDH
- public key parameters. The cofactor is not required to support
- ECDSA, except in parameter validation. The cofactor MAY be
- included to support parameter validation for ECDSA keys.
- Parameter validation is not required by this specification.
-
- The AlgorithmIdentifier within SubjectPublicKeyInfo is the only place
- within a certificate where the parameters may be used. If the
- elliptic curve parameters are specified as implicitlyCA in the
- SubjectPublicKeyInfo AlgorithmIdentifier and the CA signed the
- subject certificate using ECDSA, then the certificate issuer's ECDSA
- parameters apply to the subject's ECDSA key. If the elliptic curve
- parameters are specified as implicitlyCA in the SubjectPublicKeyInfo
- AlgorithmIdentifier and the CA signed the certificate using a
- signature algorithm other than ECDSA, then clients MUST not make use
- of the elliptic curve public key.
-
- FieldID ::= SEQUENCE {
- fieldType OBJECT IDENTIFIER,
- parameters ANY DEFINED BY fieldType }
-
- FieldID is a SEQUENCE of two components, fieldType and parameters.
- The fieldType contains an object identifier value that uniquely
- identifies the type contained in the parameters.
-
- The object identifier id-fieldType specifies an arc containing the
- object identifiers of each field type. It has the following value:
-
- id-fieldType OBJECT IDENTIFIER ::= { ansi-X9-62 fieldType(1) }
-
-
-
-
-
-Polk, et al. Standards Track [Page 15]
-
-RFC 3279 Algorithms and Identifiers April 2002
-
-
- The object identifiers prime-field and characteristic-two-field name
- the two kinds of fields defined in this Standard. They have the
- following values:
-
- prime-field OBJECT IDENTIFIER ::= { id-fieldType 1 }
-
- Prime-p ::= INTEGER -- Field size p (p in bits)
-
- characteristic-two-field OBJECT IDENTIFIER ::= { id-fieldType 2 }
-
- Characteristic-two ::= SEQUENCE {
- m INTEGER, -- Field size 2^m
- basis OBJECT IDENTIFIER,
- parameters ANY DEFINED BY basis }
-
- The object identifier id-characteristic-two-basis specifies an arc
- containing the object identifiers for each type of basis for the
- characteristic-two finite fields. It has the following value:
-
- id-characteristic-two-basis OBJECT IDENTIFIER ::= {
- characteristic-two-field basisType(1) }
-
- The object identifiers gnBasis, tpBasis and ppBasis name the three
- kinds of basis for characteristic-two finite fields defined by
- [X9.62]. They have the following values:
-
- gnBasis OBJECT IDENTIFIER ::= { id-characteristic-two-basis 1 }
-
- -- for gnBasis, the value of the parameters field is NULL
-
- tpBasis OBJECT IDENTIFIER ::= { id-characteristic-two-basis 2 }
-
- -- type of parameters field for tpBasis is Trinomial
-
- Trinomial ::= INTEGER
-
- ppBasis OBJECT IDENTIFIER ::= { id-characteristic-two-basis 3 }
-
- -- type of parameters field for ppBasis is Pentanomial
-
- Pentanomial ::= SEQUENCE {
- k1 INTEGER,
- k2 INTEGER,
- k3 INTEGER }
-
-
-
-
-
-
-
-Polk, et al. Standards Track [Page 16]
-
-RFC 3279 Algorithms and Identifiers April 2002
-
-
- The elliptic curve public key (an ECPoint which is an OCTET STRING)
- is mapped to a subjectPublicKey (a BIT STRING) as follows: the most
- significant bit of the OCTET STRING becomes the most significant bit
- of the BIT STRING, and the least significant bit of the OCTET STRING
- becomes the least significant bit of the BIT STRING. Note that this
- octet string may represent an elliptic curve point in compressed or
- uncompressed form. Implementations that support elliptic curve
- according to this specification MUST support the uncompressed form
- and MAY support the compressed form.
-
- If the keyUsage extension is present in a CA or CRL issuer
- certificate which conveys an elliptic curve public key, any
- combination of the following values MAY be present:
-
- digitalSignature;
- nonRepudiation; and
- keyAgreement.
-
- If the keyAgreement value is present, either of the following values
- MAY be present:
-
- encipherOnly; and
- decipherOnly.
-
- The keyUsage extension MUST NOT assert both encipherOnly and
- decipherOnly.
-
- If the keyUsage extension is present in a CA certificate which
- conveys an elliptic curve public key, any combination of the
- following values MAY be present:
-
- digitalSignature;
- nonRepudiation;
- keyAgreement;
- keyCertSign; and
- cRLSign.
-
- As above, if the keyUsage extension asserts keyAgreement then it MAY
- assert either encipherOnly and decipherOnly. However, this
- specification RECOMMENDS that if keyCertSign or cRLSign is present,
- keyAgreement, encipherOnly, and decipherOnly SHOULD NOT be present.
-
-
-
-
-
-
-
-
-
-
-Polk, et al. Standards Track [Page 17]
-
-RFC 3279 Algorithms and Identifiers April 2002
-
-
-3 ASN.1 Module
-
- PKIX1Algorithms88 { iso(1) identified-organization(3) dod(6)
- internet(1) security(5) mechanisms(5) pkix(7) id-mod(0)
- id-mod-pkix1-algorithms(17) }
-
- DEFINITIONS EXPLICIT TAGS ::= BEGIN
-
- -- EXPORTS All;
-
- -- IMPORTS NONE;
-
- --
- -- One-way Hash Functions
- --
-
- md2 OBJECT IDENTIFIER ::= {
- iso(1) member-body(2) us(840) rsadsi(113549)
- digestAlgorithm(2) 2 }
-
- md5 OBJECT IDENTIFIER ::= {
- iso(1) member-body(2) us(840) rsadsi(113549)
- digestAlgorithm(2) 5 }
-
- id-sha1 OBJECT IDENTIFIER ::= {
- iso(1) identified-organization(3) oiw(14) secsig(3)
- algorithms(2) 26 }
-
- --
- -- DSA Keys and Signatures
- --
-
- -- OID for DSA public key
-
- id-dsa OBJECT IDENTIFIER ::= {
- iso(1) member-body(2) us(840) x9-57(10040) x9algorithm(4) 1 }
-
- -- encoding for DSA public key
-
- DSAPublicKey ::= INTEGER -- public key, y
-
- Dss-Parms ::= SEQUENCE {
- p INTEGER,
- q INTEGER,
- g INTEGER }
-
-
-
-
-
-
-Polk, et al. Standards Track [Page 18]
-
-RFC 3279 Algorithms and Identifiers April 2002
-
-
- -- OID for DSA signature generated with SHA-1 hash
-
- id-dsa-with-sha1 OBJECT IDENTIFIER ::= {
- iso(1) member-body(2) us(840) x9-57 (10040) x9algorithm(4) 3 }
-
- -- encoding for DSA signature generated with SHA-1 hash
-
- Dss-Sig-Value ::= SEQUENCE {
- r INTEGER,
- s INTEGER }
-
- --
- -- RSA Keys and Signatures
- --
-
- -- arc for RSA public key and RSA signature OIDs
-
- pkcs-1 OBJECT IDENTIFIER ::= {
- iso(1) member-body(2) us(840) rsadsi(113549) pkcs(1) 1 }
-
- -- OID for RSA public keys
-
- rsaEncryption OBJECT IDENTIFIER ::= { pkcs-1 1 }
-
- -- OID for RSA signature generated with MD2 hash
-
- md2WithRSAEncryption OBJECT IDENTIFIER ::= { pkcs-1 2 }
-
- -- OID for RSA signature generated with MD5 hash
-
- md5WithRSAEncryption OBJECT IDENTIFIER ::= { pkcs-1 4 }
-
- -- OID for RSA signature generated with SHA-1 hash
-
- sha1WithRSAEncryption OBJECT IDENTIFIER ::= { pkcs-1 5 }
-
- -- encoding for RSA public key
-
- RSAPublicKey ::= SEQUENCE {
- modulus INTEGER, -- n
- publicExponent INTEGER } -- e
-
-
-
-
-
-
-
-
-
-
-Polk, et al. Standards Track [Page 19]
-
-RFC 3279 Algorithms and Identifiers April 2002
-
-
- --
- -- Diffie-Hellman Keys
- --
-
- dhpublicnumber OBJECT IDENTIFIER ::= {
- iso(1) member-body(2) us(840) ansi-x942(10046)
- number-type(2) 1 }
-
- -- encoding for DSA public key
-
- DHPublicKey ::= INTEGER -- public key, y = g^x mod p
-
- DomainParameters ::= SEQUENCE {
- p INTEGER, -- odd prime, p=jq +1
- g INTEGER, -- generator, g
- q INTEGER, -- factor of p-1
- j INTEGER OPTIONAL, -- subgroup factor, j>= 2
- validationParms ValidationParms OPTIONAL }
-
- ValidationParms ::= SEQUENCE {
- seed BIT STRING,
- pgenCounter INTEGER }
-
- --
- -- KEA Keys
- --
-
- id-keyExchangeAlgorithm OBJECT IDENTIFIER ::=
- { 2 16 840 1 101 2 1 1 22 }
-
- KEA-Parms-Id ::= OCTET STRING
-
- --
- -- Elliptic Curve Keys, Signatures, and Curves
- --
-
- ansi-X9-62 OBJECT IDENTIFIER ::= {
- iso(1) member-body(2) us(840) 10045 }
-
- FieldID ::= SEQUENCE { -- Finite field
- fieldType OBJECT IDENTIFIER,
- parameters ANY DEFINED BY fieldType }
-
- -- Arc for ECDSA signature OIDS
-
- id-ecSigType OBJECT IDENTIFIER ::= { ansi-X9-62 signatures(4) }
-
-
-
-
-
-Polk, et al. Standards Track [Page 20]
-
-RFC 3279 Algorithms and Identifiers April 2002
-
-
- -- OID for ECDSA signatures with SHA-1
-
- ecdsa-with-SHA1 OBJECT IDENTIFIER ::= { id-ecSigType 1 }
-
- -- OID for an elliptic curve signature
- -- format for the value of an ECDSA signature value
-
- ECDSA-Sig-Value ::= SEQUENCE {
- r INTEGER,
- s INTEGER }
-
- -- recognized field type OIDs are defined in the following arc
-
- id-fieldType OBJECT IDENTIFIER ::= { ansi-X9-62 fieldType(1) }
-
- -- where fieldType is prime-field, the parameters are of type Prime-p
-
- prime-field OBJECT IDENTIFIER ::= { id-fieldType 1 }
-
- Prime-p ::= INTEGER -- Finite field F(p), where p is an odd prime
-
- -- where fieldType is characteristic-two-field, the parameters are
- -- of type Characteristic-two
-
- characteristic-two-field OBJECT IDENTIFIER ::= { id-fieldType 2 }
-
- Characteristic-two ::= SEQUENCE {
- m INTEGER, -- Field size 2^m
- basis OBJECT IDENTIFIER,
- parameters ANY DEFINED BY basis }
-
- -- recognized basis type OIDs are defined in the following arc
-
- id-characteristic-two-basis OBJECT IDENTIFIER ::= {
- characteristic-two-field basisType(3) }
-
- -- gnbasis is identified by OID gnBasis and indicates
- -- parameters are NULL
-
- gnBasis OBJECT IDENTIFIER ::= { id-characteristic-two-basis 1 }
-
- -- parameters for this basis are NULL
-
- -- trinomial basis is identified by OID tpBasis and indicates
- -- parameters of type Pentanomial
-
- tpBasis OBJECT IDENTIFIER ::= { id-characteristic-two-basis 2 }
-
-
-
-
-Polk, et al. Standards Track [Page 21]
-
-RFC 3279 Algorithms and Identifiers April 2002
-
-
- -- Trinomial basis representation of F2^m
- -- Integer k for reduction polynomial xm + xk + 1
-
- Trinomial ::= INTEGER
-
- -- for pentanomial basis is identified by OID ppBasis and indicates
- -- parameters of type Pentanomial
-
- ppBasis OBJECT IDENTIFIER ::= { id-characteristic-two-basis 3 }
-
- -- Pentanomial basis representation of F2^m
- -- reduction polynomial integers k1, k2, k3
- -- f(x) = x**m + x**k3 + x**k2 + x**k1 + 1
-
- Pentanomial ::= SEQUENCE {
- k1 INTEGER,
- k2 INTEGER,
- k3 INTEGER }
-
- -- The object identifiers gnBasis, tpBasis and ppBasis name
- -- three kinds of basis for characteristic-two finite fields
-
- FieldElement ::= OCTET STRING -- Finite field element
-
- ECPoint ::= OCTET STRING -- Elliptic curve point
-
- -- Elliptic Curve parameters may be specified explicitly,
- -- specified implicitly through a "named curve", or
- -- inherited from the CA
-
- EcpkParameters ::= CHOICE {
- ecParameters ECParameters,
- namedCurve OBJECT IDENTIFIER,
- implicitlyCA NULL }
-
- ECParameters ::= SEQUENCE { -- Elliptic curve parameters
- version ECPVer,
- fieldID FieldID,
- curve Curve,
- base ECPoint, -- Base point G
- order INTEGER, -- Order n of the base point
- cofactor INTEGER OPTIONAL } -- The integer h = #E(Fq)/n
-
- ECPVer ::= INTEGER {ecpVer1(1)}
-
-
-
-
-
-
-
-Polk, et al. Standards Track [Page 22]
-
-RFC 3279 Algorithms and Identifiers April 2002
-
-
- Curve ::= SEQUENCE {
- a FieldElement, -- Elliptic curve coefficient a
- b FieldElement, -- Elliptic curve coefficient b
- seed BIT STRING OPTIONAL }
-
- id-publicKeyType OBJECT IDENTIFIER ::= { ansi-X9-62 keyType(2) }
-
- id-ecPublicKey OBJECT IDENTIFIER ::= { id-publicKeyType 1 }
-
- -- Named Elliptic Curves in ANSI X9.62.
-
- ellipticCurve OBJECT IDENTIFIER ::= { ansi-X9-62 curves(3) }
-
- c-TwoCurve OBJECT IDENTIFIER ::= {
- ellipticCurve characteristicTwo(0) }
-
- c2pnb163v1 OBJECT IDENTIFIER ::= { c-TwoCurve 1 }
- c2pnb163v2 OBJECT IDENTIFIER ::= { c-TwoCurve 2 }
- c2pnb163v3 OBJECT IDENTIFIER ::= { c-TwoCurve 3 }
- c2pnb176w1 OBJECT IDENTIFIER ::= { c-TwoCurve 4 }
- c2tnb191v1 OBJECT IDENTIFIER ::= { c-TwoCurve 5 }
- c2tnb191v2 OBJECT IDENTIFIER ::= { c-TwoCurve 6 }
- c2tnb191v3 OBJECT IDENTIFIER ::= { c-TwoCurve 7 }
- c2onb191v4 OBJECT IDENTIFIER ::= { c-TwoCurve 8 }
- c2onb191v5 OBJECT IDENTIFIER ::= { c-TwoCurve 9 }
- c2pnb208w1 OBJECT IDENTIFIER ::= { c-TwoCurve 10 }
- c2tnb239v1 OBJECT IDENTIFIER ::= { c-TwoCurve 11 }
- c2tnb239v2 OBJECT IDENTIFIER ::= { c-TwoCurve 12 }
- c2tnb239v3 OBJECT IDENTIFIER ::= { c-TwoCurve 13 }
- c2onb239v4 OBJECT IDENTIFIER ::= { c-TwoCurve 14 }
- c2onb239v5 OBJECT IDENTIFIER ::= { c-TwoCurve 15 }
- c2pnb272w1 OBJECT IDENTIFIER ::= { c-TwoCurve 16 }
- c2pnb304w1 OBJECT IDENTIFIER ::= { c-TwoCurve 17 }
- c2tnb359v1 OBJECT IDENTIFIER ::= { c-TwoCurve 18 }
- c2pnb368w1 OBJECT IDENTIFIER ::= { c-TwoCurve 19 }
- c2tnb431r1 OBJECT IDENTIFIER ::= { c-TwoCurve 20 }
-
- primeCurve OBJECT IDENTIFIER ::= { ellipticCurve prime(1) }
-
- prime192v1 OBJECT IDENTIFIER ::= { primeCurve 1 }
- prime192v2 OBJECT IDENTIFIER ::= { primeCurve 2 }
- prime192v3 OBJECT IDENTIFIER ::= { primeCurve 3 }
- prime239v1 OBJECT IDENTIFIER ::= { primeCurve 4 }
- prime239v2 OBJECT IDENTIFIER ::= { primeCurve 5 }
- prime239v3 OBJECT IDENTIFIER ::= { primeCurve 6 }
- prime256v1 OBJECT IDENTIFIER ::= { primeCurve 7 }
-
- END
-
-
-
-Polk, et al. Standards Track [Page 23]
-
-RFC 3279 Algorithms and Identifiers April 2002
-
-
-4 References
-
- [FIPS 180-1] Federal Information Processing Standards Publication
- (FIPS PUB) 180-1, Secure Hash Standard, 17 April 1995.
- [Supersedes FIPS PUB 180 dated 11 May 1993.]
-
- [FIPS 186-2] Federal Information Processing Standards Publication
- (FIPS PUB) 186, Digital Signature Standard, 27 January
- 2000. [Supersedes FIPS PUB 186-1 dated 15 December
- 1998.]
-
- [P1363] IEEE P1363, "Standard Specifications for Public-Key
- Cryptography", 2001.
-
- [RC95] Rogier, N. and Chauvaud, P., "The compression function
- of MD2 is not collision free," Presented at Selected
- Areas in Cryptography '95, May 1995.
-
- [RFC 1034] Mockapetris, P., "Domain Names - Concepts and
- Facilities", STD 13, RFC 1034, November 1987.
-
- [RFC 1319] Kaliski, B., "The MD2 Message-Digest Algorithm", RFC
- 1319, April 1992.
-
- [RFC 1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC
- 1321, April 1992.
-
- [RFC 1422] Kent, S., "Privacy Enhancement for Internet Electronic
- Mail: Part II: Certificate-Based Key Management", RFC
- 1422, February 1993.
-
- [RFC 1423] Balenson, D., "Privacy Enhancement for Internet
- Electronic Mail: Part III: Algorithms, Modes, and
- Identifiers", RFC 1423, February 1993.
-
- [RFC 2119] Bradner, S., "Key Words for Use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC 2313] Kaliski, B., "PKCS #1: RSA Encryption Version 1.5",
- RFC 2313, March 1998.
-
- [RFC 2459] Housley, R., Ford, W., Polk, W. and D. Solo "Internet
- X.509 Public Key Infrastructure: Certificate and CRL
- Profile", RFC 2459, January, 1999.
-
- [RFC 3174] Eastlake, D. and P. Jones, "US Secure Hash Algorithm 1
- (SHA1)", RFC 3174, September 2001.
-
-
-
-
-Polk, et al. Standards Track [Page 24]
-
-RFC 3279 Algorithms and Identifiers April 2002
-
-
- [RFC 3280] Housley, R., Polk, W., Ford, W. and D. Solo, "Internet
- X.509 Public Key Infrastructure Certificate and
- Certificate Revocation List (CRL) Profile", RFC 3280,
- April 2002.
-
- [SDN.701r] SDN.701, "Message Security Protocol 4.0", Revision A
- 1997-02-06.
-
- [X.208] CCITT Recommendation X.208: Specification of Abstract
- Syntax Notation One (ASN.1), 1988.
-
- [X.660] ITU-T Recommendation X.660 Information Technology -
- ASN.1 encoding rules: Specification of Basic Encoding
- Rules (BER), Canonical Encoding Rules (CER) and
- Distinguished Encoding Rules (DER), 1997.
-
- [X9.42] ANSI X9.42-2000, "Public Key Cryptography for The
- Financial Services Industry: Agreement of Symmetric
- Keys Using Discrete Logarithm Cryptography", December,
- 1999.
-
- [X9.62] X9.62-1998, "Public Key Cryptography For The Financial
- Services Industry: The Elliptic Curve Digital
- Signature Algorithm (ECDSA)", January 7, 1999.
-
- [X9.63] ANSI X9.63-2001, "Public Key Cryptography For The
- Financial Services Industry: Key Agreement and Key
- Transport Using Elliptic Curve Cryptography", Work in
- Progress.
-
-5 Security Considerations
-
- This specification does not constrain the size of public keys or
- their parameters for use in the Internet PKI. However, the key size
- selected impacts the strength achieved when implementing
- cryptographic services. Selection of appropriate key sizes is
- critical to implementing appropriate security.
-
- This specification does not identify particular elliptic curves for
- use in the Internet PKI. However, the particular curve selected
- impact the strength of the digital signatures. Some curves are
- cryptographically stronger than others!
-
- In general, use of "well-known" curves, such as the "named curves"
- from ANSI X9.62, is a sound strategy. For additional information,
- refer to X9.62 Appendix H.1.3, "Key Length Considerations" and
- Appendix A.1, "Avoiding Cryptographically Weak Keys".
-
-
-
-
-Polk, et al. Standards Track [Page 25]
-
-RFC 3279 Algorithms and Identifiers April 2002
-
-
- This specification supplements RFC 3280. The security considerations
- section of that document applies to this specification as well.
-
-6 Intellectual Property Rights
-
- The IETF has been notified of intellectual property rights claimed in
- regard to some or all of the specification contained in this
- document. For more information consult the online list of claimed
- rights.
-
- The IETF takes no position regarding the validity or scope of any
- intellectual property or other rights that might be claimed to
- pertain to the implementation or use of the technology described in
- this document or the extent to which any license under such rights
- might or might not be available; neither does it represent that it
- has made any effort to identify any such rights. Information on the
- IETF's procedures with respect to rights in standards-track and
- standards- related documentation can be found in BCP-11. Copies of
- claims of rights made available for publication and any assurances of
- licenses to be made available, or the result of an attempt made to
- obtain a general license or permission for the use of such
- proprietary rights by implementors or users of this specification can
- be obtained from the IETF Secretariat.
-
-7 Author Addresses:
-
- Tim Polk
- NIST
- 100 Bureau Drive, Stop 8930
- Gaithersburg, MD 20899-8930
- USA
- EMail: tim.polk@nist.gov
-
- Russell Housley
- RSA Laboratories
- 918 Spring Knoll Drive
- Herndon, VA 20170
- USA
- EMail: rhousley@rsasecurity.com
-
- Larry Bassham
- NIST
- 100 Bureau Drive, Stop 8930
- Gaithersburg, MD 20899-8930
- USA
- EMail: lbassham@nist.gov
-
-
-
-
-
-Polk, et al. Standards Track [Page 26]
-
-RFC 3279 Algorithms and Identifiers April 2002
-
-
-8. Full Copyright Statement
-
- Copyright (C) The Internet Society (2002). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Polk, et al. Standards Track [Page 27]
-
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/utils/open-isns/doc/rfc3720.txt open-iscsi-2.0-872-rc4-bnx2i.work/utils/open-isns/doc/rfc3720.txt
--- open-iscsi-2.0-872-rc4-bnx2i/utils/open-isns/doc/rfc3720.txt 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/utils/open-isns/doc/rfc3720.txt 1969-12-31 18:00:00.000000000 -0600
@@ -1,14395 +0,0 @@
-
-
-
-
-
-
-Network Working Group J. Satran
-Request for Comments: 3720 K. Meth
-Category: Standards Track IBM
- C. Sapuntzakis
- Cisco Systems
- M. Chadalapaka
- Hewlett-Packard Co.
- E. Zeidner
- IBM
- April 2004
-
-
- Internet Small Computer Systems Interface (iSCSI)
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2003). All Rights Reserved.
-
-Abstract
-
- This document describes a transport protocol for Internet Small
- Computer Systems Interface (iSCSI) that works on top of TCP. The
- iSCSI protocol aims to be fully compliant with the standardized SCSI
- architecture model.
-
- SCSI is a popular family of protocols that enable systems to
- communicate with I/O devices, especially storage devices. SCSI
- protocols are request/response application protocols with a common
- standardized architecture model and basic command set, as well as
- standardized command sets for different device classes (disks, tapes,
- media-changers etc.).
-
- As system interconnects move from the classical bus structure to a
- network structure, SCSI has to be mapped to network transport
- protocols. IP networks now meet the performance requirements of fast
- system interconnects and as such are good candidates to "carry" SCSI.
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 1]
-
-RFC 3720 iSCSI April 2004
-
-
-Table of Contents
-
- 1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . 9
- 2. Definitions and Acronyms. . . . . . . . . . . . . . . . . . . 10
- 2.1. Definitions. . . . . . . . . . . . . . . . . . . . . . 10
- 2.2. Acronyms . . . . . . . . . . . . . . . . . . . . . . . 14
- 2.3. Conventions. . . . . . . . . . . . . . . . . . . . . . 16
- 2.3.1. Word Rule. . . . . . . . . . . . . . . . . . 16
- 2.3.2. Half-Word Rule . . . . . . . . . . . . . . . 17
- 2.3.3. Byte Rule. . . . . . . . . . . . . . . . . . 17
- 3. Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . 17
- 3.1. SCSI Concepts. . . . . . . . . . . . . . . . . . . . . 17
- 3.2. iSCSI Concepts and Functional Overview . . . . . . . . 18
- 3.2.1. Layers and Sessions. . . . . . . . . . . . . 19
- 3.2.2. Ordering and iSCSI Numbering . . . . . . . . 19
- 3.2.2.1. Command Numbering and
- Acknowledging . . . . . . . . . . 20
- 3.2.2.2. Response/Status Numbering and
- Acknowledging . . . . . . . . . . 23
- 3.2.2.3. Data Sequencing . . . . . . . . 24
- 3.2.3. iSCSI Login. . . . . . . . . . . . . . . . . 24
- 3.2.4. iSCSI Full Feature Phase . . . . . . . . . . 25
- 3.2.4.1. Command Connection Allegiance . . 26
- 3.2.4.2. Data Transfer Overview. . . . . . 27
- 3.2.4.3. Tags and Integrity Checks . . . . 28
- 3.2.4.4. Task Management . . . . . . . . . 28
- 3.2.5. iSCSI Connection Termination . . . . . . . . 29
- 3.2.6. iSCSI Names. . . . . . . . . . . . . . . . . 29
- 3.2.6.1. iSCSI Name Properties . . . . . . 30
- 3.2.6.2. iSCSI Name Encoding . . . . . . . 31
- 3.2.6.3. iSCSI Name Structure. . . . . . . 32
- 3.2.6.3.1. Type "iqn." (iSCSI
- Qualified Name) . . . 32
- 3.2.6.3.2. Type "eui." (IEEE
- EUI-64 format). . . . 34
- 3.2.7. Persistent State . . . . . . . . . . . . . . 34
- 3.2.8. Message Synchronization and Steering . . . . 35
- 3.2.8.1. Sync/Steering and iSCSI PDU
- Length . . . . . . . . . . . . . 36
- 3.3. iSCSI Session Types. . . . . . . . . . . . . . . . . . 36
- 3.4. SCSI to iSCSI Concepts Mapping Model . . . . . . . . . 37
- 3.4.1. iSCSI Architecture Model . . . . . . . . . . 37
- 3.4.2. SCSI Architecture Model. . . . . . . . . . . 39
- 3.4.3. Consequences of the Model. . . . . . . . . . 41
- 3.4.3.1. I_T Nexus State . . . . . . . . . 42
- 3.5. Request/Response Summary . . . . . . . . . . . . . . . 42
- 3.5.1. Request/Response Types Carrying SCSI Payload 43
- 3.5.1.1. SCSI-Command . . . . . . . . . . 43
-
-
-
-Satran, et al. Standards Track [Page 2]
-
-RFC 3720 iSCSI April 2004
-
-
- 3.5.1.2. SCSI-Response . . . . . . . . . 43
- 3.5.1.3. Task Management Function Request. 44
- 3.5.1.4. Task Management Function Response 44
- 3.5.1.5. SCSI Data-Out and SCSI Data-In. . 44
- 3.5.1.6. Ready To Transfer (R2T) . . . . . 45
- 3.5.2. Requests/Responses carrying SCSI and iSCSI
- Payload. . . . . . . . . . . . . . . . . . . 46
- 3.5.2.1. Asynchronous Message. . . . . . . 46
- 3.5.3. Requests/Responses Carrying iSCSI Only
- Payload. . . . . . . . . . . . . . . . . . . 46
- 3.5.3.1. Text Request and Text Response. . 46
- 3.5.3.2. Login Request and Login Response. 47
- 3.5.3.3. Logout Request and Response . . . 47
- 3.5.3.4. SNACK Request . . . . . . . . . . 48
- 3.5.3.5. Reject. . . . . . . . . . . . . . 48
- 3.5.3.6. NOP-Out Request and NOP-In
- Response . . . . . . . . . . . . 48
- 4. SCSI Mode Parameters for iSCSI. . . . . . . . . . . . . . . . 48
- 5. Login and Full Feature Phase Negotiation. . . . . . . . . . . 48
- 5.1. Text Format. . . . . . . . . . . . . . . . . . . . . . 50
- 5.2. Text Mode Negotiation. . . . . . . . . . . . . . . . . 53
- 5.2.1. List negotiations. . . . . . . . . . . . . . 56
- 5.2.2. Simple-value Negotiations. . . . . . . . . . 56
- 5.3. Login Phase. . . . . . . . . . . . . . . . . . . . . . 57
- 5.3.1. Login Phase Start. . . . . . . . . . . . . . 60
- 5.3.2. iSCSI Security Negotiation . . . . . . . . . 62
- 5.3.3. Operational Parameter Negotiation During
- the Login Phase. . . . . . . . . . . . . . . 63
- 5.3.4. Connection Reinstatement . . . . . . . . . . 64
- 5.3.5. Session Reinstatement, Closure, and Timeout. 64
- 5 5.3.5.1. Loss of Nexus
- Notification. . . . . 65
- 5.3.6. Session Continuation and Failure . . . . . . 65
- 5.4. Operational Parameter Negotiation Outside the Login
- Phase. . . . . . . . . . . . . . . . . . . . . . . . . 66
- 6. iSCSI Error Handling and Recovery . . . . . . . . . . . . . . 67
- 6.1. Overview . . . . . . . . . . . . . . . . . . . . . . . 67
- 6.1.1. Background . . . . . . . . . . . . . . . . . 67
- 6.1.2. Goals. . . . . . . . . . . . . . . . . . . . 67
- 6.1.3. Protocol Features and State Expectations . . 68
- 6.1.4. Recovery Classes . . . . . . . . . . . . . . 69
- 6.1.4.1. Recovery Within-command . . . . . 69
- 6.1.4.2. Recovery Within-connection. . . . 70
- 6.1.4.3. Connection Recovery . . . . . . . 71
- 6.1.4.4. Session Recovery. . . . . . . . . 72
- 6.1.5. Error Recovery Hierarchy . . . . . . . . . . . 72
- 6.2. Retry and Reassign in Recovery . . . . . . . . . . . . 74
- 6.2.1. Usage of Retry . . . . . . . . . . . . . . . 74
-
-
-
-Satran, et al. Standards Track [Page 3]
-
-RFC 3720 iSCSI April 2004
-
-
- 6.2.2. Allegiance Reassignment. . . . . . . . . . . 75
- 6.3. Usage Of Reject PDU in Recovery. . . . . . . . . . . . 76
- 6.4. Connection Timeout Management. . . . . . . . . . . . . 76
- 6.4.1. Timeouts on Transport Exception Events . . . 77
- 6.4.2. Timeouts on Planned Decommissioning. . . . . 77
- 6.5. Implicit Termination of Tasks. . . . . . . . . . . . . 77
- 6.6. Format Errors. . . . . . . . . . . . . . . . . . . . . 78
- 6.7. Digest Errors. . . . . . . . . . . . . . . . . . . . . 78
- 6.8. Sequence Errors. . . . . . . . . . . . . . . . . . . . 80
- 6.9. SCSI Timeouts. . . . . . . . . . . . . . . . . . . . . 81
- 6.10. Negotiation Failures . . . . . . . . . . . . . . . . . 81
- 6.11. Protocol Errors. . . . . . . . . . . . . . . . . . . . 82
- 6.12. Connection Failures. . . . . . . . . . . . . . . . . . 82
- 6.13. Session Errors . . . . . . . . . . . . . . . . . . . . 83
- 7. State Transitions . . . . . . . . . . . . . . . . . . . . . . 84
- 7.1. Standard Connection State Diagrams . . . . . . . . . . 84
- 7.1.1. State Descriptions for Initiators and
- Targets. . . . . . . . . . . . . . . . . . . 84
- 7.1.2. State Transition Descriptions for Initiators
- and Targets. . . . . . . . . . . . . . . . . 85
- 7.1.3. Standard Connection State Diagram for an
- Initiator. . . . . . . . . . . . . . . . . . 88
- 7.1.4. Standard Connection State Diagram for a
- Target . . . . . . . . . . . . . . . . . . . 90
- 7.2. Connection Cleanup State Diagram for Initiators and
- Targets. . . . . . . . . . . . . . . . . . . . . . . . 92
- 7.2.1. State Descriptions for Initiators and
- Targets. . . . . . . . . . . . . . . . . . . 94
- 7.2.2. State Transition Descriptions for Initiators
- and Targets. . . . . . . . . . . . . . . . . 94
- 7.3. Session State Diagrams . . . . . . . . . . . . . . . . 95
- 7.3.1. Session State Diagram for an Initiator . . . 95
- 7.3.2. Session State Diagram for a Target . . . . . 96
- 7.3.3. State Descriptions for Initiators and
- Targets. . . . . . . . . . . . . . . . . . . 97
- 7.3.4. State Transition Descriptions for Initiators
- and Targets. . . . . . . . . . . . . . . . . 98
- 8. Security Considerations . . . . . . . . . . . . . . . . . . . 99
- 8.1. iSCSI Security Mechanisms. . . . . . . . . . . . . . . 100
- 8.2. In-band Initiator-Target Authentication. . . . . . . . 100
- 8.2.1. CHAP Considerations. . . . . . . . . . . . . 101
- 8.2.2. SRP Considerations . . . . . . . . . . . . . 103
- 8.3. IPsec. . . . . . . . . . . . . . . . . . . . . . . . . 104
- 8.3.1. Data Integrity and Authentication. . . . . . 104
- 8.3.2. Confidentiality. . . . . . . . . . . . . . . 105
- 8.3.3. Policy, Security Associations, and
- Cryptographic Key Management . . . . . . . . 105
- 9. Notes to Implementers . . . . . . . . . . . . . . . . . . . . 106
-
-
-
-Satran, et al. Standards Track [Page 4]
-
-RFC 3720 iSCSI April 2004
-
-
- 9.1. Multiple Network Adapters. . . . . . . . . . . . . . . 106
- 9.1.1. Conservative Reuse of ISIDs. . . . . . . . . 107
- 9.1.2. iSCSI Name, ISID, and TPGT Use . . . . . . . 107
- 9.2. Autosense and Auto Contingent Allegiance (ACA) . . . . 109
- 9.3. iSCSI Timeouts . . . . . . . . . . . . . . . . . . . . 109
- 9.4. Command Retry and Cleaning Old Command Instances . . . 110
- 9.5. Synch and Steering Layer and Performance . . . . . . . 110
- 9.6. Considerations for State-dependent Devices and
- Long-lasting SCSI Operations . . . . . . . . . . . . . 111
- 9.6.1. Determining the Proper ErrorRecoveryLevel. . 112
- 10. iSCSI PDU Formats . . . . . . . . . . . . . . . . . . . . . . 112
- 10.1. iSCSI PDU Length and Padding . . . . . . . . . . . . . 113
- 10.2. PDU Template, Header, and Opcodes. . . . . . . . . . . 113
- 10.2.1. Basic Header Segment (BHS) . . . . . . . . . 114
- 10.2.1.1. I . . . . . . . . . . . . . . . . 115
- 10.2.1.2. Opcode. . . . . . . . . . . . . . 115
- 10.2.1.3. Final (F) bit . . . . . . . . . . 116
- 10.2.1.4. Opcode-specific Fields. . . . . . 116
- 10.2.1.5. TotalAHSLength. . . . . . . . . . 116
- 10.2.1.6. DataSegmentLength . . . . . . . . 116
- 10.2.1.7. LUN . . . . . . . . . . . . . . . 116
- 10.2.1.8. Initiator Task Tag. . . . . . . . 117
- 10.2.2. Additional Header Segment (AHS) . . . . . . . 117
- 10.2.2.1. AHSType . . . . . . . . . . . . . 117
- 10.2.2.2. AHSLength . . . . . . . . . . . . 117
- 10.2.2.3. Extended CDB AHS. . . . . . . . . 118
- 10.2.2.4. Bidirectional Expected Read-Data
- Length AHS. . . . . . . . . . . . 118
- 10.2.3. Header Digest and Data Digest. . . . . . . . 118
- 10.2.4. Data Segment . . . . . . . . . . . . . . . . 119
- 10.3. SCSI Command . . . . . . . . . . . . . . . . . . . . . 119
- 10.3.1. Flags and Task Attributes (byte 1) . . . . . 120
- 10.3.2. CmdSN - Command Sequence Number. . . . . . . 120
- 10.3.3. ExpStatSN. . . . . . . . . . . . . . . . . . 120
- 10.3.4. Expected Data Transfer Length. . . . . . . . 121
- 10.3.5. CDB - SCSI Command Descriptor Block. . . . . 121
- 10.3.6. Data Segment - Command Data. . . . . . . . . 121
- 10.4. SCSI Response. . . . . . . . . . . . . . . . . . . . . 122
- 10.4.1. Flags (byte 1) . . . . . . . . . . . . . . . 123
- 10.4.2. Status . . . . . . . . . . . . . . . . . . . 123
- 10.4.3. Response . . . . . . . . . . . . . . . . . . 124
- 10.4.4. SNACK Tag. . . . . . . . . . . . . . . . . . 125
- 10.4.5. Residual Count . . . . . . . . . . . . . . . 125
- 10.4.6. Bidirectional Read Residual Count. . . . . . 125
- 10.4.7. Data Segment - Sense and Response Data
- Segment. . . . . . . . . . . . . . . . . . . 125
- 10.4.7.1. SenseLength . . . . . . . . . . . 126
- 10.4.7.2. Sense Data. . . . . . . . . . . . 126
-
-
-
-Satran, et al. Standards Track [Page 5]
-
-RFC 3720 iSCSI April 2004
-
-
- 10.4.8. ExpDataSN. . . . . . . . . . . . . . . . . . 127
- 10.4.9. StatSN - Status Sequence Number. . . . . . . 127
- 10.4.10. ExpCmdSN - Next Expected CmdSN from this
- Initiator. . . . . . . . . . . . . . . . . . 128
- 10.4.11. MaxCmdSN - Maximum CmdSN from this Initiator 128
- 10.5. Task Management Function Request . . . . . . . . . . . 129
- 10.5.1. Function . . . . . . . . . . . . . . . . . . 129
- 10.5.2. TotalAHSLength and DataSegmentLength . . . . 132
- 10.5.3. LUN. . . . . . . . . . . . . . . . . . . . . 132
- 10.5.4. Referenced Task Tag. . . . . . . . . . . . . 132
- 10.5.5. RefCmdSN . . . . . . . . . . . . . . . . . . 132
- 10.5.6. ExpDataSN. . . . . . . . . . . . . . . . . . 133
- 10.6. Task Management Function Response. . . . . . . . . . . 134
- 10.6.1. Response . . . . . . . . . . . . . . . . . . 134
- 10.6.2. Task Management Actions on Task Sets . . . . 136
- 10.6.3. TotalAHSLength and DataSegmentLength . . . . 137
- 10.7. SCSI Data-Out & SCSI Data-In . . . . . . . . . . . . . 137
- 10.7.1. F (Final) Bit. . . . . . . . . . . . . . . . 139
- 10.7.2. A (Acknowledge) Bit. . . . . . . . . . . . . 139
- 10.7.3. Flags (byte 1) . . . . . . . . . . . . . . . 140
- 10.7.4. Target Transfer Tag and LUN. . . . . . . . . 140
- 10.7.5. DataSN . . . . . . . . . . . . . . . . . . . 141
- 10.7.6. Buffer Offset. . . . . . . . . . . . . . . . 141
- 10.7.7. DataSegmentLength. . . . . . . . . . . . . . 141
- 10.8. Ready To Transfer (R2T). . . . . . . . . . . . . . . . 142
- 10.8.1. TotalAHSLength and DataSegmentLength . . . . 143
- 10.8.2. R2TSN. . . . . . . . . . . . . . . . . . . . 143
- 10.8.3. StatSN . . . . . . . . . . . . . . . . . . . 144
- 10.8.4. Desired Data Transfer Length and Buffer
- Offset . . . . . . . . . . . . . . . . . . . 144
- 10.8.5. Target Transfer Tag. . . . . . . . . . . . . 144
- 10.9. Asynchronous Message . . . . . . . . . . . . . . . . . 145
- 10.9.1. AsyncEvent . . . . . . . . . . . . . . . . . 146
- 10.9.2. AsyncVCode . . . . . . . . . . . . . . . . . 147
- 10.9.3. LUN. . . . . . . . . . . . . . . . . . . . . 147
- 10.9.4. Sense Data and iSCSI Event Data. . . . . . . 148
- 10.9.4.1. SenseLength . . . . . . . . . . . 148
- 10.10. Text Request . . . . . . . . . . . . . . . . . . . . . 149
- 10.10.1. F (Final) Bit. . . . . . . . . . . . . . . . 150
- 10.10.2. C (Continue) Bit . . . . . . . . . . . . . . 150
- 10.10.3. Initiator Task Tag . . . . . . . . . . . . . 150
- 10.10.4. Target Transfer Tag. . . . . . . . . . . . . 150
- 10.10.5. Text . . . . . . . . . . . . . . . . . . . . 151
- 10.11. Text Response. . . . . . . . . . . . . . . . . . . . . 152
- 10.11.1. F (Final) Bit. . . . . . . . . . . . . . . . 152
- 10.11.2. C (Continue) Bit . . . . . . . . . . . . . . 153
- 10.11.3. Initiator Task Tag . . . . . . . . . . . . . 153
- 10.11.4. Target Transfer Tag. . . . . . . . . . . . . 153
-
-
-
-Satran, et al. Standards Track [Page 6]
-
-RFC 3720 iSCSI April 2004
-
-
- 10.11.5. StatSN . . . . . . . . . . . . . . . . . . . 154
- 10.11.6. Text Response Data . . . . . . . . . . . . . 154
- 10.12. Login Request. . . . . . . . . . . . . . . . . . . . . 154
- 10.12.1. T (Transit) Bit. . . . . . . . . . . . . . . 155
- 10.12.2. C (Continue) Bit . . . . . . . . . . . . . . 155
- 10.12.3. CSG and NSG. . . . . . . . . . . . . . . . . 156
- 10.12.4. Version. . . . . . . . . . . . . . . . . . . 156
- 10.12.4.1. Version-max. . . . . . . . . . . 156
- 10.12.4.2. Version-min. . . . . . . . . . . 156
- 10.12.5. ISID . . . . . . . . . . . . . . . . . . . . 157
- 10.12.6. TSIH . . . . . . . . . . . . . . . . . . . . 158
- 10.12.7. Connection ID - CID. . . . . . . . . . . . . 158
- 10.12.8. CmdSN. . . . . . . . . . . . . . . . . . . . 159
- 10.12.9. ExpStatSN. . . . . . . . . . . . . . . . . . 159
- 10.12.10. Login Parameters . . . . . . . . . . . . . . 159
- 10.13. Login Response . . . . . . . . . . . . . . . . . . . . 160
- 10.13.1. Version-max. . . . . . . . . . . . . . . . . 160
- 10.13.2. Version-active . . . . . . . . . . . . . . . 161
- 10.13.3. TSIH . . . . . . . . . . . . . . . . . . . . 161
- 10.13.4. StatSN . . . . . . . . . . . . . . . . . . . 161
- 10.13.5. Status-Class and Status-Detail . . . . . . . 161
- 10.13.6. T (Transit) Bit. . . . . . . . . . . . . . . 164
- 10.13.7. C (Continue) Bit . . . . . . . . . . . . . . 164
- 10.13.8. Login Parameters . . . . . . . . . . . . . . 164
- 10.14. Logout Request . . . . . . . . . . . . . . . . . . . . 165
- 10.14.1. Reason Code. . . . . . . . . . . . . . . . . 167
- 10.14.2. TotalAHSLength and DataSegmentLength . . . . 168
- 10.14.3. CID. . . . . . . . . . . . . . . . . . . . . 168
- 10.14.4. ExpStatSN. . . . . . . . . . . . . . . . . . 168
- 10.14.5. Implicit termination of tasks. . . . . . . . 168
- 10.15. Logout Response. . . . . . . . . . . . . . . . . . . . 169
- 10.15.1. Response . . . . . . . . . . . . . . . . . . 170
- 10.15.2. TotalAHSLength and DataSegmentLength . . . . 170
- 10.15.3. Time2Wait. . . . . . . . . . . . . . . . . . 170
- 10.15.4. Time2Retain. . . . . . . . . . . . . . . . . 170
- 10.16. SNACK Request. . . . . . . . . . . . . . . . . . . . . 171
- 10.16.1. Type . . . . . . . . . . . . . . . . . . . . 172
- 10.16.2. Data Acknowledgement . . . . . . . . . . . . 173
- 10.16.3. Resegmentation . . . . . . . . . . . . . . . 173
- 10.16.4. Initiator Task Tag . . . . . . . . . . . . . 174
- 10.16.5. Target Transfer Tag or SNACK Tag . . . . . . 174
- 10.16.6. BegRun . . . . . . . . . . . . . . . . . . . 174
- 10.16.7. RunLength. . . . . . . . . . . . . . . . . . 174
- 10.17. Reject . . . . . . . . . . . . . . . . . . . . . . . . 175
- 10.17.1. Reason . . . . . . . . . . . . . . . . . . . 176
- 10.17.2. DataSN/R2TSN . . . . . . . . . . . . . . . . 177
- 10.17.3. StatSN, ExpCmdSN and MaxCmdSN. . . . . . . . 177
- 10.17.4. Complete Header of Bad PDU . . . . . . . . . 177
-
-
-
-Satran, et al. Standards Track [Page 7]
-
-RFC 3720 iSCSI April 2004
-
-
- 10.18. NOP-Out. . . . . . . . . . . . . . . . . . . . . . . . 178
- 10.18.1. Initiator Task Tag . . . . . . . . . . . . . 179
- 10.18.2. Target Transfer Tag. . . . . . . . . . . . . 179
- 10.18.3. Ping Data. . . . . . . . . . . . . . . . . . 179
- 10.19. NOP-In . . . . . . . . . . . . . . . . . . . . . . . . 180
- 10.19.1. Target Transfer Tag. . . . . . . . . . . . . 181
- 10.19.2. StatSN . . . . . . . . . . . . . . . . . . . 181
- 10.19.3. LUN. . . . . . . . . . . . . . . . . . . . . 181
- 11. iSCSI Security Text Keys and Authentication Methods . . . . . 181
- 11.1. AuthMethod . . . . . . . . . . . . . . . . . . . . . . 182
- 11.1.1. Kerberos . . . . . . . . . . . . . . . . . . 184
- 11.1.2. Simple Public-Key Mechanism (SPKM) . . . . . 184
- 11.1.3. Secure Remote Password (SRP) . . . . . . . . 185
- 11.1.4. Challenge Handshake Authentication Protocol
- (CHAP) . . . . . . . . . . . . . . . . . . . 186
- 12. Login/Text Operational Text Keys. . . . . . . . . . . . . . . 187
- 12.1. HeaderDigest and DataDigest. . . . . . . . . . . . . . 188
- 12.2. MaxConnections . . . . . . . . . . . . . . . . . . . . 190
- 12.3. SendTargets. . . . . . . . . . . . . . . . . . . . . . 191
- 12.4. TargetName . . . . . . . . . . . . . . . . . . . . . . 191
- 12.5. InitiatorName. . . . . . . . . . . . . . . . . . . . . 192
- 12.6. TargetAlias. . . . . . . . . . . . . . . . . . . . . . 192
- 12.7. InitiatorAlias . . . . . . . . . . . . . . . . . . . . 193
- 12.8. TargetAddress. . . . . . . . . . . . . . . . . . . . . 193
- 12.9. TargetPortalGroupTag . . . . . . . . . . . . . . . . . 194
- 12.10. InitialR2T . . . . . . . . . . . . . . . . . . . . . . 194
- 12.11. ImmediateData. . . . . . . . . . . . . . . . . . . . . 195
- 12.12. MaxRecvDataSegmentLength . . . . . . . . . . . . . . . 196
- 12.13. MaxBurstLength . . . . . . . . . . . . . . . . . . . . 196
- 12.14. FirstBurstLength . . . . . . . . . . . . . . . . . . . 197
- 12.15. DefaultTime2Wait . . . . . . . . . . . . . . . . . . . 197
- 12.16. DefaultTime2Retain . . . . . . . . . . . . . . . . . . 198
- 12.17. MaxOutstandingR2T. . . . . . . . . . . . . . . . . . . 198
- 12.18. DataPDUInOrder . . . . . . . . . . . . . . . . . . . . 198
- 12.19. DataSequenceInOrder. . . . . . . . . . . . . . . . . . 199
- 12.20. ErrorRecoveryLevel . . . . . . . . . . . . . . . . . . 199
- 12.21. SessionType. . . . . . . . . . . . . . . . . . . . . . 200
- 12.22. The Private or Public Extension Key Format . . . . . . 200
- 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 201
- 13.1. Naming Requirements. . . . . . . . . . . . . . . . . . 203
- 13.2. Mechanism Specification Requirements . . . . . . . . . 203
- 13.3. Publication Requirements . . . . . . . . . . . . . . . 203
- 13.4. Security Requirements. . . . . . . . . . . . . . . . . 203
- 13.5. Registration Procedure . . . . . . . . . . . . . . . . 204
- 13.5.1. Present the iSCSI extension item to the
- Community. . . . . . . . . . . . . . . . . . 204
- 13.5.2. iSCSI extension item review and IESG
- approval . . . . . . . . . . . . . . . . . . 204
-
-
-
-Satran, et al. Standards Track [Page 8]
-
-RFC 3720 iSCSI April 2004
-
-
- 13.5.3. IANA Registration. . . . . . . . . . . . . . 204
- 13.5.4. Standard iSCSI extension item-label format . 204
- 13.6. IANA Procedures for Registering iSCSI extension items. 205
- References. . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
- Appendix A. Sync and Steering with Fixed Interval Markers . . . . 209
- A.1. Markers At Fixed Intervals . . . . . . . . . . . . . . 209
- A.2. Initial Marker-less Interval . . . . . . . . . . . . . 210
- A.3. Negotiation. . . . . . . . . . . . . . . . . . . . . . 210
- A.3.1. OFMarker, IFMarker . . . . . . . . . . . . . 210
- A.3.2. OFMarkInt, IFMarkInt . . . . . . . . . . . . 211
- Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 212
- B.1. Read Operation Example . . . . . . . . . . . . . . . . 212
- B.2. Write Operation Example. . . . . . . . . . . . . . . . 213
- B.3. R2TSN/DataSN Use Examples. . . . . . . . . . . . . . . 214
- B.4. CRC Examples . . . . . . . . . . . . . . . . . . . . . 217
- Appendix C. Login Phase Examples . . . . . . . . . . . . . . . . 219
- Appendix D. SendTargets Operation. . . . . . . . . . . . . . . . 229
- Appendix E. Algorithmic Presentation of Error Recovery Classes . 233
- E.1. General Data Structure and Procedure Description . . . 233
- E.2. Within-command Error Recovery Algorithms . . . . . . . 234
- E.2.1. Procedure Descriptions . . . . . . . . . . . 234
- E.2.2. Initiator Algorithms . . . . . . . . . . . . 235
- E.2.3. Target Algorithms. . . . . . . . . . . . . . 237
- E.3. Within-connection Recovery Algorithms. . . . . . . . . 240
- E.3.1. Procedure Descriptions . . . . . . . . . . . 240
- E.3.2. Initiator Algorithms . . . . . . . . . . . . 241
- E.3.3. Target Algorithms. . . . . . . . . . . . . . 243
- E.4. Connection Recovery Algorithms . . . . . . . . . . . . 243
- E.4.1. Procedure Descriptions . . . . . . . . . . . 243
- E.4.2. Initiator Algorithms . . . . . . . . . . . . 244
- E.4.3. Target Algorithms. . . . . . . . . . . . . . 246
- Appendix F. Clearing Effects of Various Events on Targets. . . . 249
- F.1. Clearing Effects on iSCSI Objects. . . . . . . . . . . 249
- F.2. Clearing Effects on SCSI Objects . . . . . . . . . . . 253
- Acknowledgements. . . . . . . . . . . . . . . . . . . . . . . . . 254
- Authors' Addresses. . . . . . . . . . . . . . . . . . . . . . . . 256
- Full Copyright Statement. . . . . . . . . . . . . . . . . . . . . 257
-
-1. Introduction
-
- The Small Computer Systems Interface (SCSI) is a popular family of
- protocols for communicating with I/O devices, especially storage
- devices. SCSI is a client-server architecture. Clients of a SCSI
- interface are called "initiators". Initiators issue SCSI "commands"
- to request services from components, logical units of a server known
- as a "target". A "SCSI transport" maps the client-server SCSI
- protocol to a specific interconnect. An Initiator is one endpoint of
- a SCSI transport and a target is the other endpoint.
-
-
-
-Satran, et al. Standards Track [Page 9]
-
-RFC 3720 iSCSI April 2004
-
-
- The SCSI protocol has been mapped over various transports, including
- Parallel SCSI, IPI, IEEE-1394 (firewire) and Fibre Channel. These
- transports are I/O specific and have limited distance capabilities.
-
- The iSCSI protocol defined in this document describes a means of
- transporting SCSI packets over TCP/IP (see [RFC791], [RFC793],
- [RFC1035], [RFC1122]), providing for an interoperable solution which
- can take advantage of existing Internet infrastructure, Internet
- management facilities, and address distance limitations.
-
-2. Definitions and Acronyms
-
-2.1. Definitions
-
- - Alias: An alias string can 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.
-
- - CID (Connection ID): Connections within a session are identified by
- a connection ID. It is a unique ID for this connection within the
- session for the initiator. It is generated by the initiator and
- presented to the target during login requests and during logouts
- that close connections.
-
- - Connection: A connection is a TCP connection. Communication
- between the initiator and target occurs over one or more TCP
- connections. The TCP connections carry control messages, SCSI
- commands, parameters, and data within iSCSI Protocol Data Units
- (iSCSI PDUs).
-
- - iSCSI Device: A SCSI Device using an iSCSI service delivery
- subsystem. Service Delivery Subsystem is defined by [SAM2] as a
- transport mechanism for SCSI commands and responses.
-
- - iSCSI Initiator Name: The iSCSI Initiator Name specifies the
- worldwide unique name of the initiator.
-
- - iSCSI Initiator Node: The "initiator". The word "initiator" has
- been appropriately qualified as either a port or a device in the
- rest of the document when the context is ambiguous. All
- unqualified usages of "initiator" refer to an initiator port (or
- device) depending on the context.
-
- - iSCSI Layer: This layer builds/receives iSCSI PDUs and
- relays/receives them to/from one or more TCP connections that form
- an initiator-target "session".
-
-
-
-
-Satran, et al. Standards Track [Page 10]
-
-RFC 3720 iSCSI April 2004
-
-
- - iSCSI Name: The name of an iSCSI initiator or iSCSI target.
-
- - iSCSI Node: The iSCSI Node represents a single iSCSI initiator or
- iSCSI target. There are one or more iSCSI Nodes within a Network
- Entity. The iSCSI Node is accessible via one or more Network
- Portals. An iSCSI Node is identified by its iSCSI Name. The
- separation of the iSCSI Name from the addresses used by and for the
- iSCSI Node allows multiple iSCSI Nodes to use the same address, and
- the same iSCSI Node to use multiple addresses.
-
- - iSCSI Target Name: The iSCSI Target Name specifies the worldwide
- unique name of the target.
-
- - iSCSI Target Node: The "target".
-
- - iSCSI Task: An iSCSI task is an iSCSI request for which a response
- is expected.
-
- - iSCSI Transfer Direction: The iSCSI transfer direction is defined
- with regard to the initiator. Outbound or outgoing transfers are
- transfers from the initiator to the target, while inbound or
- incoming transfers are from the target to the initiator.
-
- - ISID: The initiator part of the Session Identifier. It is
- explicitly specified by the initiator 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,
- 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; that is, the I_T nexus
- identifier is the tuple (iSCSI Initiator Name + ',i,'+ ISID, iSCSI
- Target Name + ',t,'+ Portal Group Tag).
-
- - Network Entity: The Network Entity represents a device or gateway
- that is accessible from the IP network. A Network Entity must have
- one or more Network Portals, each of which can be used to gain
- access to the IP network by some iSCSI Nodes contained in that
- Network Entity.
-
- - Network Portal: The Network Portal 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. A Network Portal in an initiator is
- identified by its IP address. A Network Portal in a target is
- identified by its IP address and its listening TCP port.
-
-
-
-
-Satran, et al. Standards Track [Page 11]
-
-RFC 3720 iSCSI April 2004
-
-
- - Originator: In a negotiation or exchange, the party that initiates
- the negotiation or exchange.
-
- - PDU (Protocol Data Unit): The initiator and target divide their
- communications into messages. The term "iSCSI protocol data unit"
- (iSCSI PDU) is used for these messages.
-
- - 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 Network
- Entity that collectively supports the capability of coordinating a
- session with connections spanning these portals. Not all Network
- Portals within a Portal Group need 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 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: An R2T generated by a target upon detecting the loss
- of one or more Data-Out PDUs through one of the following means: a
- digest error, a sequence error, or a sequence reception timeout. A
- recovery R2T carries the next unused R2TSN, but requests all or
- part of the data burst that an earlier R2T (with a lower R2TSN) had
- already requested.
-
- - Responder: In a negotiation or exchange, the party that responds to
- the originator of the negotiation or exchange.
-
- - SCSI Device: This is the SAM2 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 Target Device contains one or
- more SCSI Target Ports and one or more device servers and
- associated logical units. 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 a given iSCSI Node. Access to the SCSI Device can only be
- achieved in an iSCSI normal operational session. The SCSI Device
- Name is defined to be the iSCSI Name of the node.
-
-
-
-
-
-Satran, et al. Standards Track [Page 12]
-
-RFC 3720 iSCSI April 2004
-
-
- - SCSI Layer: This builds/receives SCSI CDBs (Command Descriptor
- Blocks) and relays/receives them with the remaining command execute
- [SAM2] parameters to/from the iSCSI Layer.
-
- - Session: The group of TCP connections that link an initiator with a
- target form a session (loosely equivalent to a SCSI I-T nexus).
- TCP connections can be added and removed from a session. Across
- all connections within a session, an initiator sees one and the
- same target.
-
- - SCSI Initiator Port: This maps to the endpoint of an iSCSI normal
- operational session. 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 Port: This is the SAM2 term for an entity in a SCSI Device
- that provides the SCSI functionality to interface with a service
- delivery subsystem. For iSCSI, the definition of the SCSI
- Initiator Port and the SCSI Target Port are different.
-
- - SCSI Port Name: A name made up as UTF-8 [RFC2279] characters and
- includes the iSCSI Name + 'i' or 't' + ISID or Portal Group Tag.
-
-
- - SCSI Target Port: This maps to an iSCSI Target Portal Group.
-
- - SCSI Target Port Name and SCSI Target Port Identifier: These 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
- portal group tag.
-
- - SSID (Session ID): A session between an iSCSI initiator and an
- iSCSI target is defined by a session ID that is a tuple composed of
- an initiator part (ISID) and a target part (Target Portal Group
- Tag). The ISID is explicitly specified by the initiator at session
- establishment. The Target Portal Group Tag is implied by the
- initiator through the selection of the TCP endpoint at connection
- establishment. The TargetPortalGroupTag key must also be returned
- by the target as a confirmation during connection establishment
- when TargetName is given.
-
- - Target Portal Group Tag: A numerical identifier (16-bit) for an
- iSCSI Target Portal Group.
-
-
-
-Satran, et al. Standards Track [Page 13]
-
-RFC 3720 iSCSI April 2004
-
-
- - TSIH (Target Session Identifying Handle): A target assigned tag for
- a session with a specific named initiator. The target generates it
- during session establishment. Its internal format and content are
- not defined by this protocol, except for the value 0 that is
- reserved and used by the initiator to indicate a new session. It
- is given to the target during additional connection establishment
- for the same session.
-
-2.2. Acronyms
-
- 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
- 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
- ESP Encapsulating Security Payload
- EUI Extended Unique Identifier
- FFP Full Feature Phase
- FFPO Full Feature Phase Only
- FIM Fixed Interval Marker
- Gbps Gigabits per Second
- HBA Host Bus Adapter
- HMAC Hashed Message Authentication Code
- I_T Initiator_Target
- I_T_L Initiator_Target_LUN
- IANA Internet Assigned Numbers Authority
-
-
-
-Satran, et al. Standards Track [Page 14]
-
-RFC 3720 iSCSI April 2004
-
-
- ID Identifier
- IDN Internationalized Domain Name
- IEEE Institute of Electrical & 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
- ISID Initiator Session ID
- 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 Codes
- NA Not Applicable
- NIC Network Interface Card
- NOP No Operation
- NSG Next Stage
- 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
- SAM SCSI Architecture Model
- SAM2 SCSI Architecture Model - 2
- SAN Storage Area Network
- SCSI Small Computer Systems Interface
- SN Sequence Number
- SNACK Selective Negative Acknowledgment - also
- Sequence Number Acknowledgement for data
- SPKM Simple Public-Key Mechanism
- SRP Secure Remote Password
- SSID Session ID
- SW Session Wide
- TCB Task Control Block
- TCP Transmission Control Protocol
- TPGT Target Portal Group Tag
- TSIH Target Session Identifying Handle
-
-
-
-Satran, et al. Standards Track [Page 15]
-
-RFC 3720 iSCSI April 2004
-
-
- TTT Target Transfer Tag
- UFL Upper Functional Layer
- ULP Upper Level Protocol
- URN Uniform Resource Names [RFC2396]
- UTF Universal Transformation Format
- WG Working Group
-
-2.3. 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 BCP 14 [RFC2119].
-
- iSCSI messages - PDUs - are represented by diagrams as in the
- following example:
-
- 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) |
- +---------------+---------------+---------------+---------------+
- ----------
- +| |
- +---------------+---------------+---------------+---------------+
-
- The diagrams include byte and bit numbering.
-
- The following representation and ordering rules are observed in this
- document:
-
- - Word Rule
- - Half-word Rule
- - Byte Rule
-
-2.3.1. Word Rule
-
- A word holds four consecutive bytes. Whenever a word has numeric
- content, it is considered an unsigned number in base 2 positional
- representation with the lowest numbered byte (e.g., byte 0) bit 0
- representing 2**31 and bit 1 representing 2**30 through lowest
- numbered byte + 3 (e.g., byte 3) bit 7 representing 2**0.
-
- Decimal and hexadecimal representation of word values map this
- representation to decimal or hexadecimal positional notation.
-
-
-
-Satran, et al. Standards Track [Page 16]
-
-RFC 3720 iSCSI April 2004
-
-
-2.3.2. Half-Word Rule
-
- A half-word holds two consecutive bytes. Whenever a half-word has
- numeric content it is considered an unsigned number in base 2
- positional representation with the lowest numbered byte (e.g., byte
- 0), bit 0 representing 2**15 and bit 1 representing 2**14 through
- lowest numbered byte + 1 (e.g., byte 1), bit 7 representing 2**0.
-
- Decimal and hexadecimal representation of half-word values map this
- representation to decimal or hexadecimal positional notation.
-
-2.3.3. Byte Rule
-
- For every PDU, bytes are sent and received in increasing numbered
- order (network order).
-
- Whenever a byte has numerical content, it is considered an unsigned
- number in base 2 positional representation with bit 0 representing
- 2**7 and bit 1 representing 2**6 through bit 7 representing 2**0.
-
-3. Overview
-
-3.1. SCSI Concepts
-
- The SCSI Architecture Model-2 [SAM2] describes in detail the
- architecture of the SCSI family of I/O protocols. This section
- provides a brief background of the SCSI architecture and is intended
- to familiarize readers with its terminology.
-
- At the highest level, SCSI is a family of interfaces for requesting
- services from I/O devices, including 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". Initiators issue SCSI "commands" to request
- services from components, logical units, of a server known as a
- "target". The "device server" on the logical unit accepts SCSI
- commands and processes them.
-
- A "SCSI transport" maps the client-server SCSI protocol to a specific
- interconnect. Initiators are one endpoint of a SCSI transport. The
- "target" is the other endpoint. A target can contain multiple
- Logical Units (LUs). Each Logical Unit 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
-
-
-
-Satran, et al. Standards Track [Page 17]
-
-RFC 3720 iSCSI April 2004
-
-
- queue of tasks is managed by the logical unit. The target uses an
- initiator provided "task tag" to distinguish between tasks. Only one
- command in a task can be outstanding at any given time.
-
- 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 target (e.g., WRITE), target to initiator (e.g., READ),
- or in both directions. In the response phase, the target returns the
- final status of the operation, including any errors.
-
- Command Descriptor Blocks (CDB) are the data structures used to
- contain the command parameters that an initiator sends to a target.
- The CDB content and structure is defined by [SAM2] and device-type
- specific SCSI standards.
-
-3.2. iSCSI Concepts and Functional Overview
-
- The iSCSI protocol is a mapping of the SCSI remote procedure
- invocation 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 iSCSI protocol mechanisms.
-
- For the remainder of this document, the terms "initiator" and
- "target" refer to "iSCSI initiator node" and "iSCSI target node",
- respectively (see Section 3.4.1 iSCSI Architecture Model) unless
- otherwise qualified.
-
- 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.
-
- 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.
-
-
-
-
-Satran, et al. Standards Track [Page 18]
-
-RFC 3720 iSCSI April 2004
-
-
-3.2.1. Layers and Sessions
-
- The following conceptual layering model is used to specify initiator
- and target actions and the way in which they relate to transmitted
- and received Protocol Data Units:
-
- a) the SCSI layer builds/receives SCSI CDBs (Command Descriptor
- Blocks) and passes/receives them with the remaining command
- execute parameters ([SAM2]) to/from
-
- b) 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 occurs 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 (loosely equivalent to a SCSI I_T nexus,
- see Section 3.4.2 SCSI Architecture Model). A session is defined by
- a session ID that is composed 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 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 regardless
- of the connection on which they are sent or received.
-
- 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.
-
-3.2.2. Ordering and iSCSI Numbering
-
- iSCSI uses Command and Status numbering schemes and a Data sequencing
- scheme.
-
- 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.
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 19]
-
-RFC 3720 iSCSI April 2004
-
-
- 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 (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/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 an ordered command delivery from the
- SCSI initiator to the SCSI target. For detailed design
- considerations that led to the iSCSI session model as it is defined
- here and how it relates the SCSI command ordering features defined in
- SCSI specifications to the iSCSI concepts see [CORD].
-
-3.2.2.1. Command Numbering and Acknowledging
-
- iSCSI performs ordered command delivery within a session. All
- commands (initiator-to-target PDUs) in transit from the initiator to
- the target are numbered.
-
- iSCSI considers a task to be instantiated on the target in response
- to every request issued by the initiator. A set of task management
- operations including abort and reassign (see Section 10.5 Task
- Management Function Request) may be performed on any iSCSI task.
-
- Some iSCSI tasks are SCSI tasks, and many SCSI activities are related
- to a SCSI task ([SAM2]). In all cases, the task is identified by the
- Initiator Task Tag for the life of the task.
-
- The command number is carried by the iSCSI PDU as CmdSN
- (Command Sequence Number). The numbering is session-wide. Outgoing
- iSCSI PDUs carry this number. The iSCSI initiator allocates CmdSNs
- with a 32-bit unsigned counter (modulo 2**32). Comparisons and
- arithmetic on CmdSN use Serial Number Arithmetic as defined in
- [RFC1982] where SERIAL_BITS = 32.
-
- Commands meant for immediate delivery are marked with an immediate
- delivery flag; they MUST also carry the current CmdSN. CmdSN does
- not advance after a command marked for immediate delivery is sent.
-
-
-
-
-
-Satran, et al. Standards Track [Page 20]
-
-RFC 3720 iSCSI April 2004
-
-
- Command numbering starts with the first login request on the first
- connection of a session (the leading login on the leading connection)
- and command numbers are incremented by 1 for every non-immediate
- command issued afterwards.
-
- If immediate delivery is used with task management commands, these
- commands may reach the target before the tasks on which they are
- supposed to act. However their CmdSN serves as a marker of their
- position in the stream of commands. The initiator and target must
- ensure that the task management commands act as specified by [SAM2].
- For example, both commands and responses appear as if delivered in
- order. Whenever CmdSN for an outgoing PDU is not specified by an
- explicit rule, CmdSN will carry the current value of the local CmdSN
- variable (see later in this section).
-
- The means by which an implementation decides to mark a PDU for
- immediate delivery or by which iSCSI decides by itself to mark a PDU
- for immediate delivery are beyond the scope of this document.
-
- The number of commands used for immediate delivery is not limited and
- their delivery for execution is not acknowledged through the
- numbering scheme. Immediate commands MAY be rejected by the iSCSI
- target layer due to a lack of resources. 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 an iSCSI protocol specific execution engine
- (e.g., for text requests with public or private extension keys
- involving an execution component). With the exception of the
- commands marked for immediate delivery, the iSCSI target layer MUST
- deliver the commands for execution in the order specified by CmdSN.
- Commands marked for immediate delivery may be delivered by the iSCSI
- target layer for execution as soon as detected. iSCSI may avoid
- delivering some commands to the SCSI target layer if required by a
- prior SCSI or iSCSI action (e.g., CLEAR TASK SET Task Management
- request received before all the commands on which it was supposed to
- act).
-
- On any connection, the iSCSI initiator MUST send the 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 maintain the
- following three variables for each session:
-
-
-
-
-
-Satran, et al. Standards Track [Page 21]
-
-RFC 3720 iSCSI April 2004
-
-
- - CmdSN - the current command Sequence Number, advanced by 1 on
- each command shipped except for commands marked for immediate
- delivery. CmdSN always contains the number to be assigned to
- the next Command PDU.
- - ExpCmdSN - the next expected command by the target. The target
- acknowledges all commands up to, but not including, this
- number. The initiator treats all commands with CmdSN less than
- ExpCmdSN as acknowledged. The target iSCSI layer sets the
- ExpCmdSN to the largest non-immediate CmdSN that it can deliver
- for execution plus 1 (no holes in the CmdSN sequence).
- - MaxCmdSN - the maximum number to be shipped. The queuing
- capacity of the receiving iSCSI layer is MaxCmdSN - 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 non-
- immediate duplicates within the range. The CmdSN carried by
- immediate commands may lie outside the ExpCmdSN to MaxCmdSN range.
- For example, if the initiator has previously sent a non-immediate
- command carrying the CmdSN equal to MaxCmdSN, the target window is
- closed. For group task management commands issued as immediate
- commands, CmdSN indicates the scope of the group action (e.g., on
- ABORT TASK SET indicates which commands are aborted).
-
- MaxCmdSN and ExpCmdSN fields are processed by the initiator as
- follows:
-
- - If the PDU MaxCmdSN is less than the PDU ExpCmdSN-1 (in Serial
- Arithmetic Sense), they are both ignored.
- - If the PDU MaxCmdSN is greater than the local MaxCmdSN (in
- Serial Arithmetic Sense), it updates the local MaxCmdSN;
- otherwise, it is ignored.
- - If the PDU ExpCmdSN is greater than the local ExpCmdSN (in
- Serial Arithmetic Sense), it updates the local ExpCmdSN;
- otherwise, it is ignored.
-
- This sequence is required because updates may arrive out of order
- (e.g., the updates are sent on different TCP connections).
-
- iSCSI initiators and targets MUST support the command numbering
- scheme.
-
-
-
-Satran, et al. Standards Track [Page 22]
-
-RFC 3720 iSCSI April 2004
-
-
- A numbered iSCSI request will not change its allocated CmdSN,
- regardless of the number of times and circumstances in which it is
- reissued (see Section 6.2.1 Usage of Retry). At the target, CmdSN is
- only relevant when the command has not created any state related to
- its execution (execution state); afterwards, CmdSN becomes
- irrelevant. Testing for the execution state (represented by
- identifying the Initiator Task Tag) MUST precede any other action at
- the target. If no execution state is found, it is followed by
- ordering and delivery. If an execution state is found, it is
- followed by delivery.
-
- If an initiator issues a command retry for a command with CmdSN R on
- a connection when the session CmdSN value is Q, it MUST NOT advance
- the CmdSN past R + 2**31 -1 unless the connection is no longer
- operational (i.e., it has returned to the FREE state, see Section
- 7.1.3 Standard Connection State Diagram for an Initiator), the
- connection has been reinstated (see Section 5.3.4 Connection
- Reinstatement), or a non-immediate command with CmdSN equal or
- greater than Q was issued subsequent to the command retry on the same
- connection and the reception of that command is acknowledged by the
- target (see Section 9.4 Command Retry and Cleaning Old Command
- Instances).
-
- A target MUST NOT issue a command response or Data-In PDU with status
- before acknowledging the command. However, the acknowledgement can
- be included in the response or Data-In PDU.
-
-3.2.2.2. Response/Status Numbering and Acknowledging
-
- Responses in transit from the target to the initiator are numbered.
- The StatSN (Status Sequence Number) is used for this purpose. StatSN
- is a counter maintained per connection. ExpStatSN is used by the
- initiator to acknowledge status. The status sequence number space is
- 32-bit unsigned-integers and the arithmetic operations are the
- 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 (any initial value is valid).
-
- To enable command recovery, the target MAY maintain enough state
- information for data and status recovery after a connection failure.
- A target doing so can safely discard all of the state information
- maintained for recovery of a command after the delivery of the status
- for the command (numbered StatSN) is acknowledged through ExpStatSN.
-
- A large absolute difference between StatSN and ExpStatSN may indicate
- a failed connection. Initiators MUST undertake recovery actions if
-
-
-
-Satran, et al. Standards Track [Page 23]
-
-RFC 3720 iSCSI April 2004
-
-
- the difference is greater than an implementation defined constant
- that MUST NOT exceed 2**31-1.
-
- Initiators and Targets MUST support the response-numbering scheme.
-
-3.2.2.3. Data Sequencing
-
- Data and R2T PDUs transferred as part of some command execution MUST
- be sequenced. The DataSN field is used for data sequencing. For
- input (read) data PDUs, DataSN starts with 0 for the first data PDU
- of an input command and advances by 1 for each subsequent data PDU.
- For output data PDUs, 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 advances by 1 for each subsequent data
- PDU. R2Ts are also sequenced per command. For example, the first
- R2T has an R2TSN of 0 and advances by 1 for each subsequent 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 enables the initiator to detect missing data or R2T PDUs.
-
- For any read or bidirectional command, a target MUST issue less than
- 2**32 combined R2T and Data-In PDUs. Any output data sequence MUST
- contain less than 2**32 Data-Out PDUs.
-
-3.2.3. 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 3.4.2 SCSI
- Architecture Model).
-
- 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.
-
-
-
-Satran, et al. Standards Track [Page 24]
-
-RFC 3720 iSCSI April 2004
-
-
- 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 Chapter 8 and [RFC3723].
-
- 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 Chapter 5.
-
- 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 portal group tag (see Section 3.4.1 iSCSI Architecture
- Model). ISID is subject to reuse restrictions because it is used to
- identify a persistent state (see Section 3.4.3 Consequences of the
- Model).
-
- 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 a 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.
-
-3.2.4. iSCSI Full Feature Phase
-
- Once the initiator is authorized to do so, the iSCSI session is in
- the iSCSI Full Feature Phase. A session is in Full Feature Phase
- after successfully finishing the Login Phase on the first (leading)
-
-
-
-Satran, et al. Standards Track [Page 25]
-
-RFC 3720 iSCSI April 2004
-
-
- connection of a session. A connection is in Full Feature Phase if
- the session is in Full Feature Phase and the connection login has
- completed successfully. An iSCSI connection is not in Full Feature
- Phase
-
- a) when 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.
-
-3.2.4.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 6.2 Retry and
- Reassign in Recovery.
-
- 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.
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 26]
-
-RFC 3720 iSCSI April 2004
-
-
-3.2.4.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 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 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 on 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 part, outside of the bounds of the command.
-
-
-
-
-Satran, et al. Standards Track [Page 27]
-
-RFC 3720 iSCSI April 2004
-
-
- 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.
-
-3.2.4.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.
-
-3.2.4.4. Task Management
-
- SCSI task management assumes that individual tasks and task groups
- can be aborted solely based 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
-
-
-
-Satran, et al. Standards Track [Page 28]
-
-RFC 3720 iSCSI April 2004
-
-
- and targets interact asynchronously over several connections. iSCSI
- specifies the protocol mechanism and implementation requirements
- needed to present a synchronous view while using an asynchronous
- infrastructure.
-
-3.2.5. iSCSI Connection Termination
-
- An iSCSI connection may be terminated by use of a transport
- connection shutdown or a transport reset. 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 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 Full Feature Phase, connection
- cleanup (see section 7) is required prior to recovery. By doing
- connection cleanup before starting recovery, the initiator and target
- will avoid receiving stale PDUs after recovery.
-
-3.2.6. 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 of an iSCSI device. 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 operational domain of the end
- user. However, because the operational 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 two 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.
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 29]
-
-RFC 3720 iSCSI April 2004
-
-
- Some SCSI commands require that protocol-specific identifiers be
- communicated within SCSI CDBs. See Section 3.4.2 SCSI Architecture
- Model 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].
-
-3.2.6.1. iSCSI Name Properties
-
- Each iSCSI node, whether an initiator or target, MUST have an iSCSI
- name.
-
- 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 2.3 iSCSI Session Types) 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:
-
- a) iSCSI names are globally unique. No two initiators or targets
- can have the same name.
- b) iSCSI names are permanent. An iSCSI initiator node or target
- node has the same name for its lifetime.
- c) 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.
- d) iSCSI names do not rely on a central name broker; the naming
- authority is distributed.
- e) iSCSI names support integration with existing unique naming
- schemes.
- f) 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:
-
- a) iSCSI names have the same encoding method regardless of the
- underlying protocols.
- b) iSCSI names are relatively simple to compare. The algorithm
- for comparing two iSCSI names for equivalence does not rely on
- an external server.
-
-
-
-
-Satran, et al. Standards Track [Page 30]
-
-RFC 3720 iSCSI April 2004
-
-
- c) iSCSI names are composed only of displayable characters. iSCSI
- names allow the use of international character sets but are not
- case sensitive. No whitespace characters are used in iSCSI
- names.
- d) 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 (URN) [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.
-
-3.2.6.2. iSCSI Name Encoding
-
- An iSCSI name MUST be a UTF-8 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.
-
-
-
-
-
-Satran, et al. Standards Track [Page 31]
-
-RFC 3720 iSCSI April 2004
-
-
- The stringprep process is described in [RFC3454]; iSCSI's use of the
- stringprep process is described in [RFC3722]. Stringprep 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. Strings MUST NOT include punctuation, spacing,
- diacritical marks, or other characters that could get in the way of
- readability. The stringprep process also converts strings into
- equivalent strings of lower-case characters.
-
- The stringprep process does not need to be implemented if the names
- are only generated using numeric and lower-case (any character set)
- alphabetic characters.
-
- Once iSCSI names encoded in UTF-8 are "normalized" they may be safely
- compared byte-for-byte.
-
-3.2.6.3. iSCSI Name Structure
-
- An iSCSI name consists of two parts--a type designator followed by a
- unique name string.
-
- The iSCSI name does not define any new naming authorities. Instead,
- it supports two existing ways of designating naming authorities: an
- iSCSI-Qualified Name, using domain names to identify a naming
- authority, and the EUI format, where the IEEE Registration Authority
- assists in the formation of worldwide unique names (EUI-64 format).
-
- The type designator strings currently defined are:
-
- iqn. - iSCSI Qualified name
- eui. - Remainder of the string is an IEEE EUI-64
- identifier, in ASCII-encoded hexadecimal.
-
- These two 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.
-
-3.2.6.3.1. 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 be active, and does not have to resolve to an address; it
-
-
-
-Satran, et al. Standards Track [Page 32]
-
-RFC 3720 iSCSI April 2004
-
-
- 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. For this reason, a date code is provided as
- part of the "iqn." format.
-
- 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 reversed 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 reversed 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
-
-
-
-Satran, et al. Standards Track [Page 33]
-
-RFC 3720 iSCSI April 2004
-
-
-
-3.2.6.3.2. 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].
-
-3.2.7. 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 Section 3.4.2
- SCSI Architecture Model and Section 3.4.3 Consequences of the Model).
-
- iSCSI sessions do not persist through power cycles and boot
- operations.
-
- All iSCSI session and connection parameters are re-initialized upon
- 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 10.5 Task
- Management Function Request.)
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 34]
-
-RFC 3720 iSCSI April 2004
-
-
-3.2.8. 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, upon which 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 pre-allocated
- 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. To make
- these schemes work, iSCSI implementations have to make sure that the
- appropriate protocol layers are provided with enough information to
- implement a synchronization and/or data steering mechanism. One of
- these schemes is detailed in Appendix A. - Sync and Steering with
- Fixed Interval Markers -.
-
- The Fixed Interval Markers (FIM) scheme works by inserting markers in
- the payload stream at fixed intervals that contain the offset for the
- start of the next iSCSI PDU.
-
- 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
-
-
-
-
-Satran, et al. Standards Track [Page 35]
-
-RFC 3720 iSCSI April 2004
-
-
- 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.
-
- When the part of the TCP data stream containing an iSCSI PDU header
- is delayed or lost, markers may be used to minimize the damage as
- follows:
-
- - Markers indicate where the next iSCSI PDU starts and enable
- continued processing when iSCSI headers have to be dropped due to
- data errors discovered at the iSCSI level (e.g., iSCSI header CRC
- errors).
-
- - Markers help minimize the amount of data that has to be kept by
- the TCP/iSCSI layer while waiting for a late TCP packet arrival
- or recovery, because later they might help find iSCSI PDU headers
- and use the information contained in those to steer data to SCSI
- buffers.
-
-3.2.8.1. Sync/Steering and iSCSI PDU Length
-
- When a large iSCSI message is sent, the TCP segment(s) that contain
- 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.
-
-3.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 the reason "close
- the session". All other requests MUST be rejected.
-
- The session type is defined during login with the key=value parameter
- in the login command.
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 36]
-
-RFC 3720 iSCSI April 2004
-
-
-3.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 3.4.1 iSCSI
- Architecture Model.
-
- +-----------------------------------+
- | Network Entity (iSCSI Client) |
- | |
- | +-------------+ |
- | | iSCSI Node | |
- | | (Initiator) | |
- | +-------------+ |
- | | | |
- | +--------------+ +--------------+ |
- | |Network Portal| |Network Portal| |
- | | 10.1.30.4 | | 10.1.40.6 | |
- +-+--------------+-+--------------+-+
- | |
- | IP Networks |
- | |
- +-+--------------+-+--------------+-+
- | |Network Portal| |Network Portal| |
- | | 10.1.30.21 | | 10.1.40.3 | |
- | | TCP Port 3260| | TCP Port 3260| |
- | +--------------+ +--------------+ |
- | | | |
- | ----------------- |
- | | | |
- | +-------------+ +--------------+ |
- | | iSCSI Node | | iSCSI Node | |
- | | (Target) | | (Target) | |
- | +-------------+ +--------------+ |
- | |
- | Network Entity (iSCSI Server) |
- +-----------------------------------+
-
-3.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.
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 37]
-
-RFC 3720 iSCSI April 2004
-
-
- a) 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 item d), each of which can be
- used by some iSCSI Nodes (see item (b)) contained in that
- Network Entity to gain access to the IP network.
-
- b) iSCSI Node - represents a single iSCSI initiator or iSCSI
- target. There are one or more iSCSI Nodes within a Network
- Entity. The iSCSI Node is accessible via one or more Network
- Portals (see item d). An iSCSI Node is identified by its
- iSCSI Name (see Section 3.2.6 iSCSI Names and Chapter 12).
- 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 the same iSCSI node to use multiple
- addresses.
-
- c) 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.
-
- d) 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.
-
- e) 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 12.3 SendTargets). All Network Portals with the same
- portal group tag in the context of a given iSCSI Node are in
- the same Portal Group.
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 38]
-
-RFC 3720 iSCSI April 2004
-
-
- 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 9.1.1 Conservative
- Reuse of ISIDs.
-
- f) 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) |
- +------------------------------------------------------------------+
-
-3.4.2. SCSI Architecture Model
-
- This section describes the relationship between the SCSI Architecture
- Model [SAM2] and the constructs of the SCSI device, SCSI port and I_T
- nexus, and the iSCSI constructs described in Section 3.4.1 iSCSI
- Architecture Model.
-
- This relationship implies implementation requirements in order to
- conform to the SAM2 model and other SCSI operational functions.
- These requirements are detailed in Section 3.4.3 Consequences of the
- Model.
-
-
-
-Satran, et al. Standards Track [Page 39]
-
-RFC 3720 iSCSI April 2004
-
-
- The following list outlines mappings of SCSI architectural elements
- to iSCSI.
-
- a) SCSI Device - the SAM2 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 logical units. For iSCSI, the SCSI Device is the
- component within an iSCSI Node that provides the SCSI
- functionality. As such, there can be one SCSI Device, at
- most, within an iSCSI Node. Access to the SCSI Device can
- only be achieved in an iSCSI normal operational session (see
- Section 3.3 iSCSI Session Types). 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 - the SAM2 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 definition of
- SCSI Initiator Port and SCSI Target Port are different.
-
- SCSI Initiator Port: This maps to one endpoint of an iSCSI
- normal operational session (see Section 3.3 iSCSI Session
- Types). 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 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:
- - 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
-
-
-
-Satran, et al. Standards Track [Page 40]
-
-RFC 3720 iSCSI April 2004
-
-
- - a comma separator (1 byte), followed by
- - a text encoding as a hex-constant (see Section 5.1 Text
- Format) of the ISID (for SCSI initiator port) or the portal
- group tag (for SCSI target port) including the initial 0X
- or 0x and the terminating null (15 bytes).
-
- 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 - 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' + ISID,
- iSCSI Target Name + 't' + Portal Group Tag).
-
- NOTE: The I_T nexus identifier is not equal to the session
- identifier (SSID).
-
-3.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 can exist
- between a given iSCSI initiator node and an iSCSI target node, with
- the same session identifier (SSID).
-
- 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 ISID that identifies the SCSI initiator port. See Section
- 10.12.5 ISID.
-
- The structure of the ISID that contains a naming authority component
- (see Section 10.12.5 ISID and [RFC3721]) provides a mechanism to
- facilitate compliance with the ISID rule. (See Section 9.1.1
- Conservative Reuse of ISIDs.)
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 41]
-
-RFC 3720 iSCSI April 2004
-
-
- 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 9.1.1 Conservative Reuse of ISIDs). 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 nexus 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.
-
-3.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 logical unit 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 perform session recovery as described in Chapter
- 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 logical unit device server uses to identify the I_T nexus.
-
-3.5. Request/Response Summary
-
- This section lists and briefly describes all the iSCSI PDU types
- (request 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.
-
-
-
-
-Satran, et al. Standards Track [Page 42]
-
-RFC 3720 iSCSI April 2004
-
-
-3.5.1. Request/Response Types Carrying SCSI Payload
-
-3.5.1.1. SCSI-Command
-
- This request carries the SCSI CDB and all the other SCSI execute
- command procedure call (see [SAM2]) IN arguments such as task
- attributes, Expected Data Transfer Length for one or both transfer
- directions (the latter for bidirectional commands), and 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.
-
- In addition, the SCSI-command PDU carries information required for
- the proper operation of the iSCSI protocol - the command sequence
- number (CmdSN) for the session and the expected status number
- (ExpStatSN) for the connection.
-
- 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.
-
-3.5.1.2. SCSI-Response
-
- The SCSI-Response carries all the SCSI execute-command procedure call
- (see [SAM2]) OUT arguments and the SCSI execute-command procedure
- call return value.
-
- The SCSI-Response contains the residual counts from the operation, if
- any, an indication of whether the counts represent an overflow or an
- underflow, and 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.
-
- For a valid status that indicates that the command has been
- processed, but resulted in an exception (e.g., a SCSI CHECK
- CONDITION), the PDU data segment contains the associated sense data.
- The use of Autosense ([SAM2]) is REQUIRED by iSCSI.
-
- Some data segment content may also be associated (in the data
- segment) with a non-zero response code.
-
- In addition, the SCSI-Response PDU carries information required for
- the proper operation of the iSCSI protocol:
-
- - The number of Data-In PDUs that a target has sent (to enable
- the initiator to check that all have arrived).
- - StatSN - the Status Sequence Number on this connection.
-
-
-
-
-Satran, et al. Standards Track [Page 43]
-
-RFC 3720 iSCSI April 2004
-
-
- - ExpCmdSN - the next Expected Command Sequence Number at the
- target.
- - MaxCmdSN - the maximum CmdSN acceptable at the target from
- this initiator.
-
-3.5.1.3 Task Management Function Request
-
- The Task Management function request provides an initiator with a way
- to explicitly control the execution of one or more SCSI Tasks or
- iSCSI functions. The PDU carries a function identifier (which task
- management function to perform) and enough information to
- unequivocally identify the task or task-set on which to perform the
- action, even if the task(s) to act upon has not yet arrived or has
- been discarded due to an error.
-
- The referenced tag identifies an individual task if the function
- refers to an individual task.
-
- The I_T_L nexus identifies task sets. In iSCSI the I_T_L nexus is
- identified by the LUN and the session identification (the session
- identifies an I_T nexus).
-
- For task sets, the CmdSN of the Task Management function request
- helps identify the tasks upon which to act, namely all tasks
- associated with a LUN and having a CmdSN preceding the Task
- Management function request CmdSN.
-
- For a Task Management function, the coordination between responses to
- the tasks affected and the Task Management function response is done
- by the target.
-
-3.5.1.4. Task Management Function Response
-
- The Task Management function response carries an indication of
- function completion for a Task Management function request including
- how it was completed (response and qualifier) and additional
- information for failure responses.
-
- After the Task Management response indicates Task Management function
- completion, the initiator will not receive any additional responses
- from the affected tasks.
-
-3.5.1.5. SCSI Data-Out and SCSI Data-In
-
- SCSI Data-Out and SCSI Data-In are the main vehicles by which SCSI
- data payload is carried between initiator and target. Data payload
- is associated with a specific SCSI command through the Initiator Task
- Tag. For target convenience, outgoing solicited data also carries a
-
-
-
-Satran, et al. Standards Track [Page 44]
-
-RFC 3720 iSCSI April 2004
-
-
- Target Transfer Tag (copied from R2T) and the LUN. Each PDU contains
- the payload length and the data offset relative to the buffer address
- contained in the SCSI execute command procedure call.
-
- In each direction, the data transfer is split into "sequences". An
- end-of-sequence is indicated by the F bit.
-
- An outgoing sequence is either unsolicited (only the first sequence
- can be unsolicited) or consists of all the Data-Out PDUs sent in
- response to an R2T.
-
- Input sequences are built to enable the direction switching for
- bidirectional commands.
-
- For input, the target may request positive acknowledgement of input
- data. This is limited to sessions that support error recovery and is
- implemented through the A bit in the SCSI Data-In PDU header.
-
- Data-In and Data-Out PDUs also carry the DataSN to enable the
- initiator and target to detect missing PDUs (discarded due to an
- error).
-
- In addition, StatSN is carried by the Data-In PDUs.
-
- To enable a SCSI command to be processed while involving a minimum
- number of messages, the last SCSI Data-In PDU passed for a command
- may also contain the status if the status indicates termination with
- no exceptions (no sense or response involved).
-
-3.5.1.6. Ready To Transfer (R2T)
-
- R2T is the mechanism by which the SCSI target "requests" the
- initiator for output data. R2T specifies to the initiator the offset
- of the requested data relative to the buffer address from the execute
- command procedure call and the length of the solicited data.
-
- To help the SCSI target associate the resulting Data-Out with an R2T,
- the R2T carries a Target Transfer Tag that will be copied by the
- initiator in the solicited SCSI Data-Out PDUs. There are no protocol
- specific requirements with regard to the value of these tags, but it
- is assumed that together with the LUN, they will enable the target to
- associate data with an R2T.
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 45]
-
-RFC 3720 iSCSI April 2004
-
-
- R2T also carries information required for proper operation of the
- iSCSI protocol, such as:
-
- - R2TSN (to enable an initiator to detect a missing R2T)
- - StatSN
- - ExpCmdSN
- - MaxCmdSN
-
-3.5.2. Requests/Responses carrying SCSI and iSCSI Payload
-
-3.5.2.1. Asynchronous Message
-
- Asynchronous Messages are used to carry SCSI asynchronous events
- (AEN) and iSCSI asynchronous messages.
-
- When carrying an AEN, the event details are reported as sense data in
- the data segment.
-
-3.5.3. Requests/Responses Carrying iSCSI Only Payload
-
-3.5.3.1. Text Request and Text Response
-
- Text requests and responses are designed as a parameter negotiation
- vehicle and as a vehicle for future extension.
-
- In the data segment, Text Requests/Responses carry text information
- using a simple "key=value" syntax.
-
- Text Request/Responses may form extended sequences using the same
- Initiator Task Tag. The initiator uses the F (Final) flag bit in the
- text request header to indicate its readiness to terminate a
- sequence. The target uses the F (Final) flag bit in the text
- response header to indicate its consent to sequence termination.
-
- Text Request and Responses also use the Target Transfer Tag to
- indicate continuation of an operation or a new beginning. A target
- that wishes to continue an operation will set the Target Transfer Tag
- in a Text Response to a value different from the default 0xffffffff.
- An initiator willing to continue will copy this value into the Target
- Transfer Tag of the next Text Request. If the initiator wants to
- restart the current target negotiation (start fresh) will set the
- Target Transfer Tag to 0xffffffff.
-
- Although a complete exchange is always started by the initiator,
- specific parameter negotiations may be initiated by the initiator or
- target.
-
-
-
-
-
-Satran, et al. Standards Track [Page 46]
-
-RFC 3720 iSCSI April 2004
-
-
-3.5.3.2. Login Request and Login Response
-
- Login Requests and Responses are used exclusively during the Login
- Phase of each connection to set up the session and connection
- parameters. (The Login Phase consists of a sequence of login
- requests and responses carrying the same Initiator Task Tag.)
-
- A connection is identified by an arbitrarily selected connection-ID
- (CID) that is unique within a session.
-
- Similar to the Text Requests and Responses, Login Requests/Responses
- carry key=value text information with a simple syntax in the data
- segment.
-
- The Login Phase proceeds through several stages (security
- negotiation, operational parameter negotiation) that are selected
- with two binary coded fields in the header -- the "current stage"
- (CSG) and the "next stage" (NSG) with the appearance of the latter
- being signaled by the "transit" flag (T).
-
- The first Login Phase of a session plays a special role, called the
- leading login, which determines some header fields (e.g., the version
- number, the maximum number of connections, and the session
- identification).
-
- The CmdSN initial value is also set by the leading login.
-
- StatSN for each connection is initiated by the connection login.
-
- A login request may indicate an implied logout (cleanup) of the
- connection to be logged in (a connection restart) by using the same
- Connection ID (CID) as an existing connection, as well as the same
- session identifying elements of the session to which the old
- connection was associated.
-
-3.5.3.3. Logout Request and Response
-
- Logout Requests and Responses are used for the orderly closing of
- connections for recovery or maintenance. The logout request may be
- issued following a target prompt (through an asynchronous message) or
- at an initiators initiative. When issued on the connection to be
- logged out, no other request may follow it.
-
- The Logout Response indicates that the connection or session cleanup
- is completed and no other responses will arrive on the connection (if
- received on the logging out connection). In addition, the Logout
- Response indicates how long the target will continue to hold
- resources for recovery (e.g., command execution that continues on a
-
-
-
-Satran, et al. Standards Track [Page 47]
-
-RFC 3720 iSCSI April 2004
-
-
- new connection) in the text key Time2Retain and how long the
- initiator must wait before proceeding with recovery in the text key
- Time2Wait.
-
-3.5.3.4. SNACK Request
-
- With the SNACK Request, the initiator requests retransmission of
- numbered-responses or data from the target. A single SNACK request
- covers a contiguous set of missing items, called a run, of a given
- type of items. The type is indicated in a type field in the PDU
- header. The run is composed of an initial item (StatSN, DataSN,
- R2TSN) and the number of missed Status, Data, or R2T PDUs. For long
- Data-In sequences, the target may request (at predefined minimum
- intervals) a positive acknowledgement for the data sent. A SNACK
- request with a type field that indicates ACK and the number of
- Data-In PDUs acknowledged conveys this positive acknowledgement.
-
-3.5.3.5. Reject
-
- Reject enables the target to report an iSCSI error condition (e.g.,
- protocol, unsupported option) that uses a Reason field in the PDU
- header and includes the complete header of the bad PDU in the Reject
- PDU data segment.
-
-3.5.3.6. NOP-Out Request and NOP-In Response
-
- This request/response pair may be used by an initiator and target as
- a "ping" mechanism to verify that a connection/session is still
- active and all of its components are operational. Such a ping may be
- triggered by the initiator or target. The triggering party indicates
- that it wants a reply by setting a value different from the default
- 0xffffffff in the corresponding Initiator/Target Transfer Tag.
-
- NOP-In/NOP-Out may also be used "unidirectional" to convey to the
- initiator/target command, status or data counter values when there is
- no other "carrier" and there is a need to update the initiator/
- target.
-
-4. SCSI Mode Parameters for iSCSI
-
- There are no iSCSI specific mode pages.
-
-5. Login and Full Feature Phase Negotiation
-
- iSCSI parameters are negotiated at session or connection
- establishment by using Login Requests and Responses (see Section
- 3.2.3 iSCSI Login) and during the Full Feature Phase (Section 3.2.4
- iSCSI Full Feature Phase) by using Text Requests and Responses. In
-
-
-
-Satran, et al. Standards Track [Page 48]
-
-RFC 3720 iSCSI April 2004
-
-
- both cases the mechanism used is an exchange of iSCSI-text-key=value
- pairs. For brevity iSCSI-text-keys are called just keys in the rest
- of this document.
-
- Keys are either declarative or require negotiation and the key
- description indicates if the key is declarative or requires
- negotiation.
-
- For the declarative keys, the declaring party sets a value for the
- key. The key specification indicates if the key can be declared by
- the initiator, target or both.
-
- For the keys that require negotiation one of the parties (the
- proposing party) proposes a value or set of values by including the
- key=value in the data part of a Login or Text Request or Response
- PDUs. The other party (the accepting party) makes a selection based
- on the value or list of values proposed and includes the selected
- value in a key=value in the data part of one of the following Login
- or Text Response or Request PDUs. For most of the keys both the
- initiator and target can be proposing parties.
-
- The login process proceeds in two stages - the security negotiation
- stage and the operational parameter negotiation stage. Both stages
- are optional but at least one of them has to be present to enable the
- setting of some mandatory parameters.
-
- If present, the security negotiation stage precedes the operational
- parameter negotiation stage.
-
- Progression from stage to stage is controlled by the T (Transition)
- bit in the Login Request/Response PDU header. Through the T bit set
- to 1, the initiator indicates that it would like to transition. The
- target agrees to the transition (and selects the next stage) when
- ready. A field in the Login PDU header indicates the current stage
- (CSG) and during transition, another field indicates the next stage
- (NSG) proposed (initiator) and selected (target).
-
- The text negotiation process is used to negotiate or declare
- operational parameters. The negotiation process is controlled by the
- F (final) bit in the PDU header. During text negotiations, the F bit
- is used by the initiator to indicate that it is ready to finish the
- negotiation and by the Target to acquiesce the end of negotiation.
-
- Since some key=value pairs may not fit entirely in a single PDU, the
- C (continuation) bit is used (both in Login and Text) to indicate
- that "more follows".
-
-
-
-
-
-Satran, et al. Standards Track [Page 49]
-
-RFC 3720 iSCSI April 2004
-
-
- The text negotiation uses an additional mechanism by which a target
- may deliver larger amounts of data to an enquiring initiator. The
- target sets a Target Task Tag to be used as a bookmark that when
- returned by the initiator, means "go on". If reset to a "neutral
- value", it means "forget about the rest".
-
- This chapter details types of keys and values used, the syntax rules
- for parameter formation, and the negotiation schemes to be used with
- different types of parameters.
-
-5.1. Text Format
-
- The initiator and target send a set of key=value pairs encoded in
- UTF-8 Unicode. All the text keys and text values specified in this
- document are to be presented and interpreted in the case in which
- they appear in this document. They are case sensitive.
-
- The following character symbols are used in this document for text
- items (the hexadecimal values represent Unicode code points):
-
- (a-z, A-Z) - letters
- (0-9) - 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) - tilde
-
- Key=value pairs may span PDU boundaries. An initiator or target that
- sends partial key=value text within a PDU indicates that more text
- follows by setting the C bit in the Text or Login Request or Text or
- Login Response to 1. Data segments in a series of PDUs that have the
- C bit set to 1 and end with a PDU that have the C bit set to 0, or
- include a single PDU that has the C bit 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 a LTDS, MUST
- be followed by one null (0x00) delimiter.
-
-
-
-
-Satran, et al. Standards Track [Page 50]
-
-RFC 3720 iSCSI April 2004
-
-
- A key-name is whatever precedes the first "=" in the key=value pair.
- The term key is used frequently in this document in place of
- key-name.
-
- A value is whatever follows the first "=" in the key=value pair up to
- the end of the key=value pair, but not including the null delimiter.
-
- The following definitions will be used in the rest of this document:
-
- standard-label: A string of one or more characters that consist 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 that consist 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 that consist
- of minus, dot, colon, or any character allowed by the output of
- the iSCSI string-prep template as specified in [RFC3722] (see
- also Section 3.2.6.2 iSCSI Name Encoding).
-
- iSCSI-local-name-value: A UTF-8 string; no null characters are
- allowed in the string. This encoding is to be used for localized
- (internationalized) aliases.
-
- boolean-value: The string "Yes" or "No".
-
- hex-constant: A hexadecimal constant encoded 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 used to
- encode numerical values, the excessive use of leading 0 digits is
- discouraged. The string following 0X (or 0x) represents a base16
- number that starts with the most significant base16 digit,
- followed by all other digits in decreasing order of significance
- and ending with the least-significant base16 digit. When used to
- encode binary strings, hexadecimal constants have an implicit
- byte-length that includes four bits for every hexadecimal digit
- of the constant, including leading zeroes. For example, a
- hex-constant of n hexadecimal digits has a byte-length of (the
- integer part of) (n+1)/2.
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 51]
-
-RFC 3720 iSCSI April 2004
-
-
- decimal-constant: An unsigned decimal number with the digit 0 or a
- string of one or more digits that start with a non-zero digit.
- Decimal-constants are used to encode numerical values or binary
- strings. Decimal constants can only be used to encode binary
- strings if the string length is explicitly specified. There is
- no implicit length for decimal strings. Decimal-constant MUST
- NOT be used for parameter values if the values can be equal or
- greater than 2**64 (numerical) or for binary strings that can be
- longer than 64 bits.
-
- base64-constant: base64 constant encoded as a string that starts
- with "0b" or "0B" followed by 1 or more digits or letters or plus
- or slash or equal. The encoding is done according to [RFC2045]
- and each character, except equal, represents a base64 digit or a
- 6-bit binary string. Base64-constants are used to encode
- numerical-values or binary strings. When used to encode
- numerical values, the excessive use of leading 0 digits (encoded
- as A) is discouraged. The string following 0B (or 0b) represents
- a base64 number that starts with the most significant base64
- digit, followed by all other digits in decreasing order of
- significance and ending with the least-significant base64 digit;
- the least significant base64 digit may be optionally followed by
- pad digits (encoded as equal) that are not considered as part of
- the number. When used to encode binary strings, base64-constants
- have an implicit
- byte-length that includes six bits for every character of the
- constant, excluding trailing equals (i.e., a base64-constant of n
- base64 characters excluding the trailing equals has a byte-length
- of ((the integer part of) (n*3/4)). Correctly encoded base64
- strings cannot have n values of 1, 5 ... k*4+1.
-
- 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-numeric-values.
-
- numeric-range: Two numerical-values separated by a tilde where the
- value to the right of tilde must not be lower than the value to
- the left.
-
- regular-binary-value: A binary string not longer than 64 bits
- encoded as a decimal constant, hex constant, or base64-constant.
- The length of the string is either specified by the key
- definition or is the implicit byte-length of the encoded string.
-
-
-
-Satran, et al. Standards Track [Page 52]
-
-RFC 3720 iSCSI April 2004
-
-
- large-binary-value: A binary string longer than 64 bits encoded as
- a hex-constant or base64-constant. The length of the string 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: Text-value, iSCSI-name-value, boolean-value,
- numeric-value, a numeric-range, or a binary-value.
-
- list-of-values: A sequence of text-values separated by a comma.
-
- If not otherwise specified, the maximum length of a simple-value (not
- its encoded representation) 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 of at least 64 kilobytes of key=value data (see Appendix
- 11.1.2 - Simple Public-Key Mechanism (SPKM) - that require support
- for public key certificates).
-
-5.2. Text Mode Negotiation
-
- During login, and thereafter, some session or connection parameters
- are either declared or negotiated through an exchange of textual
- information.
-
- The initiator starts the negotiation and/or declaration through a
- Text or Login Request and indicates when it is ready for completion
- (by setting the F bit to 1 and keeping it to 1 in a Text Request or
- the T bit in the Login Request). As negotiation text may span PDU
- boundaries, a Text or Login Request or Text or Login Response PDU
- that has the C bit set to 1 MUST NOT have the F/T bit set to 1.
-
- A target receiving a Text or Login Request with the C bit set to 1
- MUST answer with a Text or Login Response with no data segment
- (DataSegmentLength 0). An initiator receiving a Text or Login
- Response with the C bit set to 1 MUST answer with a Text or Login
- Request with no data segment (DataSegmentLength 0).
-
- A target or initiator SHOULD NOT use a Text or Login Response or Text
- or Login Request with no data segment (DataSegmentLength 0) unless
- explicitly required by a general or a key-specific negotiation rule.
-
-
-
-
-Satran, et al. Standards Track [Page 53]
-
-RFC 3720 iSCSI April 2004
-
-
- The format of a declaration is:
-
- Declarer-> <key>=<valuex>
-
- The general format of text negotiation is:
-
- Proposer-> <key>=<valuex>
- Acceptor-> <key>={<valuey>|NotUnderstood|Irrelevant|Reject}
-
- Thus a declaration is a one-way textual exchange while a negotiation
- is a two-way exchange.
-
- The proposer or declarer can either be the initiator or the target,
- and the acceptor can either be the target or initiator, respectively.
- Targets are not limited to respond to key=value pairs as proposed by
- the initiator. The target may propose key=value pairs of its own.
-
- All negotiations are explicit (i.e., the result MUST only be based on
- newly exchanged or declared values). There are no implicit
- proposals. If a proposal is not made, then a reply cannot be
- expected. Conservative design also requires that default values
- should not be relied upon when use of some other value has serious
- consequences.
-
- The value proposed or declared can be a numerical-value, a
- numerical-range defined by lower and upper values with 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 it is explicitly allowed.
- An accepted value can be a numerical-value, a large-numerical-value,
- a text-value, or a boolean-value.
-
- If a specific key is not relevant for the current negotiation, the
- acceptor may answer with the constant "Irrelevant" for all types of
- negotiation. However the negotiation is not considered as failed if
- the answer is "Irrelevant". The "Irrelevant" answer is meant for
- those cases in which several keys are presented by a proposing party
- but the selection made by the acceptor for one of the keys makes
- other keys irrelevant. The following example illustrates the use of
- "Irrelevant":
-
- I->T OFMarker=Yes,OFMarkInt=2048~8192
- T->I OFMarker=No,OFMarkInt=Irrelevant
-
- I->T X#vkey1=(bla,alb,None),X#vkey2=(bla,alb)
- T->I X#vkey1=None,X#vkey2=Irrelevant
-
-
-
-Satran, et al. Standards Track [Page 54]
-
-RFC 3720 iSCSI April 2004
-
-
-
- Any key not understood by the acceptor may be ignored by the acceptor
- without affecting the basic function. However, the answer for a key
- not understood MUST be key=NotUnderstood.
-
- The constants "None", "Reject", "Irrelevant", and "NotUnderstood" are
- reserved and MUST ONLY be used as described here. Violation of this
- rule is a protocol error (in particular the use of "Reject",
- "Irrelevant", and "NotUnderstood" as proposed values).
-
- Reject or Irrelevant are legitimate negotiation options where allowed
- but their excessive use is discouraged. A negotiation is considered
- complete when the acceptor has sent the key value pair even if the
- value is "Reject", "Irrelevant", or "NotUnderstood. Sending the key
- again would be a re-negotiation and is forbidden for many keys.
-
- If the acceptor sends "Reject" as an answer the negotiated key is
- left at its current value (or default if no value was set). If the
- current value is not acceptable to the proposer on the connection or
- to the session it is sent, the proposer MAY choose to terminate the
- connection or session.
-
- All keys in this document, except for the X extension formats, MUST
- be supported by iSCSI initiators and targets when used as specified
- here. If used as specified, these keys MUST NOT be answered with
- NotUnderstood.
-
- Implementers may introduce new keys by prefixing them with
- "X-", followed by their (reversed) domain name, or with new keys
- registered with IANA prefixing them with X#. For example, the entity
- owning the domain example.com can issue:
-
- X-com.example.bar.foo.do_something=3
-
- or a new registered key may be used as in:
-
- X#SuperCalyPhraGilistic=Yes
-
- Implementers MAY also introduce new values, but ONLY for new keys or
- authentication methods (see Section 11 iSCSI Security Text Keys and
- Authentication Methods), or digests (see Section 12.1 HeaderDigest
- and DataDigest).
-
- Whenever parameter action or acceptance is dependent on other
- parameters, the dependency rules and parameter sequence must be
- specified with the parameters.
-
-
-
-
-
-Satran, et al. Standards Track [Page 55]
-
-RFC 3720 iSCSI April 2004
-
-
- In the Login Phase (see Section 5.3 Login Phase), every stage is a
- separate negotiation. In the FullFeaturePhase, a Text Request
- Response sequence is a negotiation. Negotiations MUST be handled as
- atomic operations. For example, all negotiated values go into effect
- after the negotiation concludes in agreement or are ignored if the
- negotiation fails.
-
- Some parameters may be subject to integrity rules (e.g., parameter-x
- must not exceed parameter-y or parameter-u not 1 implies parameter-v
- be Yes). Whenever required, integrity rules are specified with the
- keys. Checking for compliance with the integrity rule must only be
- performed after all the parameters are available (the existent and
- the newly negotiated). An iSCSI target MUST perform integrity
- checking before the new parameters take effect. An initiator MAY
- perform integrity checking.
-
- An iSCSI initiator or target MAY terminate a negotiation that does
- not end within a reasonable time or number of exchanges.
-
-5.2.1. List negotiations
-
- In list negotiation, the originator sends a list of values (which may
- include "None") in its 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 the specific
- originator) selected from the originator list.
-
- The constant "None" MUST always be used to indicate a missing
- function. However, "None" is only a valid selection if it is
- explicitly proposed.
-
- If an acceptor does not understand any particular value in a list, it
- MUST ignore it. If an acceptor does not support, does not
- understand, or is not allowed to use any of the proposed options with
- a specific originator, it may use the constant "Reject" or terminate
- the negotiation. The selection of a value not proposed MUST be
- handled as a protocol error.
-
-5.2.2. Simple-value Negotiations
-
- For simple-value negotiations, the accepting party MUST answer with
- the same key. The value it selects becomes the negotiation result.
-
- Proposing a value not admissible (e.g., not within the specified
- bounds) MAY be answered with the constant "Reject" or the acceptor
- MAY select an admissible value.
-
-
-
-
-Satran, et al. Standards Track [Page 56]
-
-RFC 3720 iSCSI April 2004
-
-
- The selection by the acceptor, of a value not admissible under the
- selection rules is considered a protocol error. The selection rules
- are key-specific.
-
- For a numerical range, the value selected must be an integer within
- the proposed range or "Reject" (if the range is unacceptable).
-
- In Boolean negotiations (i.e., those that result in keys taking the
- values Yes or No), the accepting party MUST answer with the same key
- and the result of the negotiation when the received value does not
- determine that result by itself. The last value transmitted becomes
- the negotiation result. The rules for selecting the value to answer
- with are expressed as Boolean functions of the value received, and
- the value that the accepting party would have selected if given a
- choice.
-
- Specifically, the two cases in which answers are OPTIONAL are:
-
- - 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 chosen and
- sent by the acceptor becomes the outcome of the negotiation.
-
-5.3. Login Phase
-
- The Login Phase establishes an iSCSI connection between an initiator
- and a target; it also creates a new session or associates the
- connection to an existing session. The Login Phase sets the iSCSI
- protocol parameters, security parameters, and authenticates the
- initiator and target to each other.
-
- The Login Phase is only implemented via Login Request and Responses.
- The whole Login Phase is considered as a single task and has a single
- Initiator Task Tag (similar to the linked SCSI commands).
-
- The default MaxRecvDataSegmentLength is used during Login.
-
- The Login Phase sequence of requests and responses proceeds as
- follows:
-
- - Login initial request
- - Login partial response (optional)
- - More Login Requests and Responses (optional)
- - Login Final-Response (mandatory)
-
-
-
-
-Satran, et al. Standards Track [Page 57]
-
-RFC 3720 iSCSI April 2004
-
-
- The initial Login Request of any connection MUST include the
- InitiatorName key=value pair. The initial Login Request of the first
- connection of a session MAY also include the SessionType key=value
- pair. For any connection within a session whose type is not
- "Discovery", the first Login Request MUST also include the TargetName
- key=value pair.
-
- The Login Final-response accepts or rejects the Login Request.
-
- The Login Phase MAY include a SecurityNegotiation stage and a
- LoginOperationalNegotiation stage or both, but MUST include at least
- one of them. The included stage MAY be empty except for the
- mandatory names.
-
- The Login Requests and Responses contain a field (CSG) that indicates
- the current negotiation stage (SecurityNegotiation or
- LoginOperationalNegotiation). If both stages are used, the
- SecurityNegotiation MUST precede the LoginOperationalNegotiation.
-
- Some operational parameters can be negotiated outside the login
- through Text Requests and Responses.
-
- Security MUST be completely negotiated within the Login Phase. The
- use of underlying IPsec security is specified in Chapter 8 and in
- [RFC3723]. iSCSI support for security within the protocol only
- consists of authentication in the Login Phase.
-
- In some environments, a target or an initiator is not interested in
- authenticating its counterpart. It is possible to bypass
- authentication through the Login Request and Response.
-
- The initiator and target MAY want to negotiate iSCSI authentication
- parameters. Once this negotiation is completed, the channel is
- considered secure.
-
- Most of the negotiation keys are only allowed in a specific stage.
- The SecurityNegotiation keys appear in Chapter 11 and the
- LoginOperationalNegotiation keys appear in Chapter 12. Only a
- limited set of keys (marked as Any-Stage in Chapter 12) may be used
- in any of the two stages.
-
- Any given Login Request or Response belongs to a specific stage; this
- determines the negotiation keys allowed with the request or response.
- It is considered to be a protocol error to send a key that is not
- allowed in the current stage.
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 58]
-
-RFC 3720 iSCSI April 2004
-
-
- Stage transition is performed through a command exchange (request/
- response) that carries the T bit and the same CSG code. During this
- exchange, the next stage is selected by the target through the "next
- stage" code (NSG). The selected NSG MUST NOT exceed the value stated
- by the initiator. The initiator can request a transition whenever it
- is ready, but a target can only respond with a transition after one
- is proposed by the initiator.
-
- In a negotiation sequence, the T bit settings in one pair of Login
- Request-Responses have no bearing on the T bit settings of the next
- pair. An initiator that has a T bit set to 1 in one pair and is
- answered with a T bit setting of 0, may issue the next request with
- the T bit set to 0.
-
- When a transition is requested by the initiator and acknowledged by
- the target, both the initiator and target switch 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.
-
- 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 come
- as a response to a Login Request with the T bit set to 1, and both
- the request and response MUST indicate FullFeaturePhase as the next
- phase via the NSG field.
-
- Neither the initiator nor the target should attempt to declare or
- negotiate a parameter more than once during login except for
- responses to specific keys that explicitly allow repeated key
- declarations (e.g., TargetAddress). An attempt to
- renegotiate/redeclare parameters not specifically allowed MUST be
- detected by the initiator and target. If such an attempt is detected
-
-
-
-
-Satran, et al. Standards Track [Page 59]
-
-RFC 3720 iSCSI April 2004
-
-
- by the target, the target MUST respond with Login reject (initiator
- error); if detected by the initiator, the initiator MUST drop the
- connection.
-
-5.3.1. Login Phase Start
-
- The Login Phase starts 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 may create a new session or it may add a connection to an
- existing session. Between a given iSCSI Initiator Node (selected
- only by an InitiatorName) and a given iSCSI target defined by an
- iSCSI TargetName and a Target Portal Group Tag, the login results are
- defined by the following 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 5.3.5) |
- +------------------------------------------------------------------+
- |existing | non-zero | new | add a new connection to |
- | | existing | | the session |
- +------------------------------------------------------------------+
- |existing | non-zero |existing| do connection reinstatement|
- | | existing | | (see section 5.3.4) |
- +------------------------------------------------------------------+
- |existing | non-zero | any | fail the login |
- | | new | | ("session does not exist") |
- +------------------------------------------------------------------+
-
- Determination of "existing" or "new" are made by the target.
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 60]
-
-RFC 3720 iSCSI April 2004
-
-
- Optionally, the Login Request may 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 the following ways:
-
- - Login Response with Login reject. This is an immediate rejection
- from the target that causes the connection to terminate and the
- session to terminate if this is the first (or only) connection of
- a new session. The T bit and the CSG and NSG fields are
- reserved.
- - Login Response with Login Accept as a final response (T bit set
- to 1 and the NSG in both request and response are set to
- FullFeaturePhase). The response includes the protocol version
- supported by the target and the session ID, and may include iSCSI
- operational or security parameters (that depend on the current
- stage).
- - Login Response with Login Accept as a partial response (NSG not
- set to FullFeaturePhase in both request and response) that
- indicates the start of a negotiation sequence. The response
- includes the protocol version supported by the target and either
- security or iSCSI parameters (when no security mechanism is
- chosen) supported by the target.
-
- If the initiator decides to forego the SecurityNegotiation stage, it
- issues the Login with the CSG set to LoginOperationalNegotiation and
- the target may reply with a Login Response that indicates that it is
- unwilling to accept the connection (see Section 10.13 Login Response)
- without SecurityNegotiation and will terminate the connection with a
- response of Authentication failure (see Section 10.13.5 Status-Class
- and Status-Detail).
-
- If the initiator is willing to negotiate iSCSI security, but is
- unwilling to make the initial parameter proposal and may 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 12.9 TargetPortalGroupTag), the T bit set to 1, the
- CSG set to SecurityNegotiation, and the NSG set to
- LoginOperationalNegotiation.
-
-
-
-
-
-Satran, et al. Standards Track [Page 61]
-
-RFC 3720 iSCSI April 2004
-
-
- An initiator that chooses to operate without iSCSI security, with all
- the operational parameters taking the 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 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 with which
- it is allowed to do so (i.e., the first Login Response issued after
- the first Login Request with the C bit set to 0) for all session
- types when TargetName is given and the response is not a redirection.
- The TargetPortalGroupTag key value indicates the iSCSI portal group
- servicing the Login Request PDU. If the reconfiguration of iSCSI
- portal groups is a concern in a given environment, the iSCSI
- initiator should use this key to ascertain that it had indeed
- initiated the Login Phase with the intended target portal group.
-
-5.3.2. iSCSI Security Negotiation
-
- The security exchange sets the security mechanism and authenticates
- the initiator user and the target to each other. The exchange
- proceeds according to the authentication method chosen in the
- negotiation phase and is conducted using the Login Requests' and
- responses' key=value parameters.
-
- An initiator directed negotiation proceeds as follows:
-
- - The initiator sends a Login Request with an ordered list of the
- options it supports (authentication algorithm). The options are
- listed 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 does not support any, in which case it MUST answer with
- "Reject" (see Section 5.2 Text Mode Negotiation). The parameters
- are encoded in UTF8 as key=value. For security parameters, see
- Chapter 11.
-
- - When the initiator considers that it is ready to conclude the
- SecurityNegotiation stage, it sets the T bit to 1 and the NSG to
- what it would like the next stage to be. The target will then
- set the T bit to 1 and set the NSG to the next stage in the Login
- Response when it finishes sending its security keys. The next
-
-
-
-
-Satran, et al. Standards Track [Page 62]
-
-RFC 3720 iSCSI April 2004
-
-
- stage selected will be the one the target selected. If the next
- stage is FullFeaturePhase, the target MUST respond with a Login
- Response with the TSIH value.
-
- If the security negotiation fails at the target, then the target MUST
- send the appropriate Login Response PDU. If the security negotiation
- fails at the initiator, the initiator SHOULD close the connection.
-
- It should be noted that the negotiation might also be directed by the
- target if the initiator does support security, but is not ready to
- direct the negotiation (propose options).
-
-5.3.3. Operational Parameter Negotiation During the Login Phase
-
- Operational parameter negotiation during the login 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-Response exchanges started and terminated by the initiator.
- The initiator MUST indicate its intent to terminate the negotiation
- by setting the T bit to 1; the target sets the T bit to 1 on the last
- response.
-
- If the target responds to a Login Request that has the T bit set to 1
- with a Login Response that has the T bit set to 0, the initiator
- should keep sending the Login Request (even empty) with the T bit set
- to 1, while it still wants to switch stage, until it receives the
- Login Response that has the T bit set to 1 or it receives a key that
- requires it to set the T bit to 0.
-
- Some session specific parameters can only be specified during the
- Login Phase of the first connection of a session (i.e., begun by a
- Login Request that contains a zero-valued TSIH) - the leading Login
- Phase (e.g., the maximum number of connections that can be used for
- this session).
-
- A session is operational once it has at least one connection in
- FullFeaturePhase. New or replacement connections can only be added
- to a session after the session is operational.
-
- For operational parameters, see Chapter 12.
-
-
-
-
-
-Satran, et al. Standards Track [Page 63]
-
-RFC 3720 iSCSI April 2004
-
-
-5.3.4. Connection Reinstatement
-
- Connection reinstatement is the process of an initiator logging in
- with an ISID-TSIH-CID combination that is possibly active from the
- target's perspective, which causes the implicit logging out of the
- connection corresponding to the CID, and reinstating a new Full
- Feature Phase iSCSI connection in its place (with the same CID).
- Thus, the TSIH in the Login PDU MUST be non-zero and the CID does not
- change during a connection reinstatement. The Login Request performs
- the logout function of the old connection if an explicit logout was
- not performed earlier. In sessions with a single connection, this
- may imply the opening of a second connection with the sole purpose of
- cleaning up the first. Targets MUST support opening a second
- connection even when they do not support multiple connections in 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 the
- replacement of 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 7.1.3)
- when the initiator attempts a connection reinstatement.
-
- In practical terms, in addition to the implicit logout of the old
- connection, reinstatement is equivalent to a new connection login.
-
-5.3.5. Session Reinstatement, Closure, and Timeout
-
- Session reinstatement is the process of the initiator logging in with
- an ISID that is possibly active from the target's perspective. Thus
- implicitly logging out the session that corresponds to the ISID and
- reinstating a new iSCSI session in its place (with the same ISID).
- Therefore, the TSIH in the Login PDU MUST be zero to signal session
- reinstatement. Session reinstatement 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 7.3 Session State
- Diagrams) when the initiator attempts a session reinstatement.
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 64]
-
-RFC 3720 iSCSI April 2004
-
-
- Session closure is an event defined to be one of the following:
-
- - 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 7.2 Connection Cleanup State Diagram
- for Initiators and Targets) and no tasks in the session are
- waiting for reassignment.
-
- Session timeout is an event defined to occur when the last connection
- state timeout expires and no tasks are waiting for reassignment.
- This takes the session to the FREE state (N6 transition in the
- session state diagram).
-
-5.3.5.1. Loss of Nexus Notification
-
- The iSCSI layer provides the SCSI layer with the "I_T nexus loss"
- notification when any one of the following events happens:
-
- a) Successful completion of session reinstatement.
- b) Session closure event.
- c) Session timeout event.
-
- Certain SCSI object clearing actions may result due to the
- notification in the SCSI end nodes, as documented in Appendix F.
- - Clearing Effects of Various Events on Targets -.
-
-5.3.6. Session Continuation and Failure
-
- Session continuation is the process by which the state of a
- preexisting session continues to be used by connection reinstatement
- (Section 5.3.4 Connection Reinstatement), or by adding a connection
- with a new CID. Either of these actions associates the new transport
- connection with the session state.
-
- Session failure is an event where the last Full Feature Phase
- connection reaches the CLEANUP_WAIT state (Section 7.2 Connection
- Cleanup State Diagram for Initiators and Targets), or completes a
- successful recovery logout, thus causing all active tasks (that are
- formerly allegiant to the connection) to start waiting for task
- reassignment.
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 65]
-
-RFC 3720 iSCSI April 2004
-
-
-5.4. Operational Parameter Negotiation Outside the Login Phase
-
- Some operational parameters MAY be negotiated outside (after) the
- Login Phase.
-
- Parameter negotiation in Full Feature Phase is done through Text
- requests and responses. Operational parameter negotiation MAY
- involve several Text request-response exchanges, which the initiator
- always starts and terminates using the same Initiator Task Tag. The
- initiator MUST indicate its intent to terminate the negotiation by
- setting the F bit to 1; the target sets the F bit to 1 on the last
- response.
-
- If the target responds to a Text request with the F bit set to 1 and
- with a Text response with the F bit set to 0, the initiator should
- keep sending the Text request (even empty) with the F bit set to 1,
- while it still wants to finish the negotiation, until it receives the
- Text response with the F bit set to 1. Responding to a Text request
- with the F bit set to 1 with an empty (no key=value pairs) response
- with the F bit set to 0 is discouraged.
-
- Targets MUST NOT submit parameters that require an additional
- initiator Text request in a Text response with the F bit set to 1.
-
- In a negotiation sequence, the F bit settings in one pair of Text
- request-responses have no bearing on the F bit settings of the next
- pair. An initiator that has the F bit set to 1 in a request and is
- being answered with an F bit setting of 0 may issue the 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
- issuing a Text request with the Target Transfer Tag set to the value
- 0xffffffff after receiving a response with the 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 attempt to declare or
- negotiate a parameter more than once during any negotiation sequence
- without an intervening operational parameter negotiation reset,
- except for responses to specific keys that explicitly allow repeated
- key declarations (e.g., TargetAddress). If detected by the target,
- this MUST result in a Reject PDU with a reason of "protocol error".
- The initiator MUST reset the negotiation as outlined above.
-
-
-
-
-Satran, et al. Standards Track [Page 66]
-
-RFC 3720 iSCSI April 2004
-
-
- Parameters negotiated by a text exchange negotiation sequence only
- become effective after the negotiation sequence is completed.
-
-6. iSCSI Error Handling and Recovery
-
-6.1. Overview
-
-6.1.1. Background
-
- The following two considerations prompted the design of much of the
- error recovery functionality in iSCSI:
-
- i) An iSCSI PDU may fail the digest check and be dropped, despite
- being received by the TCP layer. The iSCSI layer must
- optionally be allowed to recover such dropped PDUs.
- ii) A TCP connection may fail at any time during the data
- transfer. All the active tasks must optionally be allowed to
- continue on a different TCP connection within the same
- session.
-
- Implementations have considerable flexibility in deciding what degree
- of error recovery to support, when to use it and by which mechanisms
- to achieve the required behavior. Only the externally visible
- actions of the error recovery mechanisms must be standardized to
- ensure interoperability.
-
- This chapter describes a general model for recovery in support of
- interoperability. See Appendix E. - Algorithmic Presentation of
- Error Recovery Classes - for further detail on how the described
- model may be implemented. Compliant implementations do not have to
- match the implementation details of this model as presented, but the
- external behavior of such implementations must correspond to the
- externally observable characteristics of the presented model.
-
-6.1.2. Goals
-
- The major design goals of the iSCSI error recovery scheme are as
- follows:
-
- a) Allow iSCSI implementations to meet different requirements by
- defining a collection of error recovery mechanisms that
- implementations may choose from.
- b) Ensure interoperability between any two implementations
- supporting different sets of error recovery capabilities.
- c) Define the error recovery mechanisms to ensure command
- ordering even in the face of errors, for initiators that
- demand ordering.
-
-
-
-
-Satran, et al. Standards Track [Page 67]
-
-RFC 3720 iSCSI April 2004
-
-
- d) Do not make additions in the fast path, but allow moderate
- complexity in the error recovery path.
- e) Prevent both the initiator and target from attempting 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.
-
-6.1.3. Protocol Features and State Expectations
-
- The initiator mechanisms defined in connection with error recovery
- are:
-
- a) NOP-OUT to probe sequence numbers of the target (section
- 10.18)
- b) Command retry (section 6.2.1)
- c) Recovery R2T support (section 6.7)
- d) Requesting retransmission of status/data/R2T using the SNACK
- facility (section 10.16)
- e) Acknowledging the receipt of the data (section 10.16)
- f) Reassigning the connection allegiance of a task to a different
- TCP connection (section 6.2.2)
- g) Terminating the entire iSCSI session to start afresh (section
- 6.1.4.4)
-
- The target mechanisms defined in connection with error recovery are:
-
- a) NOP-IN to probe sequence numbers of the initiator (section
- 10.19)
- b) Requesting retransmission of data using the recovery R2T
- feature (section 6.7)
- c) SNACK support (section 10.16) d) Requesting that parts of
- read data be acknowledged (section 10.7.2)
- e) Allegiance reassignment support (section 6.2.2)
- f) Terminating the entire iSCSI session to force the initiator to
- start over (section 6.1.4.4)
-
- For any outstanding SCSI command, it is assumed that iSCSI, in
- conjunction with SCSI at the initiator, is able to keep enough
- information to be able to rebuild the command PDU, and that outgoing
- data is available (in host memory) for retransmission while the
- command is outstanding. It is 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 is further assumed that a target will keep the "status & 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
-
-
-
-Satran, et al. Standards Track [Page 68]
-
-RFC 3720 iSCSI April 2004
-
-
- until either the status for the completed command is acknowledged, or
- the data in question has been separately acknowledged.
-
-6.1.4. Recovery Classes
-
- iSCSI enables the following classes of recovery (in the 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 detailed in the rest of this section are
- representative rather than exclusive. In every case, they detail the
- lowest class recovery that MAY be attempted. The implementer is left
- to decide under which circumstances to escalate to the next recovery
- class and/or what 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 has the choice of deferring errors to
- the SCSI initiator (with an appropriate response code), in which case
- the task, if any, has to be removed from the target and all the side
- effects, such as ACA, must be considered.
-
- Use of within-connection and within-command recovery classes MUST NOT
- be attempted before the connection is in 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 and used.
-
-6.1.4.1. Recovery Within-command
-
- At the target, the following 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 6.7
- Digest Errors, using the option of a recovery R2T.
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 69]
-
-RFC 3720 iSCSI April 2004
-
-
- 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 6.8 Sequence
- Errors, 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 6.8 Sequence Errors, using the option of a recovery
- R2T.
-
- At the initiator, the following 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 6.7
- Digest Errors, using the option of a SNACK.
- b) Sequence reception timeout (no status) or response reception
- timeout - dealt with as specified in Section 6.8 Sequence
- Errors, 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 6.8 Sequence Errors, 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. Sequence reception timeout is generally a
- large enough value to allow the data sequence transfer to be
- complete.
-
-6.1.4.2. Recovery Within-connection
-
- At the initiator, the following cases lend themselves to
- within-connection recovery:
-
- - Requests not acknowledged for a long time. Requests are
- acknowledged explicitly through ExpCmdSN or implicitly by
- receiving data and/or status. The initiator MAY retry
- non-acknowledged commands as specified in Section 6.2 Retry and
- Reassign in Recovery.
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 70]
-
-RFC 3720 iSCSI April 2004
-
-
- - 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 by receiving a Response PDU with a
- higher StatSN than expected. In the first case, digest error
- handling is done as specified in Section 6.7 Digest Errors using
- the option of a SNACK. In the second case, sequence error
- handling is done as specified in Section 6.8 Sequence Errors,
- using the option of a SNACK.
-
- At the target, the following 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.
-
-6.1.4.3. Connection Recovery
-
- At an iSCSI initiator, the following cases lend themselves to
- connection recovery:
-
- - TCP connection failure: The initiator MUST close the connection.
- It then MUST either implicitly or explicitly logout 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 10.5.1 Function). 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.
-
- - Receiving an Asynchronous Message that indicates one or all
- connections in a session has been dropped. The initiator MUST
- handle it as a TCP connection failure for the connection(s)
- referred to in the Message.
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 71]
-
-RFC 3720 iSCSI April 2004
-
-
- At an iSCSI target, the following 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 it has dropped the
- connection. Then, the target will wait for the initiator to
- continue recovery.
-
-6.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 the closing of 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 F. - Clearing Effects of Various Events on
- Targets -.
-
-6.1.5. Error Recovery Hierarchy
-
- The error recovery classes described so far are organized into a
- hierarchy for ease in understanding and to limit the implementation
- complexity. With few and well defined recovery levels
- interoperability is easier to achieve. The attributes of this
- hierarchy are as follows:
-
- a) Each level is a superset of the capabilities of the previous
- level. For example, Level 1 support implies supporting all
- capabilities of Level 0 and more.
- b) As a corollary, supporting a higher error recovery level means
- increased sophistication and possibly an increase in resource
- requirements.
- c) Supporting error recovery level "n" is advertised and
- negotiated by each iSCSI entity by exchanging the text key
- "ErrorRecoveryLevel=n". The lower of the two exchanged values
- is the operational ErrorRecoveryLevel for the session.
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 72]
-
-RFC 3720 iSCSI April 2004
-
-
- The following diagram represents the error recovery hierarchy.
-
- +
- /
- / 2 \ <-- Connection recovery
- +-----+
- / 1 \ <-- Digest failure recovery
- +---------+
- / 0 \ <-- Session failure recovery
- +-------------+
-
- The following table lists the error recovery capabilities expected
- from the implementations that support each error recovery level.
-
- +-------------------+--------------------------------------------+
- |ErrorRecoveryLevel | Associated Error recovery capabilities |
- +-------------------+--------------------------------------------+
- | 0 | Session recovery class |
- | | (Section 6.1.4.4 Session Recovery) |
- +-------------------+--------------------------------------------+
- | 1 | Digest failure recovery (See Note below.) |
- | | plus the capabilities of ER Level 0 |
- +-------------------+--------------------------------------------+
- | 2 | Connection recovery class |
- | | (Section 6.1.4.3 Connection Recovery) |
- | | plus the capabilities of ER Level 1 |
- +-------------------+--------------------------------------------+
-
- Note: Digest failure recovery is comprised of two recovery classes:
- Within-Connection recovery class (Section 6.1.4.2 Recovery Within-
- connection) and Within-Command recovery class (Section 6.1.4.1
- Recovery Within-command).
-
- When a defined value of ErrorRecoveryLevel is proposed by an
- originator in a text negotiation, the originator MUST support the
- functionality defined for the proposed value and additionally, the
- functionality corresponding to any defined value numerically less
- than the proposed. When a defined value of ErrorRecoveryLevel is
- returned by a responder in a text negotiation, the responder MUST
- support the functionality corresponding to the ErrorRecoveryLevel it
- is accepting.
-
- When either party attempts to use error recovery functionality beyond
- what is negotiated, the recovery attempts MAY fail unless an a priori
- agreement outside the scope of this document exists between the two
- parties to provide such support.
-
-
-
-
-
-Satran, et al. Standards Track [Page 73]
-
-RFC 3720 iSCSI April 2004
-
-
- Implementations MUST support error recovery level "0", while the rest
- are OPTIONAL to implement. In implementation terms, the above
- striation means that the following incremental sophistication with
- each level is required.
-
- +-------------------+---------------------------------------------+
- |Level transition | Incremental requirement |
- +-------------------+---------------------------------------------+
- | 0->1 | PDU retransmissions on the same connection |
- +-------------------+---------------------------------------------+
- | 1->2 | Retransmission across connections and |
- | | allegiance reassignment |
- +-------------------+---------------------------------------------+
-
-6.2. Retry and Reassign in Recovery
-
- This section summarizes two important and somewhat related iSCSI
- protocol features used in error recovery.
-
-6.2.1. Usage of Retry
-
- By resending the same iSCSI command PDU ("retry") in the absence of a
- command acknowledgement (by way of an ExpCmdSN update) or a response,
- an initiator attempts to "plug" (what it thinks are) the
- discontinuities in CmdSN ordering on the target end. Discarded
- command PDUs, due to digest errors, may have created these
- discontinuities.
-
- Retry MUST NOT be used for reasons other than plugging command
- sequence gaps, and in particular, cannot be used for requesting PDU
- retransmissions from a target. Any such PDU retransmission requests
- for a currently allegiant command in progress may be made using the
- SNACK mechanism described in section 10.16, although the usage of
- SNACK is OPTIONAL.
-
- If initiators, as part of plugging command sequence gaps as described
- above, inadvertently issue retries for allegiant commands already in
- progress (i.e., targets did not see the discontinuities in CmdSN
- ordering), the duplicate commands are silently ignored by targets as
- specified in section 3.2.2.1.
-
- When an iSCSI command is retried, the command PDU MUST carry the
- original Initiator Task Tag and the original operational attributes
- (e.g., flags, function names, LUN, CDB etc.) as well as the original
- CmdSN. The command being retried MUST be sent on the same connection
- as the original command unless the original connection was already
- successfully logged out.
-
-
-
-
-Satran, et al. Standards Track [Page 74]
-
-RFC 3720 iSCSI April 2004
-
-
-6.2.2. Allegiance Reassignment
-
- By issuing a "task reassign" task management request (Section 10.5.1
- Function), the initiator signals its intent to continue an already
- active command (but with no current connection allegiance) as part of
- connection recovery. This means that a new connection allegiance is
- requested for the command, which seeks to associate it to the
- connection on which the task management request is being issued.
- Before the allegiance reassignment is attempted for a task, an
- implicit or explicit Logout with the reason code "remove the
- connection for recovery" ( see section 10.14) MUST be successfully
- completed for the previous connection to which the task was
- allegiant.
-
- In reassigning connection allegiance for a command, the targets
- SHOULD continue the command from its current state. For example,
- when reassigning read commands, the target SHOULD take advantage of
- the ExpDataSN field provided by the Task Management function request
- (which must be set to zero if there was no data transfer) and bring
- the read command to completion by sending the remaining data and
- sending (or resending) the status. ExpDataSN acknowledges all data
- sent up to, but not including, the Data-In PDU and or R2T with DataSN
- (or R2TSN) equal to ExpDataSN. However, targets may choose to
- send/receive all unacknowledged data or all of the data on a
- reassignment of connection allegiance if unable to recover or
- maintain an accurate state. Initiators MUST not subsequently request
- data retransmission through Data SNACK for PDUs numbered less than
- ExpDataSN (i.e., prior to the acknowledged sequence number). For all
- types of commands, a reassignment request implies that the task is
- still considered in progress by the initiator and the target must
- conclude the task appropriately if the target returns the "Function
- Complete" response to the reassignment request. This might possibly
- involve retransmission of data/R2T/status PDUs as necessary, but MUST
- involve the (re)transmission of the status PDU.
-
- It is OPTIONAL for targets to support the allegiance reassignment.
- This capability is negotiated via the ErrorRecoveryLevel text key
- during the login time. When a target does not support allegiance
- reassignment, it MUST respond with a Task Management response code of
- "Allegiance reassignment not supported". If allegiance reassignment
- is supported by the target, but the task is still allegiant to a
- different connection, or a successful recovery Logout of the
- previously allegiant connection was not performed, the target MUST
- respond with a Task Management response code of "Task still
- allegiant".
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 75]
-
-RFC 3720 iSCSI April 2004
-
-
- If allegiance reassignment is supported by the target, the Task
- Management response to the reassignment request MUST be issued before
- the reassignment becomes effective.
-
- If a SCSI Command that involves data input is reassigned, any SNACK
- Tag it holds for a final response from the original connection is
- deleted and the default value of 0 MUST be used instead.
-
-6.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 terminate the task, a Response PDU (SCSI, Text,
- Task, etc.) must be returned by the target to conclude the task. If
- the task had never been active before the Reject (i.e., the Reject is
- on the command PDU), targets should not send any further responses
- because the command itself is being discarded.
-
- The above rule means that the initiator can eventually expect a
- response on receiving Rejects, if the received Reject is for a PDU
- other than the command PDU itself. The non-command Rejects only have
- diagnostic value in logging the errors, and they can be used for
- retransmission decisions by the initiators.
-
- The CmdSN of the rejected command PDU (if it is a non-immediate
- command) MUST NOT be considered received by the target (i.e., a
- command sequence gap must be assumed for the CmdSN), even though the
- CmdSN of the rejected command PDU may be reliably ascertained. Upon
- receiving the Reject, the initiator MUST plug the CmdSN gap in order
- to continue to use the session. The gap may be plugged either by
- transmitting a command PDU with the same CmdSN, or by aborting the
- task (see section 6.9 on how an abort may plug a CmdSN gap).
-
- When a data PDU is rejected and its DataSN can be ascertained, a
- target MUST advance ExpDataSN for the current data burst if a
- recovery R2T is being generated. The target MAY advance its
- ExpDataSN if it does not attempt to recover the lost data PDU.
-
-6.4. Connection Timeout Management
-
- iSCSI defines two session-global timeout values (in seconds)
- - Time2Wait and Time2Retain - that are applicable when an iSCSI Full
- Feature Phase connection is taken out of service either intentionally
- or by an exception. Time2Wait is the initial "respite time" before
- attempting an explicit/implicit Logout for the CID in question or
- task reassignment for the affected tasks (if any). Time2Retain is
- the maximum time after the initial respite interval that the task
- and/or connection state(s) is/are guaranteed to be maintained on the
-
-
-
-Satran, et al. Standards Track [Page 76]
-
-RFC 3720 iSCSI April 2004
-
-
- target to cater to a possible recovery attempt. Recovery attempts
- for the connection and/or task(s) SHOULD NOT be made before Time2Wait
- seconds, but MUST be completed within Time2Retain seconds after that
- initial Time2Wait waiting period.
-
-6.4.1. Timeouts on Transport Exception Events
-
- A transport connection shutdown or a transport reset without any
- preceding iSCSI protocol interactions informing the end-points of the
- fact causes a Full Feature Phase iSCSI connection to be abruptly
- terminated. The timeout values to be used in this case are the
- negotiated values of defaultTime2Wait (Section 12.15
- DefaultTime2Wait) and DefaultTime2Retain (Section 12.16
- DefaultTime2Retain) text keys for the session.
-
-6.4.2. Timeouts on Planned Decommissioning
-
- Any planned decommissioning of a Full Feature Phase iSCSI connection
- is preceded by either a Logout Response PDU, or an Async Message PDU.
- The Time2Wait and Time2Retain field values (section 10.15) in a
- Logout Response PDU, and the Parameter2 and Parameter3 fields of an
- Async Message (AsyncEvent types "drop the connection" or "drop all
- the connections"; section 10.9.1) specify the timeout values to be
- used in each of these cases.
-
- These timeout values are only applicable for the affected connection,
- and the tasks active on that connection. These timeout values have
- no bearing on initiator timers (if any) that are already running on
- connections or tasks associated with that session.
-
-6.5. Implicit Termination of Tasks
-
- A target implicitly terminates the active tasks due to iSCSI protocol
- dynamics in the following cases:
-
- a) When a connection is implicitly or explicitly logged out with
- the reason code of "Close the connection" and there are active
- tasks allegiant to that connection.
-
- b) When a connection fails and the connection state eventually
- times out (state transition M1 in Section 7.2.2 State
- Transition Descriptions for Initiators and Targets) and there
- are active tasks allegiant to that connection.
-
- c) When a successful Logout with the reason code of "remove the
- connection for recovery" is performed while there are active
- tasks allegiant to that connection, and those tasks eventually
-
-
-
-
-Satran, et al. Standards Track [Page 77]
-
-RFC 3720 iSCSI April 2004
-
-
- 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 of "Close the session" and there are active
- tasks in that session.
-
- If the tasks terminated in the above cases a), b, c) and d)are SCSI
- tasks, they must be internally terminated as if with CHECK CONDITION
- status. This status is only meaningful for appropriately handling
- the internal SCSI state and SCSI side effects with respect to
- ordering because this status is never communicated back as a
- terminating status to the initiator. However additional actions may
- have to be taken at SCSI level depending on the SCSI context as
- defined by the SCSI standards (e.g., queued commands and ACA, in
- cases a), b), and c), 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, and the ASC/ASCQ value of 47h/7Fh - "SOME COMMANDS CLEARED
- BY ISCSI PROTOCOL EVENT" , etc. - see [SAM2] and [SPC3]).
-
-6.6. Format Errors
-
- The following 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 10 iSCSI PDU Formats).
- b) Inconsistent field contents (consistent field contents are
- specified in Section 10 iSCSI PDU Formats).
-
- Format errors indicate 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 either with a connection close or with a connection reset and
- escalate the format error to session recovery (see Section 6.1.4.4
- Session Recovery).
-
-6.7. Digest Errors
-
- The discussion of the legal choices in handling digest errors below
- excludes session recovery as an explicit option, but either party
- detecting a digest error may choose to escalate the error to session
- recovery.
-
-
-
-
-
-Satran, et al. Standards Track [Page 78]
-
-RFC 3720 iSCSI April 2004
-
-
- When a target or an initiator receives 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. Because the
- digest error indicates that the length field of the header may have
- been corrupted, the location of the beginning of a later PDU needs to
- be reliably ascertained by other means such as the operation of a
- sync and steering layer.
-
- When a target receives 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, 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 response PDU with a CHECK
- CONDITION Status and an iSCSI Condition of "protocol service
- CRC error" (Section 10.4.7.2 Sense Data). 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 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 case of immediate data being present on
- a discarded command, the immediate data is implicitly recovered
- when the task is retried (see section 6.2.1), followed by the
- entire data transfer for the task.
-
- When an initiator receives 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:
- i) 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 10.4.7.2 Sense Data).
- ii) 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
-
-
-
-Satran, et al. Standards Track [Page 79]
-
-RFC 3720 iSCSI April 2004
-
-
- Status and an iSCSI Condition of "protocol service CRC
- error" (Section 10.4.7.2 Sense Data).
- b) Abort the task and terminate the command with an error.
-
- - If the discarded PDU is a response PDU, the initiator MUST do one
- of the following:
-
- a) Request PDU retransmission with a status SNACK.
- b) Logout the connection for recovery and continue the tasks on a
- different connection instance as described in Section 6.2 Retry
- and Reassign in Recovery.
- c) Logout to close the connection (abort all the commands
- associated with the connection).
-
- - No further action is necessary for initiators if the discarded PDU
- is an unsolicited PDU (e.g., Async, Reject). Task timeouts as in
- the initiator waiting for a command completion, or process
- timeouts, as in the target waiting for a Logout, will ensure that
- the correct operational behavior will result in these cases
- despite the discarded PDU.
-
-6.8. Sequence Errors
-
- When an initiator receives 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 that the initiator must have detected a
- header or payload digest error on one or more earlier R2T/data PDUs.
- The initiator MUST address these implied digest errors as described
- in Section 6.7 Digest Errors. When a target receives a data PDU with
- an out of order DataSN, it means that 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 6.7 Digest Errors.
-
- When an initiator receives 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 6.7 Digest Errors.
- 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 receives duplicate R2TSNs (due to proactive
- retransmission of R2Ts by the target) or duplicate DataSNs (due to
- proactive SNACKs by the initiator), it MUST discard the duplicates.
-
-
-
-
-
-Satran, et al. Standards Track [Page 80]
-
-RFC 3720 iSCSI April 2004
-
-
-6.9. SCSI Timeouts
-
- An iSCSI initiator MAY attempt to plug a command sequence gap on the
- target end (in the absence of an acknowledgement of the command by
- way of ExpCmdSN) before the ULP timeout by retrying the
- unacknowledged command, as described in Section 6.2 Retry and
- Reassign in Recovery.
-
- On a ULP timeout for a command (that carried a CmdSN of n), if the
- iSCSI initiator intends to continue the session, it MUST abort the
- command by either using an appropriate Task Management function
- request for the 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 due to one of the following reasons:
-
- - Original command was dropped due to digest error.
- - Connection on which the original command was sent was
- successfully logged out. Upon logout, the unacknowledged
- commands issued on the connection being logged out are
- discarded.
-
- If the abort request is received and the original command is missing,
- targets MUST consider the original command with that RefCmdSN to be
- 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 is received 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 of "Task Does Not
- Exist".
-
-6.10. Negotiation Failures
-
- Text request and response sequences, when used to set/negotiate
- operational parameters, constitute the negotiation/parameter setting.
- A negotiation failure is considered to be one or more of the
- following:
-
- - None of the choices, or the stated value, is acceptable to one
- of the sides in the negotiation.
- - The text request timed out and possibly terminated.
- - The text request was answered with a Reject PDU.
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 81]
-
-RFC 3720 iSCSI April 2004
-
-
- The following two rules should be used to address negotiation
- failures:
-
- - During Login, any failure in negotiation MUST be considered a
- login process failure and the Login Phase must be terminated,
- and with it, the connection. If the target detects the
- failure, it must terminate the login with the appropriate Login
- Response code.
-
- - A failure in negotiation, while in the Full Feature Phase, will
- terminate the entire negotiation sequence that 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).
-
-6.11. Protocol Errors
-
- Mapping framed messages over a "stream" connection, such as TCP,
- makes the proposed mechanisms vulnerable to simple software framing
- errors. On the other hand, the introduction of framing mechanisms to
- limit the effects of these errors may be onerous on performance for
- simple implementations. Command Sequence Numbers and the above
- mechanisms for connection drop and reestablishment help handle this
- type of mapping errors.
-
- All violations of iSCSI PDU exchange sequences specified in this
- document are also protocol errors. This category of errors can only
- be addressed by fixing the implementations; iSCSI defines Reject and
- response codes to enable this.
-
-6.12. Connection Failures
-
- iSCSI can keep a session in operation if it is able to
- keep/establish at least one TCP connection between the initiator and
- the target in a timely fashion. Targets and/or initiators may
- recognize a failing connection by either transport level means (TCP),
- a gap in the command sequence number, a response stream that is not
- filled for a long time, or by a failing iSCSI NOP (acting as a ping).
- The latter MAY be used periodically to increase the speed and
- likelihood of detecting connection failures. Initiators and targets
- MAY also use the keep-alive option on the TCP connection to enable
- early link failure detection on otherwise idle links.
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 82]
-
-RFC 3720 iSCSI April 2004
-
-
- On connection failure, the initiator and target MUST do one of the
- following:
-
- - Attempt connection recovery within the session (Section 6.1.4.3
- Connection Recovery).
-
- - Logout the connection with the reason code "closes the
- connection" (Section 10.14.5 Implicit termination of tasks),
- re-issue missing commands, and implicitly terminate all active
- commands. This option requires support for the
- within-connection recovery class (Section 6.1.4.2 Recovery
- Within-connection).
-
- - Perform session recovery (Section 6.1.4.4 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 similar 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 regardless of
- which of the above options is used (i.e., immediate commands are not
- recoverable across connection failures).
-
-6.13. Session Errors
-
- If all of the connections of a session fail and cannot be
- reestablished in a short time, or if initiators detect protocol
- errors repeatedly, an initiator may choose to terminate a session and
- establish a new session.
-
- In this case, the initiator takes the following actions:
-
- - Resets or closes all the transport connections.
- - Terminates all outstanding requests with an appropriate
- response before initiating a new session. If the same I_T
- nexus is intended to be reestablished, the initiator MUST
- employ session reinstatement (see section 5.3.5).
-
- When the session timeout (the connection state timeout for the last
- failed connection) happens on the target, it takes the following
- actions:
-
- - Resets or closes the TCP connections (closes the session).
- - Terminates all active tasks that were allegiant to the
- connection(s) that constituted the session.
-
- A target MUST also be prepared to handle a session reinstatement
- request from the initiator, that may be addressing session errors.
-
-
-
-Satran, et al. Standards Track [Page 83]
-
-RFC 3720 iSCSI April 2004
-
-
-7. State Transitions
-
- iSCSI connections and iSCSI sessions go through several well-defined
- states from the time they are created to the time they are cleared.
-
- The connection state transitions are described in two separate but
- dependent state diagrams for ease in understanding. The first
- diagram, "standard connection state diagram", describes the
- connection state transitions when the iSCSI connection is not waiting
- for, or undergoing, a cleanup by way of an explicit or implicit
- Logout. The second diagram, "connection cleanup state diagram",
- describes the connection state transitions while performing the iSCSI
- connection cleanup.
-
- The "session state diagram" describes the state transitions an iSCSI
- session would go through during its lifetime, and it depends on the
- states of possibly multiple iSCSI connections that participate in the
- session.
-
- States and state transitions are described in the text, tables and
- diagrams. The diagrams are used for illustration. The text and the
- tables are the governing specification.
-
-7.1. Standard Connection State Diagrams
-
-7.1.1. State Descriptions for Initiators and Targets
-
- State descriptions for the standard connection state diagram are as
- follows:
-
- -S1: FREE
- -initiator: State on instantiation, or after successful
- connection closure.
- -target: State on instantiation, or after 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, possibly
- involving several PDU exchanges.
- -target: Waiting for the Login process to conclude, possibly
- involving several PDU exchanges.
-
-
-
-
-Satran, et al. Standards Track [Page 84]
-
-RFC 3720 iSCSI April 2004
-
-
- -S5: LOGGED_IN
- -initiator: In Full Feature Phase, waiting for all internal,
- iSCSI, and transport events.
- -target: In 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 completion of
- logout processing.
- -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 initiate
- the cleanup processing for this CSM.
- -target: Waiting for the cleanup process to start for this CSM.
-
-7.1.2. State Transition Descriptions for Initiators and Targets
-
- -T1:
- -initiator: Transport connect request was made (e.g., TCP SYN
- sent).
- -target: Illegal
- -T2:
- -initiator: 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: Received a valid transport connection request that
- establishes the transport connection.
- -T4:
- -initiator: Transport connection established, thus prompting the
- initiator to start the iSCSI Login.
- -target: 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, thus prompting the target to send the
- final iSCSI Login Response with a Status-Class of zero.
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 85]
-
-RFC 3720 iSCSI April 2004
-
-
- -T6:
- -initiator: Illegal
- -target: Timed out waiting for an iSCSI Login, transport
- disconnect indication was received, transport reset was
- received, or an internal event indicating a transport
- timeout was received. In all these cases, the connection is
- to be closed.
- -T7:
- -initiator - one of the following events caused the transition:
- - The final iSCSI Login Response was received with a
- non-zero Status-Class.
- - Login timed out.
- - A transport disconnect indication was received.
- - A transport reset was received.
- - An internal event was received indicating a transport
- timeout.
- - An internal event of receiving a Logout response (success)
- on another connection for a "close the session" Logout
- request was received.
-
- In all these cases, the transport connection is closed.
-
- -target - one of the following events caused the transition:
- - The final iSCSI Login Request to conclude the Login Phase
- was received, prompting the target to send the final iSCSI
- Login Response with a non-zero Status-Class.
- - Login timed out.
- - Transport disconnect indication was received.
- - Transport reset was received.
- - An internal event indicating a transport timeout was
- received.
- - On another connection a "close the session" Logout request
- was received.
- In all 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, thus closing this connection
- requiring no further cleanup.
- -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 is received,
- thus prompting the target to close this connection cleanly.
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 86]
-
-RFC 3720 iSCSI April 2004
-
-
- -T9, T10:
- -initiator: An internal event that indicates the readiness to
- start the Logout process was received, thus prompting an
- iSCSI Logout to be sent by the initiator.
- -target: An iSCSI Logout request was received.
- -T11, T12:
- -initiator: Async PDU with AsyncEvent "Request Logout" was
- received.
- -target: An internal event that requires the decommissioning of
- the connection is received, thus causing 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
- successful processing of the Logout, 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 is received. In all these cases, the
- transport connection is closed.
-
- -T14:
- -initiator: Async PDU with AsyncEvent "Request Logout" was
- received again.
- -target: Illegal
- -T15, T16:
- -initiator: One or more of the following events caused this
- transition:
- -Internal event that indicates a transport connection
- timeout was received thus prompting transport RESET or
- transport connection closure.
- -A transport RESET.
- -A transport disconnect indication.
- -Async PDU with AsyncEvent "Drop connection" (for this CID).
- -Async PDU with AsyncEvent "Drop all connections".
- -target: One or more of the following events caused this
- transition:
- -Internal event that indicates a transport connection
- timeout was received, thus prompting transport RESET or
- transport connection closure.
- -An internal event of a failed connection/session
- reinstatement is received.
- -A transport RESET.
- -A transport disconnect indication.
-
-
-
-Satran, et al. Standards Track [Page 87]
-
-RFC 3720 iSCSI April 2004
-
-
- -Internal emergency cleanup event was received which prompts
- an Async PDU with AsyncEvent "Drop connection" (for this
- CID), or event "Drop all connections".
- -T17:
- -initiator: One or more of the following events caused this
- transition:
- -Logout response, (failure i.e., a non-zero status) was
- received, or Logout timed out.
- -Any of the events specified for T15 and T16.
- -target: One or more of the following events caused this
- transition:
- -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.
- -Any of the events specified for T15 and T16.
- -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 is received. In
- both these cases, the connection is closed.
-
- The CLEANUP_WAIT state (S8) implies that there are possible iSCSI
- tasks that have not reached conclusion and are still considered busy.
-
-7.1.3. Standard Connection State Diagram for an Initiator
-
- Symbolic names for States:
-
- S1: FREE
- S2: XPT_WAIT
- S4: IN_LOGIN
- S5: LOGGED_IN
- S6: IN_LOGOUT
- S7: LOGOUT_REQUESTED
- S8: CLEANUP_WAIT
-
-
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 88]
-
-RFC 3720 iSCSI April 2004
-
-
- States S5, S6, and S7 constitute the Full Feature Phase operation of
- the connection.
-
- The state diagram is as follows:
-
- -------<-------------+
- +--------->/ 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
- +---------------------------+
-
-
-
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 89]
-
-RFC 3720 iSCSI April 2004
-
-
- The following state transition table represents the above diagram.
- Each row represents the starting state for a given transition, which
- after taking a transition marked in a table cell would end in the
- state represented by the column of the cell. For example, from state
- S1, the connection takes the T1 transition to arrive at state S2.
- The fields marked "-" correspond to 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| - |- |- | - | - | - | - |
- ---+----+---+---+---+---+----+---+
-
-7.1.4. Standard Connection State Diagram for a Target
-
- Symbolic names for States:
-
- S1: FREE
- S3: XPT_UP
- S4: IN_LOGIN
- S5: LOGGED_IN
- S6: IN_LOGOUT
- S7: LOGOUT_REQUESTED
- S8: CLEANUP_WAIT
-
- States S5, S6, and S7 constitute the Full Feature Phase operation of
- the connection.
-
-
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 90]
-
-RFC 3720 iSCSI April 2004
-
-
- The state diagram is as follows:
-
- -------<-------------+
- +--------->/ 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
- +---------------------------+
-
- The following state transition table represents the above diagram,
- and follows the conventions described for the initiator diagram.
-
-
-
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 91]
-
-RFC 3720 iSCSI April 2004
-
-
- +----+---+---+---+---+----+---+
- |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| - |- |- | - | - | - | - |
- ---+----+---+---+---+---+----+---+
-
-7.2. Connection Cleanup State Diagram for Initiators and Targets
-
- Symbolic names for states:
-
- R1: CLEANUP_WAIT (same as S8)
- R2: IN_CLEANUP
- R3: FREE (same as S1)
-
- Whenever a connection state machine (e.g., CSM-C) enters the
- CLEANUP_WAIT state (S8), it must go through the state transitions
- described in the connection cleanup state diagram either a) using a
- separate full-feature phase connection (let's call it CSM-E) in the
- LOGGED_IN state in the same session, or b) using a new transport
- connection (let's call it CSM-I) in the FREE state that is to be
- added to the same session. In the CSM-E case, an explicit logout for
- the CID that corresponds to CSM-C (either as a connection or session
- logout) needs to be performed to complete the cleanup. In the CSM-I
- case, an implicit logout for the CID that corresponds to CSM-C needs
- to be performed by way of connection reinstatement (section 5.3.4)
- for that CID. In either case, the protocol exchanges on CSM-E or
- CSM-I determine the state transitions for CSM-C. Therefore, this
- cleanup state diagram is only applicable to the instance of the
- connection in cleanup (i.e., CSM-C). In the case of an implicit
- logout for example, CSM-C reaches FREE (R3) at the time CSM-I reaches
- LOGGED_IN. In the case of an explicit logout, CSM-C reaches FREE
- (R3) when CSM-E receives a successful logout response while
- continuing to be in the LOGGED_IN state.
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 92]
-
-RFC 3720 iSCSI April 2004
-
-
- An initiator must initiate an explicit or implicit connection logout
- for a connection in the CLEANUP_WAIT state, if the initiator intends
- to continue using the associated iSCSI session.
-
- The following state diagram applies to both initiators and targets.
-
- -------
- / R1 \
- +--\ /<-+
- / ---+---
- / | \ M3
- M1 | |M2 |
- | | /
- | | /
- | | /
- | V /
- | ------- /
- | / R2 \
- | \ /
- | -------
- | |
- | |M4
- | |
- | |
- | |
- | V
- | -------
- | / R3 \
- +---->\ /
- -------
-
- The following state transition table represents the above diagram,
- and follows the same conventions as in earlier sections.
-
- +----+----+----+
- |R1 |R2 |R3 |
- -----+----+----+----+
- R1 | - |M2 |M1 |
- -----+----+----+----+
- R2 |M3 | - |M4 |
- -----+----+----+----+
- R3 | - | - | - |
- -----+----+----+----+
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 93]
-
-RFC 3720 iSCSI April 2004
-
-
-7.2.1. State Descriptions for Initiators and Targets
-
- -R1: CLEANUP_WAIT (Same as S8)
- -initiator: Waiting for the internal event to initiate 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.
-
-7.2.2. State Transition Descriptions for Initiators and Targets
-
- -M1: One or more of the following events was 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, thus prompting a
- connection (or session) reinstatement Login to be sent
- transitioning CSM-I to state IN_LOGIN.
- -target: A connection/session reinstatement Login was
- received while in state XPT_UP.
- -In CSM-E usage:
- -initiator: An internal event that indicates that 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.
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 94]
-
-RFC 3720 iSCSI April 2004
-
-
- -M3: Logout failure 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: CSM-E either moved out of LOGGED_IN, or Logout
- timed out and/or aborted, or Logout response (failure)
- was received.
- -target: CSM-E either moved out of LOGGED_IN, Logout timed
- out and/or aborted, or an internal event that indicates a
- failed Logout processing was received. A Logout response
- (failure) was sent in the last case.
-
- -M4: 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.
-
-7.3. Session State Diagrams
-
-7.3.1. Session State Diagram for an Initiator
-
- Symbolic Names for States:
-
- Q1: FREE
- Q3: LOGGED_IN
- Q4: FAILED
-
- State Q3 represents the Full Feature Phase operation of the session.
-
-
-
-Satran, et al. Standards Track [Page 95]
-
-RFC 3720 iSCSI April 2004
-
-
- The state diagram is as follows:
-
- -------
- / 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 | - |
- -----+----+----+----+
-
-7.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 represents the Full Feature Phase operation of the session.
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 96]
-
-RFC 3720 iSCSI April 2004
-
-
- 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 | - |
- -----+----+----+----+----+----+
-
-7.3.3. State Descriptions for Initiators and Targets
-
- -Q1: FREE
- -initiator: State on instantiation or after cleanup.
- -target: State on instantiation or after cleanup.
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 97]
-
-RFC 3720 iSCSI April 2004
-
-
- -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 session continuation attempt to reach a
- conclusion.
-
-7.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 5.3.6 Session Continuation and Failure).
- -target: Graceful closing of the session via session closure
- (Section 5.3.6 Session Continuation and Failure) or a
- successful session reinstatement cleanly closed the session.
-
- -N4:
- -initiator: A session continuation attempt succeeded.
- -target: Illegal.
-
- -N5:
- -initiator: Session failure (Section 5.3.6 Session Continuation
- and Failure) occurred.
- -target: Session failure (Section 5.3.6 Session Continuation and
- Failure) occurred.
-
-
-
-Satran, et al. Standards Track [Page 98]
-
-RFC 3720 iSCSI April 2004
-
-
- -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 is 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.
-
-8. Security Considerations
-
- Historically, native storage systems have not had to consider
- security because their environments offered minimal security risks.
- That is, these environments consisted of storage devices either
- directly attached to hosts or connected via a Storage Area Network
- (SAN) distinctly separate from the communications network. The use
- of storage protocols, such as SCSI, over IP-networks requires that
- security concerns be addressed. 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).
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 99]
-
-RFC 3720 iSCSI April 2004
-
-
- Although technically possible, iSCSI SHOULD NOT be configured without
- security. iSCSI configured without security should be confined, in
- extreme cases, to closed environments without any security risk.
- [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.
-
-8.1. iSCSI Security Mechanisms
-
- The entities involved in iSCSI security are the initiator, target,
- and the IP communication end points. iSCSI scenarios in which
- multiple initiators or targets share a single communication end point
- are expected. To accommodate such scenarios, iSCSI uses two separate
- security mechanisms: In-band authentication between the initiator and
- the target at the iSCSI connection level (carried out by exchange of
- iSCSI Login PDUs), and packet protection (integrity, authentication,
- and confidentiality) by IPsec at the IP level. The two security
- mechanisms complement each other. The in-band authentication
- provides end-to-end trust (at login time) between the iSCSI initiator
- and the target while IPsec provides a secure channel between the IP
- communication end points.
-
- Further details on typical iSCSI scenarios and the relation between
- the initiators, targets, and the communication end points can be
- found in [RFC3723].
-
-8.2. In-band Initiator-Target Authentication
-
- During login, the target MAY authenticate the initiator and the
- initiator MAY authenticate the target. The authentication is
- performed on every new iSCSI connection by an exchange of iSCSI Login
- PDUs using a negotiated authentication method.
-
- The authentication method cannot assume an underlying IPsec
- protection, because IPsec is optional to use. An attacker should
- gain as little advantage as possible by inspecting the authentication
- phase PDUs. Therefore, a method using clear text (or equivalent)
- passwords is not acceptable; on the other hand, identity protection
- is not strictly required.
-
- The authentication mechanism protects against an unauthorized login
- to storage resources by using a false identity (spoofing). Once the
- authentication phase is completed, if the underlying IPsec is not
- used, all PDUs are sent and received in clear. The authentication
-
-
-
-
-
-Satran, et al. Standards Track [Page 100]
-
-RFC 3720 iSCSI April 2004
-
-
- mechanism alone (without underlying IPsec) should only be used when
- there is no risk of eavesdropping, message insertion, deletion,
- modification, and replaying.
-
- Section 11 iSCSI Security Text Keys and Authentication Methods
- defines several authentication methods and the exact steps that must
- be followed in each of them, including the iSCSI-text-keys and their
- allowed values in each step. Whenever an iSCSI initiator gets a
- response whose keys, or their values, are not according to the step
- definition, it MUST abort the connection. Whenever an iSCSI target
- gets a response whose keys, or their values, are not according to the
- step definition, it MUST answer with a Login reject with the
- "Initiator Error" or "Missing Parameter" status. These statuses are
- not intended for cryptographically incorrect values such as the CHAP
- response, for which "Authentication Failure" status MUST be
- specified. The importance of this rule can be illustrated in CHAP
- with target authentication (see Section 11.1.4 Challenge Handshake
- Authentication Protocol (CHAP)) where the initiator would have been
- able to conduct a reflection attack by omitting his response key
- (CHAP_R) using the same CHAP challenge as the target and reflecting
- the target's response back to the target. In CHAP, this is prevented
- because the target must answer the missing CHAP_R key with a Login
- reject with the "Missing Parameter" status.
-
- For some of the authentication methods, a key specifies the identity
- of the iSCSI initiator or target for authentication purposes. The
- value associated with that key MAY be different from the iSCSI name
- and SHOULD be configurable. (CHAP_N, see Section 11.1.4 Challenge
- Handshake Authentication Protocol (CHAP) and SRP_U, see Section
- 11.1.3 Secure Remote Password (SRP)).
-
-8.2.1. CHAP Considerations
-
- Compliant iSCSI initiators and targets MUST implement the CHAP
- authentication method [RFC1994] (according to Section 11.1.4
- Challenge Handshake Authentication Protocol (CHAP) including the
- target authentication option).
-
- When CHAP is performed over a non-encrypted channel, it is vulnerable
- to an off-line dictionary attack. Implementations MUST support use
- of 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 of an environment in which CHAP is used with
- a secret that has less than 96 random bits MUST enforce IPsec
- encryption (according to the implementation requirements in Section
-
-
-
-Satran, et al. Standards Track [Page 101]
-
-RFC 3720 iSCSI April 2004
-
-
- 8.3.2 Confidentiality) to protect the connection. Moreover, in this
- case IKE authentication with group pre-shared cryptographic keys
- SHOULD NOT be used unless it is not 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 in
- which it should send a CHAP response (CHAP_R, Section 11.1.4
- Challenge Handshake Authentication Protocol (CHAP)) unless it can
- verify that the CHAP secret is at least 96 bits, or that IPsec
- encryption is being used to protect the connection.
-
- Any CHAP secret used for initiator authentication MUST NOT be
- configured for authentication of any target, and any CHAP secret used
- for target authentication MUST NOT be configured for authentication
- of any initiator. If the CHAP response received by one end of an
- iSCSI connection is the same as the CHAP response that 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 ensures that the same CHAP secret is not
- 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.
- The following is an example of the attacks prevented by the above
- requirements:
-
- Rogue wants to impersonate Storage to Alice, and knows that a
- single secret is used for both directions of Storage-Alice
- authentication.
-
- Rogue convinces Alice to open two connections to Rogue, and Rogue
- identifies itself as Storage on both connections.
-
- Rogue issues a CHAP challenge on connection 1, waits for Alice to
- respond, and then reflects Alice's challenge as the initial
- challenge to Alice on connection 2.
-
- If Alice doesn't check for the reflection across connections,
- Alice's response on connection 2 enables Rogue to impersonate
- Storage on connection 1, even though Rogue does not 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 occurs.
-
-
-
-
-
-Satran, et al. Standards Track [Page 102]
-
-RFC 3720 iSCSI April 2004
-
-
- The same CHAP secret SHOULD NOT be configured for authentication of
- multiple initiators or multiple targets, as this enables any of them
- to impersonate any other one of them, and compromising one of them
- enables the attacker to impersonate any of them. It is recommended
- that iSCSI implementations check for use of identical CHAP secrets by
- different peers when this check is feasible, and take appropriate
- measures to warn users and/or administrators when this is 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 to avoid
- propagating security compromises 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) to verify the target's CHAP responses and do not know
- the target's CHAP secret.
-
- If an external response verification server (e.g., RADIUS) is not
- used, employing a single CHAP secret for authentication of a target
- to multiple initiators requires that all such initiators know that
- target secret. Any of these initiators can impersonate the target to
- any other such initiator, and compromise of such an initiator enables
- an attacker to impersonate the target to all such initiators.
- Targets SHOULD use separate CHAP secrets for authentication to each
- initiator when such risks are of concern; in this 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 among which
- such separation is desired.
-
-8.2.2. SRP Considerations
-
- The strength of the SRP authentication method (specified in
- [RFC2945]) is dependent on the characteristics of the group being
- used (i.e., the prime modulus N and generator g). As described in
- [RFC2945], N is required to be a Sophie-German 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].
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 103]
-
-RFC 3720 iSCSI April 2004
-
-
-8.3. IPsec
-
- iSCSI uses the IPsec mechanism for packet protection (cryptographic
- integrity, authentication, and confidentiality) at the IP level
- between the iSCSI communicating end points. The following sections
- describe the IPsec protocols that must be implemented for data
- integrity and authentication, 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].
-
-8.3.1. Data Integrity and Authentication
-
- Data authentication and integrity is 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 integrity
- and authentication by implementing IPsec [RFC2401] with ESP [RFC2406]
- in tunnel mode and MAY provide data integrity and authentication by
- implementing IPsec with ESP in transport mode. The IPsec
- implementation MUST fulfill the following iSCSI specific
- requirements:
-
- - HMAC-SHA1 MUST be implemented [RFC2404].
- - AES CBC MAC with XCBC extensions SHOULD be implemented
- [RFC3566].
-
- The ESP anti-replay service MUST also be implemented.
-
- At the high speeds iSCSI is expected to operate, a single IPsec SA
- could rapidly cycle through the 32-bit IPsec sequence number space.
- In view of this, it may be desirable in the future for an iSCSI
- implementation that operates at speeds of 1 Gbps or greater to
- implement the IPsec sequence number extension [SEQ-EXT].
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 104]
-
-RFC 3720 iSCSI April 2004
-
-
-8.3.2. Confidentiality
-
- Confidentiality is provided by encrypting the data in every packet.
- When confidentiality is used it MUST be accompanied by data integrity
- and authentication to provide comprehensive protection against
- eavesdropping, message insertion, deletion, modification, and
- replaying.
-
- An iSCSI compliant initiator or target MUST provide confidentiality
- by implementing IPsec [RFC2401] with ESP [RFC2406] in tunnel mode and
- MAY provide confidentiality by implementing IPsec with ESP in
- transport mode, with the following iSCSI specific requirements:
-
- - 3DES in CBC mode MUST be implemented [RFC2451].
- - AES in Counter mode SHOULD be implemented [RFC3686].
-
- DES in CBC mode SHOULD NOT be used due to its inherent weakness. The
- NULL encryption algorithm MUST also be implemented.
-
-8.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] with the following iSCSI specific requirements:
-
- - Peer authentication using a pre-shared cryptographic key MUST be
- supported. Certificate-based peer authentication using digital
- signatures MAY be supported. Peer authentication using the
- public key encryption methods outlined in IKE sections 5.2 and
- 5.3[7] SHOULD NOT be used.
-
- - 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
- the pertinent Certificate Revocation List (CRL) before accepting
- a PKI certificate for use in IKE authentication procedures.
-
- - Conformant iSCSI implementations MUST support IKE Main Mode and
- SHOULD support Aggressive Mode. IKE main mode with pre-shared
- key authentication method SHOULD NOT be used when either the
- initiator or the target uses dynamically assigned IP 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.
-
-
-
-
-Satran, et al. Standards Track [Page 105]
-
-RFC 3720 iSCSI April 2004
-
-
- - In the IKE Phase 2 Quick Mode, exchanges for creating the Phase 2
- SA, the Identity Payload, fields MUST be present. ID_IPV4_ADDR,
- ID_IPV6_ADDR (if the protocol stack supports IPv6) and ID_FQDN
- Identity payloads MUST be supported; ID_USER_FQDN SHOULD be
- supported. The IP Subnet, IP Address Range, ID_DER_ASN1_DN, and
- ID_DER_ASN1_GN formats SHOULD NOT be used. The ID_KEY_ID
- Identity Payload MUST NOT be used.
-
- Manual cryptographic keying MUST NOT be used because it does not
- provide the necessary re-keying support.
-
- When IPsec is used, the receipt of an IKE Phase 2 delete message
- SHOULD NOT be interpreted as a reason for tearing down the iSCSI TCP
- connection. If additional traffic is sent on it, a new IKE Phase 2
- 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 not defined in the iSCSI standard.
-
- 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. Notes to Implementers
-
- This section notes 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 3.4.3 Consequences of the Model.
-
-9.1. Multiple Network Adapters
-
- The iSCSI protocol allows multiple connections, not all of which need
- to go over the same network adapter. If multiple network connections
- are to be utilized with hardware support, the iSCSI protocol
-
-
-
-
-Satran, et al. Standards Track [Page 106]
-
-RFC 3720 iSCSI April 2004
-
-
- 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.
-
- However, some task management commands may require some loose form of
- cooperation or replication at least on the target.
-
-9.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 clauses (particularly, Section 3.4.2
- SCSI Architecture Model) 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 to 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
- to 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 3.4.3 Consequences of the Model)
- 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.
-
-9.1.2. iSCSI Name, ISID, and TPGT Use
-
- The designers of the iSCSI protocol envisioned there being one iSCSI
- Initiator Node Name per operating system image on a machine. This
- enables SAN resource configuration and authentication schemes based
- on a system's identity. It supports the notion that it should be
- possible to assign access to storage resources based on "initiator
- device" identity.
-
-
-
-
-
-Satran, et al. Standards Track [Page 107]
-
-RFC 3720 iSCSI April 2004
-
-
- 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 (ISID for initiators) to enforce both
- the ISID and TSIH RULES (see Section 3.4.3 Consequences of the
- Model).
-
- 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
- anytime 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 either by pointing the
- component to a vendor-specific location for this datum or to a
- system-wide location. The structure of the ISID namespace (see
- Section 10.12.5 ISID 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 3.4.3 Consequences of the Model) at the initiator.
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 108]
-
-RFC 3720 iSCSI April 2004
-
-
- 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 unique worldwide. It is therefore important that when one
- chooses to reuse the iSCSI Node Name of a disabled unit, not to
- re-assign 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 pre-assigned 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 via private APIs driven by the
- vendor's own software.
-
-9.2. Autosense and Auto Contingent Allegiance (ACA)
-
- Autosense refers to the automatic return of sense data to the
- initiator in case a command did not complete successfully. iSCSI
- initiators and targets MUST support and use autosense.
-
- ACA helps preserve ordered command execution in the presence of
- errors. As iSCSI can have many commands in-flight between initiator
- and target, iSCSI initiators and targets SHOULD support ACA.
-
-9.3. iSCSI Timeouts
-
- iSCSI recovery actions are often dependent on iSCSI time-outs being
- recognized and acted upon before SCSI time-outs. Determining the
- right time-outs to use for various iSCSI actions (command
- acknowledgements expected, status acknowledgements, etc.) is very
- much dependent on infrastructure (hardware, links, TCP/IP stack,
- iSCSI driver). As a 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 the
- network load variability. For connection teardown the implementer
- may want to consider also the TCP common practice for the given
- infrastructure.
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 109]
-
-RFC 3720 iSCSI April 2004
-
-
- Text negotiations MAY also be subject to either time-limits or limits
- in the number of exchanges. Those SHOULD be generous enough to avoid
- affecting interoperability (e.g., allowing each key to be negotiated
- on a separate exchange).
-
- The relation between iSCSI timeouts and SCSI timeouts should also be
- considered. 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 will
- become active only where iSCSI is not planned to, or failed to,
- recover.
-
- The implementer may also want to consider the interaction between
- various iSCSI exception events - such as a digest failure - and
- subsequent timeouts. When iSCSI error recovery is active, a digest
- failure is likely to result in discovering a missing command or data
- PDU. In these cases, an implementer may want to lower the timeout
- values to enable faster initiation for recovery procedures.
-
-9.4. Command Retry and Cleaning Old Command Instances
-
- To avoid having old, retried command instances appear in a valid
- command window after a command sequence number wrap around, the
- protocol requires (see Section 3.2.2.1 Command Numbering and
- Acknowledging) that on every connection on which a retry has been
- issued, a non-immediate command be issued and acknowledged within a
- 2**31-1 commands interval from the CmdSN of the retried command.
- This requirement can be fulfilled by an implementation in several
- ways.
-
- The simplest technique to use 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 on which the retry was
- attempted. As errors are deemed rare events, this technique is
- probably the most effective, as it does not involve additional checks
- at the initiator when issuing commands.
-
-9.5. Synch and Steering Layer and Performance
-
- While a synch and steering layer is optional, an initiator/target
- that does not have it working against a target/initiator that demands
- synch and steering may experience performance degradation caused by
- packet reordering and loss. Providing a synch and steering mechanism
- is recommended for all high-speed implementations.
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 110]
-
-RFC 3720 iSCSI April 2004
-
-
-9.6. Considerations for State-dependent Devices and Long-lasting SCSI
- Operations
-
- Sequential access devices operate on the principle that the position
- of the device is based on the last command processed. As such,
- command processing order and knowledge of whether or not the previous
- command was processed is of the utmost importance to maintain data
- integrity. For example, inadvertent retries of SCSI commands when it
- is not known if the previous SCSI command was processed is a
- potential data integrity risk.
-
- For a sequential access device, consider the scenario in which a SCSI
- SPACE command to backspace one filemark is issued and then re-issued
- due to no status received for the command. If the first SPACE
- command was actually processed, the re-issued SPACE command, if
- processed, will cause the position to change. Thus, a subsequent
- write operation will write data to the wrong position and any
- previous data at that position will be overwritten.
-
- For a medium changer device, consider the scenario in which an
- EXCHANGE MEDIUM command (the SOURCE ADDRESS and DESTINATION ADDRESS
- are the same thus performing a swap) is issued and then re-issued due
- to no status received for the command. If the first EXCHANGE MEDIUM
- command was actually processed, the re-issued EXCHANGE MEDIUM
- command, if processed, will perform the swap again. The net effect
- is that a swap was not performed thus leaving a data integrity
- exposure.
-
- All commands that change the state of the device (as in SPACE
- commands for sequential access devices, and EXCHANGE MEDIUM for
- medium changer device), MUST be issued as non-immediate commands for
- deterministic and in order delivery to iSCSI targets.
-
- For many of those state changing commands, the execution model also
- assumes that the command is executed exactly once. Devices
- implementing READ POSITION and LOCATE provide a means for SCSI level
- command recovery and new tape-class devices should support those
- commands. In their absence a retry at SCSI level is difficult and
- error recovery at iSCSI level is advisable.
-
- Devices operating on long latency delivery subsystems and performing
- long lasting SCSI operations may need mechanisms that enable
- connection replacement while commands are running (e.g., during an
- extended copy operation).
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 111]
-
-RFC 3720 iSCSI April 2004
-
-
-9.6.1. Determining the Proper ErrorRecoveryLevel
-
- The implementation and use of a specific ErrorRecoveryLevel should be
- determined based on the deployment scenarios of a given iSCSI
- implementation. Generally, the following factors must be considered
- before deciding on the proper 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". 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.
-
-
- A consideration of the above factors for SCSI tape devices as an
- example suggests that implementations SHOULD use ErrorRecoveryLevel=1
- when transport connection failure is not a concern and SCSI level
- recovery is unavailable, and ErrorRecoveryLevel=2 when the connection
- failure is also of high likelihood during a backup/retrieval.
-
- For extended copy operations, implementations SHOULD use
- ErrorRecoveryLevel=2 whenever there is a relatively high likelihood
- of connection failure.
-
-10. iSCSI PDU Formats
-
- All multi-byte integers that are specified in formats defined in this
- document are to be represented in network byte order (i.e., big
- endian). Any field that appears in this document assumes that 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.
-
- Any compliant sender MUST set all bits not defined and all reserved
- fields to zero 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.
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 112]
-
-RFC 3720 iSCSI April 2004
-
-
-10.1. iSCSI PDU Length and Padding
-
- iSCSI PDUs are padded to the closest integer number of four byte
- words. The padding bytes SHOULD be sent as 0.
-
-10.2. PDU Template, Header, and Opcodes
-
- All iSCSI PDUs have one or more header segments and, optionally, a
- data segment. After the entire header segment group a header-digest
- MAY follow. The data segment MAY also be followed by a data-digest.
-
- The Basic Header Segment (BHS) is the first segment in all of the
- iSCSI PDUs. The BHS is a fixed-length 48-byte header segment. It
- MAY be followed by Additional Header Segments (AHS), a Header-Digest,
- a Data Segment, and/or a Data-Digest.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 113]
-
-RFC 3720 iSCSI April 2004
-
-
- The overall structure of an iSCSI PDU 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/ 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) /
- +/ /
- +---------------+---------------+---------------+---------------+
-
- All PDU segments and digests are padded to the closest integer number
- of four byte words. For example, all PDU segments and digests start
- at a four byte word boundary and the padding ranges from 0 to 3
- bytes. The padding bytes SHOULD be sent as 0.
-
- iSCSI response PDUs do not have AH Segments.
-
-10.2.1. Basic Header Segment (BHS)
-
- The BHS is 48 bytes long. The Opcode and DataSegmentLength fields
- appear in all iSCSI PDUs. In addition, when used, the Initiator Task
- Tag and Logical Unit Number always appear in the same location in the
- header.
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 114]
-
-RFC 3720 iSCSI April 2004
-
-
- The format of the BHS 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|.|I| Opcode |F| Opcode-specific fields |
- +---------------+---------------+---------------+---------------+
- 4|TotalAHSLength | DataSegmentLength |
- +---------------+---------------+---------------+---------------+
- 8| LUN or Opcode-specific fields |
- + +
- 12| |
- +---------------+---------------+---------------+---------------+
- 16| Initiator Task Tag |
- +---------------+---------------+---------------+---------------+
- 20/ Opcode-specific fields /
- +/ /
- +---------------+---------------+---------------+---------------+
- 48
-
-10.2.1.1 I
-
- For request PDUs, the I bit set to 1 is an immediate delivery marker.
-
-10.2.1.2. Opcode
-
- The Opcode indicates the type of iSCSI PDU the header encapsulates.
-
- The Opcodes are divided into two categories: initiator opcodes and
- target opcodes. Initiator opcodes are in PDUs sent by the initiator
- (request PDUs). Target opcodes are in PDUs sent by the target
- (response PDUs).
-
- Initiators MUST NOT use target opcodes and targets MUST NOT use
- initiator opcodes.
-
- Initiator opcodes defined in this specification are:
-
- 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 codes
-
-
-
-Satran, et al. Standards Track [Page 115]
-
-RFC 3720 iSCSI April 2004
-
-
-
- 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 Reject
-
- All other opcodes are reserved.
-
-10.2.1.3. Final (F) bit
-
- When set to 1 it indicates the final (or only) PDU of a sequence.
-
-10.2.1.4. Opcode-specific Fields
-
- These fields have different meanings for different opcode types.
-
-10.2.1.5. TotalAHSLength
-
- Total length of all AHS header segments in units of four byte words
- including padding, if any.
-
- The TotalAHSLength is only used in PDUs that have an AHS and MUST be
- 0 in all other PDUs.
-
-10.2.1.6. DataSegmentLength
-
- This is the data segment payload length in bytes (excluding padding).
- The DataSegmentLength MUST be 0 whenever the PDU has no data segment.
-
-10.2.1.7. LUN
-
- Some opcodes operate on a specific Logical Unit. The Logical Unit
- Number (LUN) field identifies which Logical Unit. If the opcode does
- not relate to a Logical Unit, this field is either ignored or may be
- used in an opcode specific way. The LUN field is 64-bits and should
-
-
-
-
-Satran, et al. Standards Track [Page 116]
-
-RFC 3720 iSCSI April 2004
-
-
- be formatted in accordance with [SAM2]. For example, LUN[0] from
- [SAM2] is BHS byte 8 and so on up to LUN[7] from [SAM2], which is BHS
- byte 15.
-
-10.2.1.8. Initiator Task Tag
-
- The initiator assigns a Task Tag to each iSCSI task it issues. While
- a task exists, this tag MUST uniquely identify the task session-wide.
- SCSI may also use the initiator task tag as part of the SCSI task
- identifier when the timespan during which an iSCSI initiator task tag
- must be unique extends over the timespan during which a SCSI task tag
- must be unique. However, the iSCSI Initiator Task Tag must exist and
- be unique even for untagged SCSI commands.
-
-10.2.2. Additional Header Segment (AHS)
-
- The general format of an AHS 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| AHSLength | AHSType | AHS-Specific |
- +---------------+---------------+---------------+---------------+
- 4/ AHS-Specific /
- +/ /
- +---------------+---------------+---------------+---------------+
- x
-
-10.2.2.1. AHSType
-
- The AHSType field is coded as follows:
-
- bit 0-1 - Reserved
-
- bit 2-7 - AHS code
-
- 0 - Reserved
- 1 - Extended CDB
- 2 - Expected Bidirectional Read Data Length
- 3 - 63 Reserved
-
-10.2.2.2. AHSLength
-
- This field contains the effective length in bytes of the AHS
- excluding AHSType and AHSLength and padding, if any. The AHS is
- padded to the smallest integer number of 4 byte words (i.e., from 0
- up to 3 padding bytes).
-
-
-
-Satran, et al. Standards Track [Page 117]
-
-RFC 3720 iSCSI April 2004
-
-
-10.2.2.3. Extended CDB AHS
-
- The format of the Extended CDB AHS 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| AHSLength (CDBLength-15) | 0x01 | Reserved |
- +---------------+---------------+---------------+---------------+
- 4/ ExtendedCDB...+padding /
- +/ /
- +---------------+---------------+---------------+---------------+
- x
-
- This type of AHS MUST NOT be used if the CDBLength is less than 17.
- The length includes the reserved byte 3.
-
-10.2.2.4. Bidirectional Expected Read-Data Length AHS
-
- The format of the Bidirectional Read Expected Data Transfer Length
- AHS 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| AHSLength (0x0005) | 0x02 | Reserved |
- +---------------+---------------+---------------+---------------+
- 4| Expected Read-Data Length |
- +---------------+---------------+---------------+---------------+
- 8
-
-10.2.3. Header Digest and Data Digest
-
- Optional header and data digests protect the integrity of the header
- and data, respectively. The digests, if present, are located,
- respectively, after the header and PDU-specific data, and cover
- respectively the header and the PDU data, each including the padding
- bytes, if any.
-
- The existence and type of digests are negotiated during the Login
- Phase.
-
- The separation of the header and data digests is useful in iSCSI
- routing applications, in which only the header changes when a message
- is forwarded. In this case, only the header digest should be
- recalculated.
-
-
-
-Satran, et al. Standards Track [Page 118]
-
-RFC 3720 iSCSI April 2004
-
-
- Digests are not included in data or header length fields.
-
- A zero-length Data Segment also implies a zero-length data-digest.
-
-10.2.4. Data Segment
-
- The (optional) Data Segment contains PDU associated data. Its
- payload effective length is provided in the BHS field -
- DataSegmentLength. The Data Segment is also padded to an integer
- number of 4 byte words.
-
-10.3. SCSI Command
-
- The format of the SCSI Command PDU 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|.|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) /
- +---------------+---------------+---------------+---------------+
-
-
-
-
-Satran, et al. Standards Track [Page 119]
-
-RFC 3720 iSCSI April 2004
-
-
-10.3.1. Flags and Task Attributes (byte 1)
-
- The flags for a SCSI Command are:
-
- bit 0 (F) is set to 1 when no unsolicited SCSI Data-Out PDUs follow
- this PDU. When F=1 for a write and if Expected Data
- Transfer Length is larger than the DataSegmentLength, the
- target may solicit additional 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-4 Reserved.
-
- bit 5-7 contains Task Attributes.
-
- Task Attributes (ATTR) have one of the following integer values (see
- [SAM2] for details):
-
- 0 - Untagged
- 1 - Simple
- 2 - Ordered
- 3 - Head of Queue
- 4 - ACA
- 5-7 - Reserved
-
- Setting both the W and the F bit to 0 is an error. Either or both of
- R and W MAY be 1 when either the Expected Data Transfer Length and/or
- Bidirectional Read Expected Data Transfer Length are 0, but they MUST
- NOT both be 0 when the Expected Data Transfer Length and/or
- Bidirectional Read Expected Data Transfer Length are not 0 (i.e.,
- when some data transfer is expected the transfer direction is
- indicated by the R and/or W bit).
-
-10.3.2. CmdSN - Command Sequence Number
-
- Enables ordered delivery across multiple connections in a single
- session.
-
-10.3.3. ExpStatSN
-
- Command responses up to ExpStatSN-1 (mod 2**32) have been received
- (acknowledges status) on the connection.
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 120]
-
-RFC 3720 iSCSI April 2004
-
-
-10.3.4. Expected Data Transfer Length
-
- For unidirectional operations, the Expected Data Transfer Length
- field contains the number of bytes of data involved in this SCSI
- operation. For a unidirectional write operation (W flag set to 1 and
- R flag set to 0), the initiator uses this field to specify the number
- of bytes of data it expects to transfer for this operation. For a
- unidirectional read operation (W flag set to 0 and R flag set to 1),
- the initiator uses this field to specify the number of bytes of data
- it expects the target to transfer to the initiator. It corresponds
- to the SAM2 byte count.
-
- For bidirectional operations (both R and W flags are set to 1), this
- field contains the number of data bytes involved in the write
- transfer. For bidirectional operations, an additional header segment
- MUST be present in the header sequence that indicates the
- Bidirectional Read Expected Data Transfer Length. The Expected Data
- Transfer Length field and the Bidirectional Read Expected Data
- Transfer Length field correspond to the SAM2 byte count
-
- If the Expected Data Transfer Length for a write and the length of
- the immediate data part that follows the command (if any) are the
- same, then no more data PDUs are expected to follow. In this case,
- the F bit MUST be set to 1.
-
- If the Expected Data Transfer Length is higher than the
- FirstBurstLength (the negotiated maximum 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.
-
- Upon completion of a data transfer, the target informs the initiator
- (through residual counts) of how many bytes were actually processed
- (sent and/or received) by the target.
-
-10.3.5. CDB - SCSI Command Descriptor Block
-
- There are 16 bytes in the CDB field to accommodate the commonly used
- CDBs. Whenever the CDB is larger than 16 bytes, an Extended CDB AHS
- MUST be used to contain the CDB spillover.
-
-10.3.6. Data Segment - Command Data
-
- Some SCSI commands require additional parameter data to accompany the
- SCSI command. This data may be placed beyond the boundary of the
- iSCSI header in a data segment. Alternatively, user data (e.g., from
- a WRITE operation) can be placed in the data segment (both cases are
-
-
-
-
-
-Satran, et al. Standards Track [Page 121]
-
-RFC 3720 iSCSI April 2004
-
-
- referred to as immediate data). These data are governed by the rules
- for solicited vs. unsolicited data outlined in Section 3.2.4.2 Data
- Transfer Overview.
-
-10.4. SCSI Response
-
- The format of the SCSI Response PDU 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|.|.| 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) |
- +---------------+---------------+---------------+---------------+
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 122]
-
-RFC 3720 iSCSI April 2004
-
-
-10.4.1. Flags (byte 1)
-
- bit 1-2 Reserved.
-
- bit 3 - (o) set for Bidirectional Read Residual Overflow. In this
- case, the Bidirectional Read Residual Count indicates the number
- of bytes that were not transferred to the initiator because the
- initiator's Expected Bidirectional Read Data Transfer Length was
- not sufficient.
-
- bit 4 - (u) set for Bidirectional Read Residual Underflow. In this
- case, the Bidirectional Read Residual Count indicates the number
- of bytes that were not transferred to the initiator out of the
- number of bytes expected to be transferred.
-
- bit 5 - (O) set for Residual Overflow. In this case, the Residual
- Count indicates the number of bytes that were not transferred
- because the initiator's Expected Data Transfer Length was not
- sufficient. For a bidirectional operation, the Residual Count
- contains the residual for the write operation.
-
- bit 6 - (U) set for Residual Underflow. In this case, the Residual
- Count indicates the number of bytes that were not transferred out
- of the number of bytes that were expected to be transferred. For
- a bidirectional operation, the Residual Count contains the
- residual for the write operation.
-
- bit 7 - (0) Reserved.
-
- Bits O and U and bits o and u are mutually exclusive (i.e., having
- both o and u or O and U set to 1 is a protocol error). For a
- response other than "Command Completed at Target", bits 3-6 MUST be
- 0.
-
-10.4.2. Status
-
- The Status field is used to report the SCSI status of the command (as
- specified in [SAM2]) and is only valid if the Response Code is
- Command Completed at target.
-
-
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 123]
-
-RFC 3720 iSCSI April 2004
-
-
- Some of the status codes defined in [SAM2] are:
-
- 0x00 GOOD
- 0x02 CHECK CONDITION
- 0x08 BUSY
- 0x18 RESERVATION CONFLICT
- 0x28 TASK SET FULL
- 0x30 ACA ACTIVE
- 0x40 TASK ABORTED
-
- See [SAM2] for the complete list and definitions.
-
- If a SCSI device error is detected while data from the initiator is
- still expected (the command PDU did not contain all the data and the
- target has not received a Data PDU with the final bit Set), the
- target MUST wait until it receives a Data PDU with the F bit set in
- the last expected sequence before sending the Response PDU.
-
-10.4.3. Response
-
- This field contains the iSCSI service response.
-
- iSCSI service response codes defined in this specification are:
-
- 0x00 - Command Completed at Target
- 0x01 - Target Failure
- 0x80-0xff - Vendor specific
-
- All other response codes are reserved.
-
- The Response is used to report a Service Response. The mapping of
- the response code into a SCSI service response code value, if needed,
- is outside the scope of this document. However, in symbolic terms
- response value 0x00 maps to the SCSI service response (see [SAM2] and
- [SPC3]) of TASK COMPLETE or LINKED COMMAND COMPLETE. All other
- Response values map to the SCSI service response of SERVICE DELIVERY
- OR TARGET FAILURE.
-
- If a PDU that includes SCSI status (Response PDU or Data-In PDU
- including status) does not arrive before the session is terminated,
- the SCSI service response is SERVICE DELIVERY OR TARGET FAILURE.
-
- A non-zero Response field indicates a failure to execute the command
- in which case the Status and Flag fields are undefined.
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 124]
-
-RFC 3720 iSCSI April 2004
-
-
-10.4.4. SNACK Tag
-
- This field contains a copy of the SNACK Tag of the last SNACK Tag
- accepted by the target on the same connection and for the command for
- which the response is issued. Otherwise it is reserved and should be
- set to 0.
-
- After issuing a R-Data SNACK the initiator must discard any SCSI
- status unless contained in an SCSI Response PDU carrying the same
- SNACK Tag as the last issued R-Data SNACK for the SCSI command on the
- current connection.
-
- For a detailed discussion on R-Data SNACK see Section 10.16 SNACK
- Request.
-
-10.4.5. Residual Count
-
- The Residual Count field MUST be valid in the case where either the U
- bit or the O bit is set. If neither bit is set, the Residual Count
- field is reserved. Targets may set the residual count and initiators
- may use it when the response code is "completed at target" (even if
- the status returned is not GOOD). If the O bit is set, the Residual
- Count indicates the number of bytes that were not transferred because
- the initiator's Expected Data Transfer Length was not sufficient. If
- the U bit is set, the Residual Count indicates the number of bytes
- that were not transferred out of the number of bytes expected to be
- transferred.
-
-10.4.6. Bidirectional Read Residual Count
-
- The Bidirectional Read Residual Count field MUST be valid in the case
- where either 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 "completed at target". If the o bit is
- set, the Bidirectional Read Residual Count indicates the number of
- bytes that were not transferred to the initiator because the
- initiator's Expected Bidirectional Read Transfer Length was not
- sufficient. If the u bit is set, the Bidirectional Read Residual
- Count indicates the number of bytes that were not transferred to the
- initiator out of the number of bytes expected to be transferred.
-
-10.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.
-
-
-
-
-Satran, et al. Standards Track [Page 125]
-
-RFC 3720 iSCSI April 2004
-
-
- For some iSCSI responses, the response data segment MAY contain some
- response related information, (e.g., for a target failure, it may
- contain a vendor specific detailed description of the failure).
-
- If the DataSegmentLength is not 0, the format of the Data Segment 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/ Response Data /
- / /
- +---------------+---------------+---------------+---------------+
- z|
-
-10.4.7.1. SenseLength
-
- Length of Sense Data.
-
-10.4.7.2. Sense Data
-
- The Sense Data contains detailed information about a check condition
- and [SPC3] specifies the format and content of the Sense Data.
-
- Certain iSCSI conditions result in the command being terminated at
- the target (response Command Completed at Target) with a SCSI Check
- Condition Status as outlined in the next table:
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 126]
-
-RFC 3720 iSCSI April 2004
-
-
- +--------------------------+----------+---------------------------+
- | iSCSI Condition |Sense | Additional Sense Code & |
- | |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 than
- FirstBurstLength. The target reports the same error when the amount
- of data sent as a reply to an R2T does not match the amount
- requested.
-
-10.4.8. ExpDataSN
-
- The number of R2T and Data-In (read) PDUs the target has sent for the
- command.
-
- This field MUST be 0 if the response code is not Command Completed at
- Target or the target sent no Data-In PDUs for the command.
-
-10.4.9. StatSN - Status Sequence Number
-
- StatSN is a Sequence Number that the target iSCSI layer generates per
- connection and that in turn, enables the initiator to acknowledge
- status reception. StatSN is incremented by 1 for every
- response/status sent on a connection except for responses sent as a
- result of a retry or SNACK. In the case of responses sent due to a
- retransmission request, the StatSN MUST be the same as the first time
- the PDU was sent unless the connection has since been restarted.
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 127]
-
-RFC 3720 iSCSI April 2004
-
-
-10.4.10. ExpCmdSN - Next Expected CmdSN from this Initiator
-
- ExpCmdSN is a Sequence Number that the target iSCSI returns to the
- initiator to acknowledge command reception. It is used to update a
- local variable with the same name. An ExpCmdSN equal to MaxCmdSN+1
- indicates that the target cannot accept new commands.
-
-10.4.11. MaxCmdSN - Maximum CmdSN from this Initiator
-
- MaxCmdSN is a Sequence Number that the target iSCSI returns to the
- initiator to indicate the maximum CmdSN the initiator can send. It
- is used to update a local variable with the same name. If MaxCmdSN
- is equal to ExpCmdSN-1, this indicates to the initiator that the
- target cannot receive any additional commands. When MaxCmdSN changes
- at the target while the target has no pending PDUs to convey this
- information to the initiator, it MUST generate a NOP-IN to carry the
- new MaxCmdSN.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 128]
-
-RFC 3720 iSCSI April 2004
-
-
-10.5. Task Management Function 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|.|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) |
- +---------------+---------------+---------------+---------------+
-
-10.5.1. Function
-
- The Task Management functions provide an initiator with a way to
- explicitly control the execution of one or more Tasks (SCSI and iSCSI
- tasks). The Task Management function codes are listed below. 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
- logical unit.
-
- 3 - CLEAR ACA - clears the Auto Contingent Allegiance condition.
-
-
-
-
-
-Satran, et al. Standards Track [Page 129]
-
-RFC 3720 iSCSI April 2004
-
-
- 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 Referenced Task Tag field to this connection,
- thus resuming the iSCSI exchanges for the task.
-
- For all these functions, the Task Management function response MUST
- be returned as detailed in Section 10.6 Task Management Function
- Response. All these functions apply to the referenced tasks
- regardless of whether they are 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 with CmdSN equal or exceeding CmdSN.
-
- If the task management request is marked for immediate delivery, it
- must be considered immediately for execution, but the operations
- involved (all or part of them) may be postponed to allow the target
- to receive all relevant tasks. According to [SAM2], for all the
- tasks covered by the Task Management response (i.e., with CmdSN lower
- than the task management command CmdSN) but except 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 (i.e., it is a matter of
- implementation if the SCSI responses, received before the Task
- Management response but after the task management request was issued,
- are 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 on its part MUST wait for responses on all affected target
-
-
-
-Satran, et al. Standards Track [Page 130]
-
-RFC 3720 iSCSI April 2004
-
-
- transfer tags before acting on either of these two task management
- requests. In case 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 within-command error recovery class (see Section
- 6.1.4.1 Recovery Within-command) if it is supporting
- ErrorRecoveryLevel >= 1, or alternatively 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 RefCmdSN MUST be that of the Task Management request itself
- (i.e., CmdSN and RefCmdSN are equal); otherwise RefCmdSN MUST be set
- to the CmdSN of the task to be aborted (lower than CmdSN).
-
- If the connection is still active (it is not undergoing an implicit
- or explicit logout), 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 (i.e., the task to be aborted will not have to be retried or
- reassigned, and its status, if issued but not acknowledged, will be
- reissued 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 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 and when implemented, 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 10.6 Task Management Function Response 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 Logical Units 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.
-
-
-
-Satran, et al. Standards Track [Page 131]
-
-RFC 3720 iSCSI April 2004
-
-
- The target MUST treat the TARGET COLD RESET function additionally 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 6.2 Retry and Reassign in
- Recovery.
-
- 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 Task Management response of "Function
- rejected".
-
- TASK REASSIGN MUST be issued as an immediate command.
-
-10.5.2. TotalAHSLength and DataSegmentLength
-
- For this PDU TotalAHSLength and DataSegmentLength MUST be 0.
-
-10.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) and is reserved in all others.
-
-10.5.4. Referenced Task Tag
-
- The Initiator Task Tag of the task to be aborted for the ABORT TASK
- function or reassigned for the TASK REASSIGN function. For all the
- other functions this field MUST be set to the reserved value
- 0xffffffff.
-
-10.5.5. RefCmdSN
-
- If an ABORT TASK is issued for a task created by an immediate command
- then RefCmdSN MUST be that of the Task Management request itself
- (i.e., CmdSN and RefCmdSN are equal).
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 132]
-
-RFC 3720 iSCSI April 2004
-
-
- For an ABORT TASK of a task created by non-immediate command 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
- 10.6.1 when the task identified by the Referenced Task Tag field is
- not with the target.
-
- Otherwise, this field is reserved.
-
-10.5.6. ExpDataSN
-
- For recovery purposes, the iSCSI target and initiator maintain a data
- acknowledgement reference number - the first input DataSN number
- unacknowledged by the initiator. When issuing a new command, this
- number is set to 0. If the function is TASK REASSIGN, which
- establishes a new connection allegiance for a previously issued Read
- or Bidirectional command, ExpDataSN will contain an updated data
- acknowledgement reference number or the value 0; the latter
- indicating that the data acknowledgement reference number is
- unchanged. 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
- acknowledgement reference number. The number of retransmitted PDUs
- may or may not be the same as the original transmission depending on
- if there was a change in MaxRecvDataSegmentLength in the
- reassignment. The target MAY also send no more Data-In PDUs if all
- data has been acknowledged.
-
- 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. Any other value MUST be ignored
- by the target.
-
- For other functions this field is reserved.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 133]
-
-RFC 3720 iSCSI April 2004
-
-
-10.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) |
- +---------------+---------------+---------------+---------------+
-
- 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 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.
-
-10.6.1. Response
-
- The target provides a Response, which may take on the following
- values:
-
- a) 0 - Function complete.
- b) 1 - Task does not exist.
- c) 2 - LUN does not exist.
- d) 3 - Task still allegiant.
- e) 4 - Task allegiance reassignment not supported.
-
-
-
-
-Satran, et al. Standards Track [Page 134]
-
-RFC 3720 iSCSI April 2004
-
-
- f) 5 - Task management function not supported.
- g) 6 - Function authorization failed.
- h) 255 - Function rejected.
-
- All other values are reserved.
-
- For a discussion on usage of response codes 3 and 4, see Section
- 6.2.2 Allegiance Reassignment.
-
- For the TARGET COLD RESET and TARGET WARM RESET functions, the target
- cancels all pending operations across all Logical Units known to the
- issuing initiator. For the TARGET COLD RESET function, the target
- MUST then close all of its TCP connections to all initiators
- (terminates all sessions).
-
- The mapping of the response code into a SCSI service response code
- value, if needed, is outside the scope of this document. However, in
- symbolic terms Response values 0 and 1 map to the SCSI service
- response of FUNCTION COMPLETE. All other Response values map to the
- SCSI service response of FUNCTION REJECTED. If a Task Management
- function response PDU does not arrive before the session is
- 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 commands affected have been received
- by the target, the corresponding task management functions have been
- executed by the SCSI target, and the delivery of all responses
- delivered until the task management function completion have been
- confirmed (acknowledged through ExpStatSN) by the initiator on all
- connections of this session. For the exact timeline of events, refer
- to Section 10.6.2 Task Management Actions on Task Sets.
-
- For the ABORT TASK function,
-
- 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 does not identify an existing task,
- but if 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 received
- and return the "Function complete" response.
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 135]
-
-RFC 3720 iSCSI April 2004
-
-
- c) If the Referenced Task Tag does not identify an existing task
- and if 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.
-
-10.6.2. Task Management Actions on Task Sets
-
- The execution of ABORT TASK SET and CLEAR TASK SET Task Management
- function requests consists of the following sequence of events in the
- specified order on each of the entities.
-
- The initiator:
-
- a) Issues ABORT TASK SET/CLEAR TASK SET request.
- b) Continues to respond to each target transfer tag received
- for the affected task set.
- c) Receives any responses for the tasks in the affected task
- set (may process them as usual because they are guaranteed
- to be valid).
- d) Receives the task set management response, thus concluding
- all the tasks in the affected task set.
-
- The target:
-
- a) Receives the ABORT TASK SET/CLEAR TASK SET request.
- b) Waits for all target transfer tags to be responded to and
- for all affected tasks in the task set to be received.
- c) Propagates the command to and receives the response from the
- target SCSI layer.
- d) Takes note of last-sent StatSN on each of the connections in
- the iSCSI sessions (one or more) sharing the affected task
- set, and waits for acknowledgement of each StatSN (may
- solicit for acknowledgement by way of a NOP-In). If some
- tasks originate from non-iSCSI I_T_L nexi then the means by
- which the target insures that all affected tasks have
- returned their status to the initiator are defined by the
- specific protocol.
-
- e) Sends the task set management response to the issuing
- initiator.
-
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 136]
-
-RFC 3720 iSCSI April 2004
-
-
-10.6.3. TotalAHSLength and DataSegmentLength
-
- For this PDU TotalAHSLength and DataSegmentLength MUST be 0.
-
-10.7. SCSI Data-Out & SCSI Data-In
-
- The SCSI Data-Out PDU for WRITE operations has the following 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|.|.| 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) |
- +---------------+---------------+---------------+---------------+
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 137]
-
-RFC 3720 iSCSI April 2004
-
-
- The SCSI Data-In PDU for READ operations has the following 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|.|.| 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) |
- +---------------+---------------+---------------+---------------+
-
- Status can accompany the last Data-In PDU if the command did not end
- with an exception (i.e., the status is "good status" - GOOD,
- CONDITION MET or INTERMEDIATE CONDITION MET). The presence of status
- (and of a residual count) is signaled though the S flag bit.
- Although targets MAY choose to send even non-exception status in
- separate responses, initiators MUST support non-exception status in
- Data-In PDUs.
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 138]
-
-RFC 3720 iSCSI April 2004
-
-
-10.7.1. F (Final) Bit
-
- For outgoing data, this bit is 1 for the last PDU of unsolicited data
- or the last PDU of a sequence that answers an R2T.
-
- For incoming data, this bit is 1 for the last input (read) data PDU
- of a sequence. Input can be split into several sequences, each
- having its own F bit. Splitting the data stream into sequences does
- not affect DataSN counting on Data-In PDUs. It MAY be used as a
- "change direction" indication for Bidirectional operations that need
- such a change.
-
- DataSegmentLength MUST not exceed MaxRecvDataSegmentLength for the
- direction it is sent and the total of all the DataSegmentLength of
- all PDUs in a sequence MUST not exceed MaxBurstLength (or
- FirstBurstLength for unsolicited data). However the number of
- individual PDUs in a sequence (or in total) may be higher than the
- MaxBurstLength (or FirstBurstLength) to MaxRecvDataSegmentLength
- ratio (as PDUs may be limited in length by the sender capabilities).
- Using DataSegmentLength of 0 may increase beyond what is reasonable
- for the number of PDUs and should therefore be avoided.
-
- For Bidirectional operations, the F bit is 1 for both the end of the
- input sequences and the end of the output sequences.
-
-10.7.2. A (Acknowledge) Bit
-
- For sessions with ErrorRecoveryLevel 1 or higher, the target sets
- this bit to 1 to indicate that it requests a positive acknowledgement
- from the initiator for the data received. The target should use the
- A bit moderately; it MAY only set the A bit to 1 once every
- MaxBurstLength bytes, or on the last Data-In PDU that concludes the
- entire requested read data transfer for the task from the target's
- perspective, and it MUST NOT do so more frequently. The target MUST
- NOT set to 1 the A bit for sessions with ErrorRecoveryLevel=0. The
- initiator MUST ignore the A bit set to 1 for sessions with
- ErrorRecoveryLevel=0.
-
- On receiving a Data-In PDU with the A bit set to 1 on a session with
- ErrorRecoveryLevel greater than 0, if there are no holes in the read
- data until that Data-In PDU, the initiator MUST issue a SNACK of type
- DataACK except when it is able to acknowledge the status for the task
- immediately via ExpStatSN on other outbound PDUs if the status for
- the task is also received. In the latter case (acknowledgement
- through ExpStatSN), sending a SNACK of type DataACK in response to
- the A bit is OPTIONAL, but if it is done, it must not be sent after
- the status acknowledgement through ExpStatSN. If the initiator has
- detected holes in the read data prior to that Data-In PDU, it MUST
-
-
-
-Satran, et al. Standards Track [Page 139]
-
-RFC 3720 iSCSI April 2004
-
-
- postpone issuing the SNACK of type DataACK until the holes are
- filled. An initiator also MUST NOT acknowledge the status for the
- task before those holes are filled. A status acknowledgement for a
- task that generated the Data-In PDUs is considered by the target as
- an implicit acknowledgement of the Data-In PDUs if such an
- acknowledgement was requested by the target.
-
-10.7.3. Flags (byte 1)
-
- The last SCSI Data packet sent from a target to an initiator for a
- SCSI command that completed successfully (with a status of GOOD,
- CONDITION MET, INTERMEDIATE or INTERMEDIATE CONDITION MET) may also
- optionally contain the Status for the data transfer. As Sense Data
- cannot be sent together with the Command Status, if the command is
- completed with an error, then the response and sense data MUST be
- sent in a SCSI Response PDU (i.e., MUST NOT be sent in a SCSI Data
- packet). If Status is sent with the data, then a SCSI Response PDU
- MUST NOT be sent as this would violate SCSI rules (a single status).
- For Bidirectional commands, the status MUST be sent in a SCSI
- Response PDU.
-
- 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
- 10.4.1 Flags (byte 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.
-
- The fields StatSN, Status, and Residual Count only have meaningful
- content if the S bit is set to 1 and their values are defined in
- Section 10.4 SCSI Response.
-
-10.7.4. Target Transfer Tag and LUN
-
- On outgoing data, the Target Transfer Tag is provided to the target
- if the transfer is honoring an R2T. In this case, the Target
- Transfer Tag field is a replica of the Target Transfer Tag provided
- with the R2T.
-
- On incoming data, the Target Transfer Tag and LUN MUST be provided by
- the target if the A bit is set to 1; otherwise they are reserved.
- The Target Transfer Tag and LUN are copied by the initiator into the
- SNACK of type DataACK that it issues as a result of receiving a SCSI
- Data-In PDU with the A bit set to 1.
-
-
-
-
-Satran, et al. Standards Track [Page 140]
-
-RFC 3720 iSCSI April 2004
-
-
- The Target Transfer Tag values are not specified by this protocol
- except that the value 0xffffffff is reserved and means that the
- Target Transfer Tag is not supplied. If the Target Transfer Tag is
- provided, then the LUN field MUST hold a valid value and be
- consistent with whatever was specified with the command; otherwise,
- the LUN field is reserved.
-
-10.7.5. DataSN
-
- For input (read) or bidirectional Data-In PDUs, the DataSN is the
- input PDU number within the data transfer for the command identified
- by the Initiator Task Tag.
-
- R2T and Data-In PDUs, in the context of bidirectional commands, share
- the numbering sequence (see Section 3.2.2.3 Data Sequencing).
-
- For output (write) data PDUs, the DataSN is the Data-Out PDU number
- within the current output sequence. The current output sequence is
- either identified by the Initiator Task Tag (for unsolicited data) or
- is a data sequence generated for one R2T (for data solicited through
- R2T).
-
-10.7.6. Buffer Offset
-
- The Buffer Offset field contains the offset of this PDU payload data
- within the complete data transfer. The sum of the buffer offset and
- length should not exceed the expected transfer length for the
- command.
-
- The order of data PDUs within a sequence is determined by
- DataPDUInOrder. When set to Yes, it means that PDUs have to be in
- increasing Buffer Offset order and overlays are forbidden.
-
- The ordering between sequences is determined by DataSequenceInOrder.
- When set to Yes, it means that sequences have to be in increasing
- Buffer Offset order and overlays are forbidden.
-
-10.7.7. DataSegmentLength
-
- This is the data payload length of a SCSI Data-In or SCSI Data-Out
- PDU. The sending of 0 length data segments should be avoided, but
- initiators and targets MUST be able to properly receive 0 length data
- segments.
-
- The Data Segments of Data-In and Data-Out PDUs SHOULD be filled to
- the integer number of 4 byte words (real payload) unless the F bit is
- set to 1.
-
-
-
-
-Satran, et al. Standards Track [Page 141]
-
-RFC 3720 iSCSI April 2004
-
-
-10.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) |
- +---------------+---------------+---------------+---------------+
-
- When an initiator has submitted a SCSI Command with data that passes
- from the initiator to the target (WRITE), the target may specify
- which blocks of data it is ready to receive. The target may request
- that the data blocks be delivered in whichever order is convenient
- for the target at that particular instant. This information is
- passed from the target to the initiator in the Ready To Transfer
- (R2T) PDU.
-
- In order to allow write operations 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 with a
- matching Target Transfer Tag. If an R2T is answered with a single
- Data-Out PDU, the Buffer Offset in the Data PDU MUST be the same as
-
-
-
-Satran, et al. Standards Track [Page 142]
-
-RFC 3720 iSCSI April 2004
-
-
- the one specified by the R2T, and the data length of the Data PDU
- MUST be the same as the Desired Data Transfer Length specified in the
- R2T. If the R2T is answered with a sequence of Data PDUs, the Buffer
- Offset and Length MUST be within the range of those specified by R2T,
- and the last PDU MUST have the F bit set to 1. If the last PDU
- (marked with the F bit) is received before the Desired Data Transfer
- Length is transferred, a target MAY choose to Reject that
-
- PDU with "Protocol error" reason code. DataPDUInOrder governs the
- Data-Out PDU ordering. If DataPDUInOrder is 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 may send several R2T PDUs. It, therefore, can have a
- number of pending data transfers. The number of outstanding R2T PDUs
- are limited by the value of the negotiated key MaxOutstandingR2T.
- Within a connection, outstanding R2Ts MUST be fulfilled by the
- initiator in the order in which they were received.
-
- R2T PDUs MAY also be used to recover Data Out PDUs. Such an R2T
- (Recovery-R2T) is generated by a target upon detecting the loss of
- one or more Data-Out PDUs due to:
-
- - Digest error
- - Sequence error
- - Sequence reception timeout
-
- A Recovery-R2T carries the next unused R2TSN, but requests part of or
- the entire data burst that an earlier R2T (with a lower R2TSN) had
- already requested.
-
- DataSequenceInOrder governs the buffer offset ordering in consecutive
- R2Ts. If DataSequenceInOrder is Yes, then consecutive R2Ts MUST
- refer to continuous non-overlapping ranges except for Recovery-R2Ts.
-
-10.8.1. TotalAHSLength and DataSegmentLength
-
- For this PDU TotalAHSLength and DataSegmentLength MUST be 0.
-
-10.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 3.2.2.3 Data Sequencing).
-
-
-
-
-Satran, et al. Standards Track [Page 143]
-
-RFC 3720 iSCSI April 2004
-
-
-10.8.3. StatSN
-
- The StatSN field will contain the next StatSN. The StatSN for this
- connection is not advanced after this PDU is sent.
-
-10.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 from the
- initiator in several chunks, not necessarily in the original order of
- the data. The target, therefore, also specifies a Buffer Offset that
- indicates the point at which the data transfer should begin, relative
- to the beginning of the total data transfer. The Desired Data
- Transfer Length MUST NOT be 0 and MUST not exceed MaxBurstLength.
-
-10.8.5. Target Transfer Tag
-
- The target assigns its own tag to each R2T request that it sends to
- the initiator. This tag can be used by the target to easily identify
- the data it receives. The Target Transfer Tag and LUN are copied in
- the outgoing data PDUs and are only used by the target. There is 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.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 144]
-
-RFC 3720 iSCSI April 2004
-
-
-10.9. Asynchronous Message
-
- An Asynchronous Message may be sent from the target to the initiator
- without correspondence to a particular command. The target specifies
- the reason for the event and 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].
-
- StatSN counts this PDU as an acknowledgeable event (StatSN is
- advanced), which allows for initiator and target state
- synchronization.
-
-
-
-Satran, et al. Standards Track [Page 145]
-
-RFC 3720 iSCSI April 2004
-
-
-10.9.1. AsyncEvent
-
- The codes used for iSCSI Asynchronous Messages (events) are:
-
- 0 - a SCSI Asynchronous Event is reported in the sense data.
- Sense Data that accompanies the report, in the data segment,
- identifies the condition. The sending of a SCSI Event
- (Asynchronous Event Reporting in SCSI terminology) is
- dependent on the target support for SCSI asynchronous event
- reporting (see [SAM2]) as indicated in the standard INQUIRY
- data (see [SPC3]). Its use may be enabled by parameters in
- the SCSI Control mode page (see [SPC3]).
-
- 1 - 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 Parameter3 seconds.
- 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 Logout in Parameter3
- seconds, the target should send an Async PDU with iSCSI event
- code "Dropped the connection" if possible, or simply terminate
- the transport connection. Parameter1 and Parameter2 are
- reserved.
-
- 2 - target indicates it will drop the connection. The Parameter1
- field indicates the CID of the connection that is going to be
- dropped.
-
- The Parameter2 field (Time2Wait) indicates, in seconds, the
- minimum time to wait before attempting to reconnect or
- reassign.
-
- The Parameter3 field (Time2Retain) indicates the maximum time
- allowed to reassign commands after the initial wait (in
- Parameter2).
-
- If the initiator does not attempt to reconnect and/or reassign
- the outstanding commands within the time specified by
- Parameter3, or if Parameter3 is 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.
-
-
-
-
-Satran, et al. Standards Track [Page 146]
-
-RFC 3720 iSCSI April 2004
-
-
- A value of 0 for Parameter2 indicates that reconnect can be
- attempted immediately.
-
- 3 - target indicates it will drop all the connections of this
- session.
-
- Parameter1 field is reserved.
-
- The Parameter2 field (Time2Wait) indicates, in seconds, the
- minimum time to wait before attempting to reconnect. The
- Parameter3 field (Time2Retain) indicates the maximum time
- allowed to reassign commands after the initial wait (in
- Parameter2).
-
- If the initiator does not attempt to reconnect and/or reassign
- the outstanding commands within the time specified by
- Parameter3, or if Parameter3 is 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 Parameter2 indicates that reconnect
- can be attempted immediately.
-
- 4 - 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 Parameter3 seconds, 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.
-
- 255 - vendor specific iSCSI Event. The AsyncVCode details the
- vendor code, and data MAY accompany the report.
-
- All other event codes are reserved.
-
-10.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.
-
-10.9.3. LUN
-
- The LUN field MUST be valid if AsyncEvent is 0. Otherwise, this
- field is reserved.
-
-
-
-Satran, et al. Standards Track [Page 147]
-
-RFC 3720 iSCSI April 2004
-
-
-10.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|
-
-10.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.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 148]
-
-RFC 3720 iSCSI April 2004
-
-
-10.10. Text Request
-
- The Text Request is provided to allow for the exchange of information
- and for future extensions. It permits the initiator to inform a
- target of its capabilities or to 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 have at most 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 must cause such a task
- to be implicitly terminated by the target.
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 149]
-
-RFC 3720 iSCSI April 2004
-
-
-10.10.1. F (Final) Bit
-
- When set to 1, 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.
-
-10.10.2. C (Continue) Bit
-
- When set to 1, 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.
-
-10.10.3. Initiator Task Tag
-
- 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.
-
-10.10.4. Target Transfer Tag
-
- When the Target Transfer Tag is set to the reserved value 0xffffffff,
- it tells the target that this is a new request and the target resets
- any internal state associated with the Initiator Task Tag (resets the
- current negotiation state).
-
- The target sets the Target Transfer Tag in a text response to a value
- other than the reserved value 0xffffffff whenever it indicates that
- it has more data to send or more operations to perform that are
- associated with the specified Initiator Task Tag. It MUST do so
- whenever it sets the F bit to 0 in the response. By copying the
- Target Transfer Tag from the response to the next Text Request, the
- initiator tells the target to continue the operation for the specific
- Initiator Task Tag. The initiator MUST ignore the Target Transfer
- Tag in the Text Response when the F bit is set to 1.
-
- This mechanism allows the initiator and target to transfer a large
- amount of textual data over a sequence of text-command/text-response
- exchanges, or to perform extended negotiation sequences.
-
- If the Target Transfer Tag is not 0xffffffff, the LUN field MUST be
- sent by the target in the Text Response.
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 150]
-
-RFC 3720 iSCSI April 2004
-
-
- A target MAY reset its internal negotiation state if an exchange is
- stalled by the initiator for a long time or if it is running out of
- resources.
-
- Long text responses are handled as in the following example:
-
- 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)
-
-10.10.5. Text
-
- The data lengths of a text request MUST NOT exceed the iSCSI target
- MaxRecvDataSegmentLength (a per connection and per direction
- negotiated parameter). The text format is specified in Section 5.2
- Text Mode Negotiation.
-
- Chapter 11 and Chapter 12 list some basic Text key=value pairs, some
- of which can be used in Login Request/Response and some in Text
- Request/Response.
-
- A key=value pair can span Text request or response boundaries. A
- key=value pair can start in one PDU and continue on the next. In
- other words the end of a PDU does not necessarily signal the end of a
- key=value pair.
-
- The target responds by sending its response back to the initiator.
- The response text format is similar to the request text format. The
- text response MAY refer to key=value pairs presented in an earlier
- text request and the text in the request may refer to earlier
- responses.
-
- Chapter 5 details the rules for the Text Requests and Responses.
-
- Text operations are usually meant for parameter setting/
- negotiations, but can also be used to perform some long lasting
- operations.
-
- Text operations that take a long time should be placed in their own
- Text request.
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 151]
-
-RFC 3720 iSCSI April 2004
-
-
-10.11. Text Response
-
- The Text Response PDU contains the target's responses to the
- initiator's Text request. The format of the Text field matches that
- of the Text 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|.|.| 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) |
- +---------------+---------------+---------------+---------------+
-
-10.11.1. F (Final) Bit
-
- When set to 1, in response to a Text Request with the Final bit set
- to 1, the F bit indicates that the target has finished the whole
- operation. Otherwise, if set to 0 in response to a Text Request with
- the Final Bit set to 1, it indicates that the target has more work to
- do (invites 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.
-
-
-
-Satran, et al. Standards Track [Page 152]
-
-RFC 3720 iSCSI April 2004
-
-
- 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 of 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 0xffffffff.
-
-10.11.2. C (Continue) Bit
-
- When set to 1, indicates that the text (set of key=value pairs) in
- this Text Response is not complete (it will be continued on
- subsequent Text Responses); otherwise, it indicates that 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.
-
-10.11.3. Initiator Task Tag
-
- The Initiator Task Tag matches the tag used in the initial Text
- Request.
-
-10.11.4. Target Transfer Tag
-
- When a target has more work to do (e.g., cannot transfer all the
- remaining text data in a single Text Response or has to continue the
- negotiation) and has enough resources to proceed, it MUST set the
- Target Transfer Tag to a value other than the reserved value of
- 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 indicate that it wants the rest of the data.
-
- When the target receives a Text Request with the Target Transfer Tag
- set to the reserved value of 0xffffffff, it resets its internal
- information (resets state) associated with the given Initiator Task
- Tag (restarts the negotiation).
-
- When a target cannot finish the operation in a single Text Response,
- and does not have enough resources to continue, it rejects the Text
- Request with the appropriate Reject code.
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 153]
-
-RFC 3720 iSCSI April 2004
-
-
- A target may reset its internal state associated with an Initiator
- Task Tag (the current negotiation state), state expressed through the
- Target Transfer Tag if the initiator fails to continue the exchange
- for some time. The target may reject subsequent Text Requests with
- the Target Transfer Tag set to the "stale" value.
-
-10.11.5. StatSN
-
- The target StatSN variable is advanced by each Text Response sent.
-
-10.11.6. Text Response Data
-
- The data lengths of a text response MUST NOT exceed the iSCSI
- initiator MaxRecvDataSegmentLength (a per connection and per
- direction negotiated parameter).
-
- The text in the Text Response Data is governed by the same rules as
- the text in the Text Request Data (see Section 10.10.5 Text).
-
- Although the initiator is the requesting party and controls the
- request-response initiation and termination, the target can offer
- key=value pairs of its own as part of a sequence and not only in
- response to the initiator.
-
-10.12. Login Request
-
- After establishing a TCP connection between an initiator and a
- target, the initiator MUST start a Login Phase to gain further access
- to the target's resources.
-
- The Login Phase (see Chapter 5) consists of a sequence of Login
- Requests and Responses that carry the same Initiator Task Tag.
-
- Login Requests are always considered as immediate.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 154]
-
-RFC 3720 iSCSI April 2004
-
-
- 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 /
- +/ /
- +---------------+---------------+---------------+---------------+
-
-10.12.1. T (Transit) Bit
-
- If set to 1, indicates that the initiator is ready to transit to the
- next stage.
-
- If the T bit is set to 1 and NSG is FullFeaturePhase, then this also
- indicates that the initiator is ready for the Final Login Response
- (see Chapter 5).
-
-10.12.2. C (Continue) Bit
-
- When set to 1, indicates that the text (set of key=value pairs) in
- this Login Request is not complete (it will be continued on
- subsequent Login Requests); otherwise, it indicates that this Login
- Request ends a set of key=value pairs. A Login Request with the C
- bit set to 1 MUST have the T bit set to 0.
-
-
-
-
-Satran, et al. Standards Track [Page 155]
-
-RFC 3720 iSCSI April 2004
-
-
-10.12.3. CSG and NSG
-
- Through these fields, Current Stage (CSG) and Next Stage (NSG), the
- Login negotiation requests and responses are associated with a
- specific stage in the session (SecurityNegotiation,
- LoginOperationalNegotiation, FullFeaturePhase) and may indicate the
- next stage to which they want to move (see Chapter 5). The next
- stage value is only valid when the T bit is 1; otherwise, it is
- reserved.
-
- The stage codes are:
-
- - 0 - SecurityNegotiation
- - 1 - LoginOperationalNegotiation
- - 3 - FullFeaturePhase
-
- All other codes are reserved.
-
-10.12.4. Version
-
- The version number of the current draft is 0x00. As such, all
- devices MUST carry version 0x00 for both Version-min and Version-max.
-
-10.12.4.1. Version-max
-
- 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.
-
-10.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.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 156]
-
-RFC 3720 iSCSI April 2004
-
-
-10.12.5. ISID
-
- This is an initiator-defined component of the session identifier and
- is structured as follows (see [RFC3721] and Section 9.1.1
- Conservative Reuse of ISIDs 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 identifies the format and usage of A, B, C, and D as
- indicated below:
-
- T
-
- 00b OUI-Format
- A&B are a 22 bit OUI
- (the I/G & U/L bits are omitted)
- C&D 24 bit qualifier
- 01b EN - Format (IANA Enterprise Number)
- A - Reserved
- B&C EN (IANA Enterprise Number)
- D - Qualifier
- 10b "Random"
- A - Reserved
- B&C Random
- D - Qualifier
- 11b A,B,C&D Reserved
-
- For the T field values 00b and 01b, a combination of A and B (for
- 00b) or B and C (for 01b) identifies the vendor or organization whose
- component (software or hardware) generates 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 select the
- appropriate value for the T field when its components generate ISIDs.
- An OUI or EN MUST be set in the corresponding fields in network byte
- order (byte big-endian).
-
- If the T field is 10b, B and C are set to a random 24-bit unsigned
- integer value in network byte order (byte big-endian). See [RFC3721]
- for how this affects the principle of "conservative reuse".
-
-
-
-
-
-Satran, et al. Standards Track [Page 157]
-
-RFC 3720 iSCSI April 2004
-
-
- The Qualifier field is a 16 or 24-bit unsigned integer value that
- provides a range of possible values for the ISID within the selected
- namespace. It may be set to any value within the constraints
- specified in the iSCSI protocol (see Section 3.4.3 Consequences of
- the Model and Section 9.1.1 Conservative Reuse of ISIDs).
-
- The T field value of 11b is reserved.
-
- If the ISID is derived from something assigned to a hardware adapter
- or interface by a vendor, as a preset default value, it MUST be
- configurable to a value assigned according to the SCSI port behavior
- desired by the system in which it is installed (see Section 9.1.1
- Conservative Reuse of ISIDs and Section 9.1.2 iSCSI Name, ISID, and
- TPGT Use). The resultant ISID MUST also be persistent over power
- cycles, reboot, card swap, etc.
-
-10.12.6. TSIH
-
- 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 sent by the target at the conclusion of the successful login
- of the first connection for this session MUST be used. The TSIH
- identifies to the target the associated existing session for this new
- connection.
-
- 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 5.3.1 Login Phase Start.
-
-10.12.7. Connection ID - CID
-
- A unique ID for this connection within 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 equal to that of an
- existing connection implies a logout of the connection followed by a
- Login (see Section 5.3.4 Connection Reinstatement). For the details
- of the implicit Logout Request, see Section 10.14 Logout Request.
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 158]
-
-RFC 3720 iSCSI April 2004
-
-
-10.12.8. CmdSN
-
- CmdSN is either the initial 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:
-
- - Login on a leading connection - if the leading login carries
- the CmdSN 123, all other Login Requests in the same Login Phase
- carry the CmdSN 123 and the first non-immediate command in
- FullFeaturePhase also carries the CmdSN 123.
-
- - Login on other than a leading connection - if the current CmdSN
- at the time the first login on the connection is issued is 500,
- then that PDU carries CmdSN=500. Subsequent Login Requests
- that are needed to complete this Login Phase may carry a CmdSN
- higher than 500 if non-immediate requests that were issued on
- other connections in the same session advance CmdSN.
-
- If the Login Request is a leading Login Request, the target MUST use
- the value presented in CmdSN as the target value for ExpCmdSN.
-
-10.12.9. ExpStatSN
-
- For the first Login Request on a connection this is ExpStatSN for the
- old connection and this field is only valid if the Login Request
- restarts a connection (see Section 5.3.4 Connection Reinstatement).
-
- For subsequent Login Requests it is used to acknowledge the Login
- Responses with their increasing StatSN values.
-
-10.12.10. Login Parameters
-
- The initiator MUST provide some basic parameters in order to enable
- the target to determine if the initiator may use the target's
- resources and the initial text parameters for the security exchange.
-
- All the rules specified in Section 10.10.5 Text for text requests
- also hold for Login Requests. Keys and their explanations are listed
- in Chapter 11 (security negotiation keys) and Chapter 12 (operational
- parameter negotiation keys). All keys in Chapter 12, except for the
- X extension formats, MUST be supported by iSCSI initiators and
- targets. Keys in Chapter 11 only need to be supported when the
- function to which they refer is mandatory to implement.
-
-
-
-
-
-Satran, et al. Standards Track [Page 159]
-
-RFC 3720 iSCSI April 2004
-
-
-10.13. Login Response
-
- The Login Response indicates the progress and/or end of the Login
- Phase.
-
- 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 /
- +/ /
- +---------------+---------------+---------------+---------------+
-
-10.13.1. Version-max
-
- This is the highest version number supported by the target.
-
- 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.
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 160]
-
-RFC 3720 iSCSI April 2004
-
-
-10.13.2. Version-active
-
- Indicates the highest version supported by the target and initiator.
- If the target does not support a version within the range specified
- by the initiator, the target rejects the login and this field
- indicates the lowest version supported by the target.
-
- 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.
-
-10.13.3. TSIH
-
- The TSIH is the target assigned session identifying handle. Its
- internal format and content are not defined by this protocol except
- for the value 0 that is reserved. With the exception of the Login
- Final-Response in a new session, this field should be set to the TSIH
- provided by the initiator 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 5.3 Login Phase).
-
-10.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, if any, in the same Login Phase, will carry this number +
- 1. This field is only valid if the Status-Class is 0.
-
-10.13.5. Status-Class and Status-Detail
-
- The Status returned in a Login Response indicates the execution
- status of the Login Phase. The status includes:
-
- Status-Class
- Status-Detail
-
- 0 Status-Class indicates success.
-
- A non-zero Status-Class indicates an exception. In this case,
- Status-Class is sufficient for a simple initiator to use when
- handling exceptions, without having to look at the Status-Detail.
- The Status-Detail allows finer-grained exception handling for more
- sophisticated initiators and for better information for logging.
-
-
-
-
-
-Satran, et al. Standards Track [Page 161]
-
-RFC 3720 iSCSI April 2004
-
-
- The status classes are as follows:
-
- 0 - Success - indicates that the iSCSI target successfully
- received, understood, and accepted the request. The numbering
- fields (StatSN, ExpCmdSN, MaxCmdSN) are only valid if
- Status-Class is 0.
-
- 1 - Redirection - indicates that the initiator must take further
- action to complete the request. This is usually due to the
- target moving to a different address. All of the redirection
- status class responses MUST return one or more text key
- parameters of the type "TargetAddress", which indicates the
- target's new address. A redirection response MAY be issued by
- a target prior or after completing a security negotiation if a
- security negotiation is required. A redirection SHOULD be
- accepted by an initiator even without having the target
- complete a security negotiation if any security negotiation is
- required, and MUST be accepted by the initiator after the
- completion of the security negotiation if any security
- negotiation is required.
-
- 2 - Initiator Error (not a format error) - indicates that the
- initiator most likely caused the error. This MAY be due to a
- request for a resource for which the initiator does not have
- permission. The request should not be tried again.
-
- 3 - Target Error - indicates that the target sees no errors in the
- initiator's Login Request, but is currently incapable of
- fulfilling the request. The initiator may re-try 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.
- -----------------------------------------------------------------
-
-
-
-Satran, et al. Standards Track [Page 162]
-
-RFC 3720 iSCSI April 2004
-
-
- 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 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 | | of 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.
- -----------------------------------------------------------------
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 163]
-
-RFC 3720 iSCSI April 2004
-
-
- (*1) If the response T bit is 1 in both the request and the matching
- response, and the NSG is 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.
-
-10.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 NSG is FullFeaturePhase, then this is also
- the Final Login Response (see Chapter 5). A T bit of 0 indicates a
- "partial" response, which means "more negotiation needed".
-
- A Login Response with a 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.
-
-10.13.7. C (Continue) Bit
-
- When set to 1, 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.
-
-10.13.8. Login Parameters
-
- The target MUST provide some basic parameters in order to enable the
- initiator to determine if it is connected to the correct port and the
- initial text parameters for the security exchange.
-
- All the rules specified in Section 10.11.6 Text Response Data for
- text responses also hold for Login Responses. Keys and their
- explanations are listed in Chapter 11 (security negotiation keys) and
- Chapter 12 (operational parameter negotiation keys). All keys in
- Chapter 12, except for the X extension formats, MUST be supported by
- iSCSI initiators and targets. Keys in Chapter 11, only need to be
- supported when the function to which they refer is mandatory to
- implement.
-
-
-
-
-Satran, et al. Standards Track [Page 164]
-
-RFC 3720 iSCSI April 2004
-
-
-10.14. Logout Request
-
- The Logout Request is used to perform a controlled closing of a
- connection.
-
- 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. If the Logout Request
- is intended to close the session, new iSCSI requests MUST NOT be sent
- on any of the connections participating in the session.
-
- When receiving a Logout Request with the reason code of "close the
- connection" or "close the session", the target MUST terminate all
- pending commands, whether acknowledged via ExpCmdSN or not, on that
- connection or session respectively.
-
- When receiving a Logout Request with the reason code "remove
- connection for recovery", the target MUST discard all requests not
- yet acknowledged via ExpCmdSN that were issued on the specified
- connection, and suspend all data/status/R2T transfers on behalf of
- pending commands on the specified connection.
-
- The target then issues the Logout Response and half-closes the TCP
- connection (sends FIN). After receiving the Logout Response and
- attempting to receive the FIN (if still possible), the initiator MUST
- completely close the logging-out connection. For the terminated
- commands, no additional responses should be expected.
-
- A Logout for a CID may be performed on a different transport
- connection when the TCP connection for the CID has already been
- terminated. In such a case, only a logical "closing" of the iSCSI
- connection for the CID is implied with a Logout.
-
- All commands that were not terminated or not completed (with status)
- and acknowledged when the connection is closed completely can be
- reassigned to a new connection if the target supports connection
- recovery.
-
- If an initiator intends to start recovery for a failing connection,
- it MUST use the Logout Request to "clean-up" the target end of a
- failing connection and enable recovery to start, or the Login Request
- with a non-zero TSIH and the same CID on a new connection for the
- same effect (see Section 10.14.3 CID). In sessions with a single
- connection, the connection can be closed and then a new connection
- reopened. A connection reinstatement login can be used for recovery
- (see Section 5.3.4 Connection Reinstatement).
-
-
-
-Satran, et al. Standards Track [Page 165]
-
-RFC 3720 iSCSI April 2004
-
-
- A successful completion of a Logout Request with the reason code of
- "close the connection" or "remove the connection for recovery"
- results at the target in the discarding of unacknowledged commands
- received on the connection being logged out. These are commands that
- have arrived on the connection being logged out, but have not been
- delivered to SCSI because one or more commands with a smaller CmdSN
- has not been received by iSCSI. See Section 3.2.2.1 Command
- Numbering and Acknowledging. The resulting holes the in command
- sequence numbers will have to be handled by appropriate recovery (see
- Chapter 6) unless the session is also closed.
-
- The entire logout discussion in this section is also applicable for
- an implicit Logout realized via a connection reinstatement or session
- reinstatement. When a Login Request performs an implicit Logout, the
- implicit Logout is performed as if having the reason codes specified
- 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 = 2
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 166]
-
-RFC 3720 iSCSI April 2004
-
-
- 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) |
- +---------------+---------------+---------------+---------------+
-
-10.14.1. Reason Code
-
- Reason Code indicates the reason for Logout as follows:
-
- 0 - close the session. All commands associated with the session
- (if any) are terminated.
-
- 1 - close the connection. All commands associated with connection
- (if any) are terminated.
-
- 2 - remove the connection for recovery. Connection is closed and
- all commands associated with it, if any, are to be prepared
- for a new allegiance.
-
- All other values are reserved.
-
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 167]
-
-RFC 3720 iSCSI April 2004
-
-
-10.14.2. TotalAHSLength and DataSegmentLength
-
- For this PDU TotalAHSLength and DataSegmentLength MUST be 0.
-
-10.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".
-
-10.14.4. ExpStatSN
-
- This is the last ExpStatSN value for the connection to be closed.
-
-10.14.5. Implicit termination of tasks
-
- A target implicitly terminates the active tasks due to the iSCSI
- protocol in the following cases:
-
- a) When a connection is implicitly or explicitly logged out with
- the reason code of "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 7.2.2 State
- Transition Descriptions for Initiators and Targets) 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 of "Close the session" and there are active
- tasks in that session.
-
- If the tasks terminated in any of the above cases are SCSI tasks,
- they must be internally terminated as if with CHECK CONDITION status.
- This status is only meaningful for appropriately handling the
- internal SCSI state and SCSI side effects with respect to ordering
- because this status is never communicated back as a terminating
- status to the initiator. However additional actions may have to be
- taken at SCSI level depending on the SCSI context as defined by the
- SCSI standards (e.g., queued commands and ACA, in cases a), b), and
- c), 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, and
-
-
-
-Satran, et al. Standards Track [Page 168]
-
-RFC 3720 iSCSI April 2004
-
-
- the ASC/ASCQ value of 47h/7Fh - "SOME COMMANDS CLEARED BY ISCSI
- PROTOCOL EVENT" - etc. - see [SAM2] and [SPC3]).
-
-10.15. Logout Response
-
- The Logout Response is used by the target to indicate if the cleanup
- operation for the connection(s) has completed.
-
- After Logout, the TCP connection referred 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) |
- +---------------+---------------+---------------+---------------+
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 169]
-
-RFC 3720 iSCSI April 2004
-
-
-10.15.1. Response
-
- Logout Response:
-
- 0 - connection or session closed successfully.
-
- 1 - CID not found.
-
- 2 - connection recovery is not supported. If Logout reason code
- was recovery and target does not support it as indicated by the
- ErrorRecoveryLevel.
-
- 3 - cleanup failed for various reasons.
-
-10.15.2. TotalAHSLength and DataSegmentLength
-
- For this PDU TotalAHSLength and DataSegmentLength MUST be 0.
-
-10.15.3. Time2Wait
-
- If the Logout Response code is 0 and if 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 if 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.
-
-10.15.4. Time2Retain
-
- If the Logout response code is 0 and if the operational
- ErrorRecoveryLevel is 2, this is the maximum amount of time, in
- seconds, after the initial wait (Time2Wait), the target waits for the
- allegiance reassignment for any active task after which the task
- state is discarded. If the Logout response code is 0 and if the
- operational ErrorRecoveryLevel is less than 2, this field is to be
- ignored.
-
- This field is invalid if the Logout response code is 1.
-
-
-
-
-
-Satran, et al. Standards Track [Page 170]
-
-RFC 3720 iSCSI April 2004
-
-
- If the Logout response code is 2 or 3, this field specifies the
- maximum amount of time, in seconds, after the initial wait
- (Time2Wait), the target waits for a new implicit or explicit logout.
-
- If it is the last connection of a session, the whole session state is
- discarded after Time2Retain.
-
- If Time2Retain is 0, the target has already discarded the connection
- (and possibly the session) state along with the task states. No
- reassignment or Logout is required in this case.
-
-10.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.
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 171]
-
-RFC 3720 iSCSI April 2004
-
-
- The SNACK is used by the initiator to request the retransmission of
- numbered-responses, data, or R2T PDUs from the target. The SNACK
- request indicates the numbered-responses or data "runs" whose
- retransmission is requested by the target, where the run starts with
- the first StatSN, DataSN, or R2TSN whose retransmission is requested
- and indicates the number of Status, Data, or R2T PDUs requested
- including the first. 0 has special meaning when used as a starting
- number and 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 that the target transmitted
- 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 StatSN.
-
- The numbered Data-In PDUs, requested by a Data SNACK MUST be
- delivered as exact replicas of the ones that the target transmitted
- originally except for the fields ExpCmdSN and MaxCmdSN, which MUST
- carry the current values and except for resegmentation (see Section
- 10.16.3 Resegmentation).
-
- Any SNACK that requests a numbered-response, Data, or R2T that was
- not sent by the target or was already acknowledged by the initiator,
- MUST be rejected with a reason code of "Protocol error".
-
-10.16.1. Type
-
- This field encodes the SNACK function as follows:
-
- 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.
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 172]
-
-RFC 3720 iSCSI April 2004
-
-
- All other values are reserved.
-
- Data/R2T SNACK, Status SNACK, or R-Data SNACK for a command MUST
- precede status acknowledgement for the given command.
-
-10.16.2. Data Acknowledgement
-
- 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. However, 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.
-
- An initiator MUST NOT request retransmission for any data it had
- already acknowledged.
-
-10.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
- 10.16.1 Type). With R-Data SNACK, the initiator indicates that 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 in order
- to 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 is increased 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 containing another value
- in the SNACK Tag field or 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 due to this rule, all SCSI responses must
- carry the same StatSN (see Section 10.4.4 SNACK Tag). If an
- initiator attempts to recover a lost SCSI Response (with a
- Status SNACK, see Section 10.16.1 Type) 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.
-
-
-
-Satran, et al. Standards Track [Page 173]
-
-RFC 3720 iSCSI April 2004
-
-
- For considerations in allegiance reassignment of a task to a
- connection with a different MaxRecvDataSegmentLength, refer to
- Section 6.2.2 Allegiance Reassignment.
-
-10.16.4. Initiator Task Tag
-
- For 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.
-
-10.16.5. Target Transfer Tag or SNACK Tag
-
- For an 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 of 0xffffffff.
-
-10.16.6. BegRun
-
- 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).
-
- BegRun 0 when used in conjunction with RunLength 0 means resend all
- unacknowledged Data-In, R2T or Response PDUs.
-
- BegRun MUST be 0 for a R-Data SNACK.
-
-10.16.7. RunLength
-
- The number of PDUs whose retransmission is requested.
-
- RunLength 0 signals that all Data-In, R2T, or Response PDUs carrying
- the numbers equal to or greater than BegRun have to be resent.
-
- The RunLength MUST also be 0 for a DataACK SNACK in addition to
- R-Data SNACK.
-
-
-
-
-
-Satran, et al. Standards Track [Page 174]
-
-RFC 3720 iSCSI April 2004
-
-
-10.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) |
- +---------------+---------------+---------------+---------------+
-
- Reject is used to indicate an iSCSI error condition (protocol,
- unsupported option, etc.).
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 175]
-
-RFC 3720 iSCSI April 2004
-
-
-10.17.1. Reason
-
- The reject Reason is coded as follows:
-
- +------+----------------------------------------+------------------+
- | Code | Explanation | Can the original |
- | (hex)| | PDU be re-sent? |
- +------+----------------------------------------+------------------+
- | 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 Operation Reject - Can't generate | yes |
- | | Target Transfer Tag - out of resources | |
- | | | |
- | 0x0b | Negotiation Reset | no |
- | | | |
- | 0x0c | Waiting for Logout | no |
- +------+----------------------------------------+------------------+
-
- Note 1: For iSCSI, Data-Out PDU retransmission is only done if the
- target requests retransmission with a recovery R2T. However, if this
- is the data digest error on immediate data, the initiator may choose
- to retransmit the whole PDU including the immediate data.
-
- 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.
-
- All other values for Reason are reserved.
-
-
-
-
-Satran, et al. Standards Track [Page 176]
-
-RFC 3720 iSCSI April 2004
-
-
- In all the cases in which 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 10.4.3
- Response. In these cases in which 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 Reject PDU, see Section 6.3 Usage
- Of Reject PDU in Recovery.
-
-10.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 10.16 SNACK
- Request). The DataSN/R2TSN is the next Data/R2T sequence number that
- the target would send for the task, if any.
-
-10.17.3. StatSN, ExpCmdSN and MaxCmdSN
-
- These fields carry their usual values and are not related to the
- rejected command. StatSN is advanced after a Reject.
-
-10.17.4. Complete Header of Bad PDU
-
- The target returns the header (not including digest) of the PDU in
- error as the data of the response.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 177]
-
-RFC 3720 iSCSI April 2004
-
-
-10.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) |
- +---------------+---------------+---------------+---------------+
-
- A 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 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.
-
-
-
-
-
-Satran, et al. Standards Track [Page 178]
-
-RFC 3720 iSCSI April 2004
-
-
-10.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 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 10.19 NOP-In).
-
- 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.
-
-10.18.2. Target Transfer Tag
-
- 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.
-
-10.18.3. Ping Data
-
- Ping data are reflected in the NOP-In Response. The length of the
- reflected data are limited to MaxRecvDataSegmentLength. The length
- of ping data are indicated by the DataSegmentLength. 0 is a valid
- value for the DataSegmentLength and indicates the absence of ping
- data.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 179]
-
-RFC 3720 iSCSI April 2004
-
-
-10.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) |
- +---------------+---------------+---------------+---------------+
-
- NOP-In is either sent by a target as a response to a NOP-Out, as a
- "ping" to an initiator, or as a means to carry a changed ExpCmdSN
- and/or MaxCmdSN if another PDU will not be available for a long time
- (as determined by the target).
-
- When a target receives the NOP-Out with a valid Initiator Task Tag
- (not the reserved value 0xffffffff), it MUST respond with a NOP-In
- with the same Initiator Task Tag that was provided in the NOP-Out
- request. It MUST also duplicate up to the first
- MaxRecvDataSegmentLength bytes of the initiator provided Ping Data.
- For such a response, the Target Transfer Tag MUST be 0xffffffff.
-
-
-
-
-
-Satran, et al. Standards Track [Page 180]
-
-RFC 3720 iSCSI April 2004
-
-
- Otherwise, when a target sends a NOP-In that is not a response to a
- Nop-Out received from the initiator, the Initiator Task Tag MUST be
- set to 0xffffffff and the Data Segment MUST NOT contain any data
- (DataSegmentLength MUST be 0).
-
-10.19.1. Target Transfer Tag
-
- If the target is responding to a NOP-Out, this is set to the reserved
- value 0xffffffff.
-
- If the target is sending a NOP-In as a Ping (intending to receive a
- corresponding NOP-Out), this field is set to a valid value (not the
- reserved 0xffffffff).
-
- If the target is initiating a NOP-In without wanting to receive a
- corresponding NOP-Out, this field MUST hold the reserved value of
- 0xffffffff.
-
-10.19.2. StatSN
-
- The StatSN field will always contain the next StatSN. However, when
- the Initiator Task Tag is set to 0xffffffff, StatSN for the
- connection is not advanced after this PDU is sent.
-
-10.19.3. LUN
-
- A LUN MUST be set to a correct value when the Target Transfer Tag is
- valid (not the reserved value 0xffffffff).
-
-11. 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 under Section 11.1 AuthMethod along with all of
- their associated keys as well as Vendor Specific
- Authentication Methods.
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 181]
-
-RFC 3720 iSCSI April 2004
-
-
- Other keys MUST NOT be used.
-
- SessionType, InitiatorName, TargetName, InitiatorAlias, TargetAlias,
- and TargetPortalGroupTag are described in Chapter 12 as they can be
- used also in the OperationalNegotiation stage.
-
- All security keys have connection-wide applicability.
-
-11.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 (appear in the
- list-of-values) are either those listed in the following table or are
- vendor-unique methods:
-
- +------------------------------------------------------------+
- | Name | Description |
- +------------------------------------------------------------+
- | KRB5 | Kerberos V5 - defined in [RFC1510] |
- +------------------------------------------------------------+
- | SPKM1 | Simple Public-Key GSS-API Mechanism |
- | | defined in [RFC2025] |
- +------------------------------------------------------------+
- | SPKM2 | Simple Public-Key GSS-API Mechanism |
- | | defined in [RFC2025] |
- +------------------------------------------------------------+
- | 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"
- specific to the authentication method selected.
-
- The authentication method proposal may be made by either the
- initiator or the target. However the initiator MUST make the first
- step specific to the selected authentication method as soon as it is
-
-
-
-Satran, et al. Standards Track [Page 182]
-
-RFC 3720 iSCSI April 2004
-
-
- selected. It follows that if the target makes the authentication
- method proposal the initiator sends the first keys(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 MUST be supported by the target and 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 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:
-
- a) Z-reversed.vendor.dns_name.do_something=
- b) Z<#><IANA-registered-string>=
-
- Authentication methods named using the Z- format are used as private
- extensions. Authentication methods named using the Z# format are
- used as public extensions that must be registered with IANA and MUST
- be described by an informational RFC.
-
- For all of the public or private extension authentication methods,
- the method specific keys MUST conform to the format specified in
- Section 5.1 Text Format for standard-label.
-
- To identify the vendor for private extension authentication methods,
- we suggest you use the reversed DNS-name as a prefix to the proper
- digest names.
-
- The part of digest-name following Z- and Z# MUST conform to the
- format for standard-label specified in Section 5.1 Text Format.
-
- 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.
-
-
-
-
-
-Satran, et al. Standards Track [Page 183]
-
-RFC 3720 iSCSI April 2004
-
-
-11.1.1. Kerberos
-
- For KRB5 (Kerberos V5) [RFC1510] and [RFC1964], the initiator MUST
- use:
-
- KRB_AP_REQ=<KRB_AP_REQ>
-
- where KRB_AP_REQ is the client message as defined in [RFC1510].
-
- The default principal name assumed by an iSCSI initiator or target
- (prior to 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
- [RFC1510].
-
- 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.
-
-11.1.2. Simple Public-Key Mechanism (SPKM)
-
- For SPKM1 and SPKM2 [RFC2025], the initiator MUST use:
-
- SPKM_REQ=<SPKM-REQ>
-
- where SPKM-REQ is the first initiator token as defined in [RFC2025].
-
- [RFC2025] defines situations where each side may send an error token
- that may cause the peer to re-generate and resend its last token.
- This scheme is followed in iSCSI, and the error token syntax is:
-
- SPKM_ERROR=<SPKM-ERROR>
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 184]
-
-RFC 3720 iSCSI April 2004
-
-
- However, SPKM-DEL tokens that are defined by [RFC2025] for fatal
- errors will not be used by iSCSI. If the target needs to send a
- SPKM-DEL token, it will, instead, send a Login "login reject" message
- with the "Authentication Failure" status and terminate the
- connection. If the initiator needs to send a SPKM-DEL token, it will
- close the connection.
-
- In the following sections, we assume that no SPKM-ERROR tokens are
- required.
-
- If the initiator authentication fails, the target MUST return an
- error. Otherwise, if the AuthMethod is SPKM1 or if the initiator has
- selected the mutual authentication option (by setting mutual-state
- bit in the options field of the REQ-TOKEN in the SPKM-REQ), the
- target MUST reply with:
-
- SPKM_REP_TI=<SPKM-REP-TI>
-
- where SPKM-REP-TI is the target token as defined in [RFC2025].
-
- If mutual authentication was selected and target authentication
- fails, the initiator MUST close the connection. Otherwise, if the
- AuthMethod is SPKM1, the initiator MUST continue with:
-
- SPKM_REP_IT=<SPKM-REP-IT>
-
- where SPKM-REP-IT is the second initiator token as defined in
- [RFC2025]. If the initiator authentication fails, the target MUST
- answer with a Login reject with "Authentication Failure" status.
-
- SPKM requires support for very long authentication items.
-
- All the SPKM-* tokens 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.
-
-11.1.3. 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.
-
-
-
-Satran, et al. Standards Track [Page 185]
-
-RFC 3720 iSCSI April 2004
-
-
- 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.
-
- 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.
-
-11.1.4. Challenge Handshake Authentication Protocol (CHAP)
-
- For CHAP [RFC1994], in the first step, the initiator MUST send:
-
- CHAP_A=<A1,A2...>
-
- Where A1,A2... are proposed algorithms, in order of preference.
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 186]
-
-RFC 3720 iSCSI April 2004
-
-
- In the second step, the target MUST answer with a Login reject with
- the "Authentication Failure" status or reply with:
-
- CHAP_A=<A> CHAP_I=<I> CHAP_C=<C>
-
- Where A is one of A1,A2... that were proposed by the initiator.
-
- In the third step, the initiator MUST continue with:
-
- CHAP_N=<N> CHAP_R=<R>
-
- or, if it requires target authentication, with:
-
- CHAP_N=<N> CHAP_R=<R> CHAP_I=<I> CHAP_C=<C>
-
- If the initiator authentication fails, the target MUST answer with a
- Login reject with "Authentication Failure" status. Otherwise, if the
- initiator required target authentication, the target MUST either
- answer with a Login reject with "Authentication Failure" or reply
- with:
-
- CHAP_N=<N> CHAP_R=<R>
-
- If target authentication fails, the initiator MUST close the
- connection.
-
- Where N, (A,A1,A2), I, C, and R are (correspondingly) the Name,
- Algorithm, Identifier, Challenge, and Response as defined in
- [RFC1994], N is a text string, A,A1,A2, and I are numbers, and C and
- R are large-binary-values and their binary length (not the length of
- the character string that represents them in encoded form) MUST not
- exceed 1024 bytes.
-
- For the Algorithm, as stated in [RFC1994], one value is required to
- be implemented:
-
- 5 (CHAP with MD5)
-
- To guarantee interoperability, initiators MUST always offer it as one
- of the proposed algorithms.
-
-12. Login/Text Operational Text Keys
-
- Some session specific parameters MUST only be carried on the leading
- connection and cannot be changed after the leading connection login
- (e.g., MaxConnections, the maximum number of connections). This
-
-
-
-
-
-Satran, et al. Standards Track [Page 187]
-
-RFC 3720 iSCSI April 2004
-
-
- holds for a single connection session with regard to connection
- restart. The keys that fall into this category have the use: LO
- (Leading Only).
-
- Keys that can only be used during login have the use: IO (initialize
- only), while those that can be used in both the Login Phase and Full
- Feature Phase have the use: ALL.
-
- Keys that can only be used during Full Feature Phase use FFPO (Full
- Feature Phase only).
-
- Keys marked as Any-Stage may also appear in the SecurityNegotiation
- stage while all other keys described in this chapter are operational
- keys.
-
- Keys that do not require an answer are marked as Declarative.
-
- Key scope is indicated as session-wide (SW) or connection-only (CO).
-
- Result function, wherever mentioned, states the function that can be
- applied to check the validity of the responder selection. Minimum
- means that the selected value cannot exceed the offered value.
- Maximum means that the selected value cannot be lower than the
- offered value. AND means that the selected value must be a possible
- result of a Boolean "and" function with an arbitrary Boolean value
- (e.g., if the offered value is No the selected value must be No). OR
- means that the selected value must be a possible result of a Boolean
- "or" function with an arbitrary Boolean value (e.g., if the offered
- value is Yes the selected value must be Yes).
-
-12.1. HeaderDigest and DataDigest
-
- Use: IO
- Senders: Initiator and Target
- Scope: CO
-
- HeaderDigest = <list-of-values>
- DataDigest = <list-of-values>
-
- Default is None for both HeaderDigest and DataDigest.
-
- Digests enable the checking of end-to-end, non-cryptographic data
- integrity beyond the integrity checks provided by the link layers and
- the covering of the whole communication path including all elements
- that may change the network level PDUs such as routers, switches, and
- proxies.
-
-
-
-
-
-Satran, et al. Standards Track [Page 188]
-
-RFC 3720 iSCSI April 2004
-
-
- The following table lists cyclic integrity checksums that can be
- negotiated for the digests and that 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 for this digest is given in
- hex-notation (e.g., 0x3b stands for 0011 1011 and the polynomial is
- x**5+X**4+x**3+x+1).
-
- When the Initiator and Target agree on a digest, this digest MUST be
- used for every PDU in Full Feature Phase.
-
- Padding bytes, when present in a segment covered by a CRC, SHOULD be
- set to 0 and are included in the CRC.
-
- The CRC MUST be calculated by a method that produces the same
- results as the following process:
-
- - The PDU bits are considered as the coefficients of a
- polynomial M(x) of degree n-1; bit 7 of the lowest numbered
- byte is considered the most significant bit (x^n-1), followed
- by bit 6 of the lowest numbered byte through bit 0 of the
- highest numbered byte (x^0).
-
- - The most significant 32 bits are complemented.
-
- - The polynomial is multiplied by x^32 then divided by G(x). The
- generator polynomial produces a remainder R(x) of degree <= 31.
-
- - The coefficients of R(x) are considered a 32 bit sequence.
-
- - The bit sequence is complemented and the result is the CRC.
-
- - The CRC bits are mapped into the digest word. The x^31
- coefficient in bit 7 of the lowest numbered byte of the digest
- continuing through to the byte up to the x^24 coefficient in
- bit 0 of the lowest numbered byte, continuing with the x^23
- coefficient in bit 7 of next byte through x^0 in bit 0 of the
- highest numbered byte.
-
-
-
-
-Satran, et al. Standards Track [Page 189]
-
-RFC 3720 iSCSI April 2004
-
-
- - Computing the CRC over any segment (data or header) extended
- to include the CRC built using the generator 0x11edc6f41 will
- always get the value 0x1c2d19ed as its final remainder (R(x)).
- This value is given here in its polynomial form (i.e., not
- mapped as the digest word).
-
- For a discussion about selection criteria for the CRC, see
- [RFC3385]. For a detailed analysis of 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 in absence of explicit
- administrative action) the implementer MUST ensure that CRC32C is
- listed as an alternative in the default offer and "None" is not
- part of the default offer.
-
- Extension digest algorithms MUST be named using one of the following
- two formats:
-
- a) Y-reversed.vendor.dns_name.do_something=
- b) Y<#><IANA-registered-string>=
-
- Digests named using the Y- format are used for private purposes
- (unregistered). Digests named using the Y# format (public extension)
- must be registered with IANA and MUST be described by an
- informational RFC.
-
- For private extension digests, to identify the vendor, we suggest
- you use the reversed DNS-name as a prefix to the proper digest
- names.
-
- The part of digest-name following Y- and Y# MUST conform to the
- format for standard-label specified in Section 5.1 Text Format.
-
- Support for public or private extension digests is OPTIONAL.
-
-12.2. MaxConnections
-
- Use: LO
- Senders: Initiator and Target
- Scope: SW
- Irrelevant when: SessionType=Discovery
-
- MaxConnections=<numerical-value-from-1-to-65535>
-
- Default is 1.
- Result function is Minimum.
-
-
-
-Satran, et al. Standards Track [Page 190]
-
-RFC 3720 iSCSI April 2004
-
-
-
- Initiator and target negotiate the maximum number of connections
- requested/acceptable.
-
-12.3. SendTargets
-
- Use: FFPO
- Senders: Initiator
- Scope: SW
-
- For a complete description, see Appendix D. - SendTargets
- Operation -.
-
-12.4. TargetName
-
- Use: IO by initiator, FFPO by target - only as response to a
- SendTargets, Declarative, Any-Stage
-
- Senders: Initiator and Target
- Scope: SW
-
- TargetName=<iSCSI-name-value>
-
- Examples:
-
- TargetName=iqn.1993-11.com.disk-vendor:diskarrays.sn.45678
- TargetName=eui.020000023B040506
-
- The initiator of the TCP connection MUST provide this key to the
- remote endpoint in the first login request if the initiator is not
- establishing a discovery session. The iSCSI Target Name specifies
- the worldwide unique name of the target.
-
- The TargetName key may also be returned by the "SendTargets" text
- request (which is its only use when issued by a target).
-
- TargetName MUST not be redeclared within the login phase.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 191]
-
-RFC 3720 iSCSI April 2004
-
-
-12.5. InitiatorName
-
- Use: IO, Declarative, Any-Stage
- Senders: Initiator
- Scope: SW
-
- InitiatorName=<iSCSI-name-value>
-
- Examples:
-
- InitiatorName=iqn.1992-04.com.os-vendor.plan9:cdrom.12345
- InitiatorName=iqn.2001-02.com.ssp.users:customer235.host90
-
- The initiator of the TCP connection MUST provide this key to the
- remote endpoint at the first Login of the Login Phase for every
- connection. The InitiatorName key enables the initiator to identify
- itself to the remote endpoint.
-
- InitiatorName MUST not be redeclared within the login phase.
-
-12.6. TargetAlias
-
- Use: ALL, Declarative, Any-Stage
- Senders: Target
- Scope: SW
-
- TargetAlias=<iSCSI-local-name-value>
-
- Examples:
-
- TargetAlias=Bob-s Disk
- TargetAlias=Database Server 1 Log Disk
- TargetAlias=Web Server 3 Disk 20
-
- If a target has been configured with a human-readable name or
- description, this name SHOULD be communicated to the initiator during
- a Login Response PDU if SessionType=Normal (see Section 12.21
- SessionType). This string is not used as an identifier, nor is it
- meant to be used for authentication or authorization decisions. It
- can be displayed by the initiator's user interface in a list of
- targets to which it is connected.
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 192]
-
-RFC 3720 iSCSI April 2004
-
-
-12.7. InitiatorAlias
-
- Use: ALL, Declarative, Any-Stage
- Senders: Initiator
- Scope: SW
-
- InitiatorAlias=<iSCSI-local-name-value>
-
- Examples:
-
- InitiatorAlias=Web Server 4
- InitiatorAlias=spyalley.nsa.gov
- InitiatorAlias=Exchange Server
-
- If an initiator has been configured with a human-readable name or
- description, it SHOULD be communicated to the target during a Login
- Request PDU. If not, the host name can be used instead. This string
- is not used as an identifier, nor is meant to be used for
- authentication or authorization decisions. It can be displayed by
- the target's user interface in a list of initiators to which it is
- connected.
-
-12.8. TargetAddress
-
- Use: ALL, Declarative, Any-Stage
- Senders: Target
- Scope: SW
-
- TargetAddress=domainname[:port][,portal-group-tag]
-
- The domainname can be specified as either a DNS host name, a
- dotted-decimal IPv4 address, or a bracketed IPv6 address as specified
- in [RFC2732].
-
- If the TCP port is not specified, it is assumed to be the
- IANA-assigned default port for iSCSI (see Section 13 IANA
- Considerations).
-
- If the TargetAddress is returned 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 within a SendTargets response, the
- portal group tag MUST be included.
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 193]
-
-RFC 3720 iSCSI April 2004
-
-
- Examples:
-
- 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,23
-
- Use of the portal-group-tag is described in Appendix D.
- - SendTargets Operation -. The formats for the port and
- portal-group-tag are the same as the one specified in Section 12.9
- TargetPortalGroupTag.
-
-12.9. TargetPortalGroupTag
-
- Use: IO by target, Declarative, Any-Stage
- Senders: Target
- Scope: SW
-
- TargetPortalGroupTag=<16-bit-binary-value>
-
- Examples:
- TargetPortalGroupTag=1
-
- The target portal group tag is a 16-bit binary-value that uniquely
- identifies a portal group within an iSCSI target node. This key
- carries the value of the tag of the portal group that is servicing
- the Login request. The iSCSI target returns this key to the
- initiator in the Login Response PDU to the first Login Request PDU
- that has the C bit set to 0 when TargetName is given by the
- initiator.
-
- For the complete usage expectations of this key see Section 5.3 Login
- Phase.
-
-12.10. InitialR2T
-
- Use: LO
- Senders: Initiator and Target
- Scope: SW
- Irrelevant when: SessionType=Discovery
-
- InitialR2T=<boolean-value>
-
- Examples:
-
- I->InitialR2T=No
- T->InitialR2T=No
-
-
-
-
-Satran, et al. Standards Track [Page 194]
-
-RFC 3720 iSCSI April 2004
-
-
- Default is Yes.
- Result function is OR.
-
- The InitialR2T key is used to turn off the default use of R2T for
- unidirectional and the output part of bidirectional commands, thus
- allowing an initiator to start sending data to a target as if it has
- received an initial R2T with Buffer Offset=Immediate Data Length and
- Desired Data Transfer Length=(min(FirstBurstLength, Expected Data
- Transfer Length) - Received Immediate Data Length).
-
- The default action is that R2T is required, unless both the initiator
- and the target send this key-pair attribute specifying InitialR2T=No.
- Only the first outgoing data burst (immediate data and/or separate
- PDUs) can be sent unsolicited (i.e., not requiring an explicit R2T).
-
-12.11. ImmediateData
-
- Use: LO
- Senders: Initiator and Target
- Scope: SW
- Irrelevant when: SessionType=Discovery
-
- ImmediateData=<boolean-value>
-
- Default is Yes.
- Result function is AND.
-
- The initiator and target negotiate support for immediate data. To
- turn immediate data off, the initiator or target must state its
- desire to do so. ImmediateData can be turned on if both the
- initiator and target have ImmediateData=Yes.
-
- If ImmediateData is set to Yes and InitialR2T is set to Yes
- (default), then only immediate data are accepted in the first burst.
-
- If ImmediateData is set to No and InitialR2T is set to Yes, then the
- initiator MUST NOT send unsolicited data and the target MUST reject
- unsolicited data with the corresponding response code.
-
- If ImmediateData is set to No and InitialR2T is set to No, then the
- initiator MUST NOT send unsolicited immediate data, but MAY send one
- unsolicited burst of Data-Out PDUs.
-
- If ImmediateData is set to Yes and InitialR2T is set to No, then the
- initiator MAY send unsolicited immediate data and/or one unsolicited
- burst of Data-Out PDUs.
-
-
-
-
-
-Satran, et al. Standards Track [Page 195]
-
-RFC 3720 iSCSI April 2004
-
-
- The following table is a summary of unsolicited data options:
-
- +----------+-------------+------------------+--------------+
- |InitialR2T|ImmediateData| Unsolicited |Immediate Data|
- | | | Data Out PDUs | |
- +----------+-------------+------------------+--------------+
- | No | No | Yes | No |
- +----------+-------------+------------------+--------------+
- | No | Yes | Yes | Yes |
- +----------+-------------+------------------+--------------+
- | Yes | No | No | No |
- +----------+-------------+------------------+--------------+
- | Yes | Yes | No | Yes |
- +----------+-------------+------------------+--------------+
-
-12.12. MaxRecvDataSegmentLength
-
- Use: ALL, Declarative
- Senders: Initiator and Target
- Scope: CO
-
- MaxRecvDataSegmentLength=<numerical-value-512-to-(2**24-1)>
-
- Default is 8192 bytes.
-
- The initiator or target declares the maximum data segment length in
- bytes it can receive in an iSCSI PDU.
-
- The transmitter (initiator or target) is required to send PDUs with a
- data segment that does not exceed MaxRecvDataSegmentLength of the
- receiver.
-
- A target receiver is additionally limited by MaxBurstLength for
- solicited data and FirstBurstLength for unsolicited data. An
- initiator MUST NOT send solicited PDUs exceeding MaxBurstLength nor
- unsolicited PDUs exceeding FirstBurstLength (or
- FirstBurstLength-Immediate Data Length if immediate data were sent).
-
-12.13. MaxBurstLength
-
- Use: LO
- Senders: Initiator and Target
- Scope: SW
- Irrelevant when: SessionType=Discovery
-
- MaxBurstLength=<numerical-value-512-to-(2**24-1)>
-
-
-
-
-
-Satran, et al. Standards Track [Page 196]
-
-RFC 3720 iSCSI April 2004
-
-
- Default is 262144 (256 Kbytes).
- Result function is Minimum.
-
- The initiator and target negotiate maximum SCSI data payload in bytes
- in a Data-In or a solicited Data-Out iSCSI sequence. A sequence
- consists of one or more consecutive Data-In or Data-Out PDUs that end
- with a Data-In or Data-Out PDU with the F bit set to one.
-
-12.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)>
-
- Default is 65536 (64 Kbytes).
- Result function is Minimum.
-
- The initiator and target negotiate the maximum amount in bytes of
- unsolicited data an iSCSI initiator may send to the target during the
- execution of a single SCSI command. 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.
-
-12.15. DefaultTime2Wait
-
- Use: LO
- Senders: Initiator and Target
- Scope: SW
-
- DefaultTime2Wait=<numerical-value-0-to-3600>
-
- Default is 2.
- Result function is Maximum.
-
- The initiator and target negotiate the minimum time, in seconds, to
- wait before attempting an explicit/implicit logout or an active task
- reassignment after an unexpected connection termination or a
- connection reset.
-
- A value of 0 indicates that logout or active task reassignment can be
- attempted immediately.
-
-
-
-
-Satran, et al. Standards Track [Page 197]
-
-RFC 3720 iSCSI April 2004
-
-
-12.16. DefaultTime2Retain
-
- Use: LO Senders: Initiator and Target Scope: SW
-
- DefaultTime2Retain=<numerical-value-0-to-3600>
-
- Default is 20. Result function is Minimum.
-
- The initiator and target negotiate the maximum time, in seconds after
- an initial wait (Time2Wait), before 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 indicates that connection/task state is immediately
- discarded by the target.
-
-12.17. MaxOutstandingR2T
-
- Use: LO
- Senders: Initiator and Target
- Scope: SW
-
- MaxOutstandingR2T=<numerical-value-from-1-to-65535>
- Irrelevant when: SessionType=Discovery
-
- Default is 1.
- Result function is Minimum.
-
- Initiator and target negotiate the maximum number of outstanding R2Ts
- per task, excluding any implied initial R2T that might be part of
- that task. An R2T is considered outstanding until the last data PDU
- (with the F bit set to 1) is transferred, or a sequence reception
- timeout (Section 6.1.4.1 Recovery Within-command) is encountered for
- that data sequence.
-
-12.18. DataPDUInOrder
-
- Use: LO
- Senders: Initiator and Target
- Scope: SW
- Irrelevant when: SessionType=Discovery
-
- DataPDUInOrder=<boolean-value>
-
-
-
-
-
-Satran, et al. Standards Track [Page 198]
-
-RFC 3720 iSCSI April 2004
-
-
- Default is Yes.
- Result function is OR.
-
- No is used by iSCSI to indicate that the data PDUs within sequences
- can be in any order. Yes is used to indicate that data PDUs within
- sequences have to be at continuously increasing addresses and
- overlays are forbidden.
-
-12.19. DataSequenceInOrder
-
- Use: LO
- Senders: Initiator and Target
- Scope: SW
- Irrelevant when: SessionType=Discovery
-
- DataSequenceInOrder=<boolean-value>
-
- Default is Yes.
- Result function is OR.
-
- A Data Sequence is a sequence of Data-In or Data-Out PDUs that end
- with a Data-In or Data-Out PDU with the F bit set to one. A Data-Out
- sequence is sent either unsolicited or in response to an R2T.
- Sequences cover an offset-range.
-
- If DataSequenceInOrder is set to No, Data PDU sequences may be
- transferred in any order.
-
- If DataSequenceInOrder is set to Yes, Data Sequences MUST be
- transferred using continuously non-decreasing sequence offsets (R2T
- buffer offset for writes, or the smallest SCSI Data-In buffer offset
- within a read data sequence).
-
- If DataSequenceInOrder is set to Yes, a target may retry at most the
- last R2T, and an initiator may at most request retransmission for the
- last read data sequence. For this reason, if ErrorRecoveryLevel is
- not 0 and DataSequenceInOrder is set to Yes then MaxOustandingR2T
- MUST be set to 1.
-
-12.20. ErrorRecoveryLevel
-
- Use: LO
- Senders: Initiator and Target
- Scope: SW
-
- ErrorRecoveryLevel=<numerical-value-0-to-2>
-
-
-
-
-
-Satran, et al. Standards Track [Page 199]
-
-RFC 3720 iSCSI April 2004
-
-
- Default is 0.
- Result function is Minimum.
-
- The initiator and target negotiate the recovery level supported.
-
- Recovery levels represent a combination of recovery capabilities.
- Each recovery level includes all the capabilities of the lower
- recovery levels and adds some new ones to them.
-
- In the description of recovery mechanisms, certain recovery classes
- are specified. Section 6.1.5 Error Recovery Hierarchy describes the
- mapping between the classes and the levels.
-
-12.21. SessionType
-
- Use: LO, Declarative, Any-Stage
- Senders: Initiator
- Scope: SW
-
- SessionType= <Discovery|Normal>
-
- Default is Normal.
-
- The initiator indicates the type of session it wants to create. The
- target can either accept it or reject it.
-
- A discovery session indicates to the Target that the only purpose of
- this Session is discovery. The only requests a target accepts in
- this type 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 an explicit setting.
-
-12.22. The Private or Public Extension Key Format
-
- Use: ALL
- Senders: Initiator and Target
- Scope: specific key dependent
-
- X-reversed.vendor.dns_name.do_something=
-
- or
-
- X<#><IANA-registered-string>=
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 200]
-
-RFC 3720 iSCSI April 2004
-
-
- Keys with this format are used for public or private extension
- purposes. These keys always start with X- if unregistered with IANA
- (private) or X# if registered with IANA (public).
-
- For unregistered keys, to identify the vendor, we suggest you use the
- reversed DNS-name as a prefix to the key-proper.
-
- The part of key-name following X- and X# MUST conform to the format
- for key-name specified in Section 5.1 Text Format.
-
- For IANA registered keys the string following X# must be registered
- with IANA and the use of the key MUST be described by an
- informational RFC.
-
- Vendor specific keys MUST ONLY be used in normal sessions.
-
- Support for public or private extension keys is OPTIONAL.
-
-13. IANA Considerations
-
- This section conforms to [RFC2434].
-
- The well-known user TCP port number for iSCSI connections assigned by
- IANA is 3260 and this is the default iSCSI port. Implementations
- needing a system TCP port number may use port 860, the port assigned
- by IANA as the iSCSI system port; however in order to use port 860,
- it MUST be explicitly specified - implementations MUST NOT default to
- use of port 860, as 3260 is the only allowed default.
-
- Extension keys, authentication methods, or digest types for which a
- vendor or group of vendors intend to provide publicly available
- descriptions MUST be described by an RFC and MUST be registered with
- IANA.
-
- The IANA has set up the following three registries:
-
- a) iSCSI extended key registry
- b) iSCSI authentication methods registry
- c) iSCSI digests registry
-
- [RFC3723] also instructs IANA to maintain a registry for the values
- of the SRP_GROUP key. The format of these values must conform to the
- one specified for iSCSI extension item-label in Section 13.5.4
- Standard iSCSI extension item-label format.
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 201]
-
-RFC 3720 iSCSI April 2004
-
-
- For the iSCSI authentication methods registry and the iSCSI digests
- registry, IANA MUST also assign a 16-bit unsigned integer number (the
- method number for the authentication method and the digest number for
- the digest).
-
- The following initial values for the registry for authentication
- methods are specified by the standards action of this document:
-
- Authentication Method | Number |
- +----------------------------------------+--------+
- | CHAP | 1 |
- +----------------------------------------+--------+
- | SRP | 2 |
- +----------------------------------------+--------+
- | KRB5 | 3 |
- +----------------------------------------+--------+
- | SPKM1 | 4 |
- +----------------------------------------+--------+
- | SPKM2 | 5 |
- +----------------------------------------+--------+
-
- All other record numbers from 0 to 255 are reserved. IANA will
- register numbers above 255.
-
- Authentication methods with numbers above 255 MUST be unique within
- the registry and MUST be used with the prefix Z#.
-
-
- The following initial values for the registry for digests are
- specified by the standards action of this document:
-
- Digest | Number |
- +----------------------------------------+--------+
- | CRC32C | 1 |
- +----------------------------------------+--------+
-
- All other record numbers from 0 to 255 are reserved. IANA will
- register numbers above 255.
-
- Digests with numbers above 255 MUST be unique within the registry and
- MUST be used with the prefix Y#.
-
- The RFC that describes the item to be registered MUST indicate in the
- IANA Considerations section the string and iSCSI registry to which it
- should be recorded.
-
- Extension Keys, Authentication Methods, and digests (iSCSI extension
- items) must conform to a number of requirements as described below.
-
-
-
-Satran, et al. Standards Track [Page 202]
-
-RFC 3720 iSCSI April 2004
-
-
-13.1. Naming Requirements
-
- Each iSCSI extension item must have a unique name in its category.
- This name will be used as a standard-label for the key, access
- method, or digest and must conform to the syntax specified in Section
- 13.5.4 Standard iSCSI extension item-label format for iSCSI extension
- item-labels.
-
-13.2. Mechanism Specification Requirements
-
- For iSCSI extension items all of the protocols and procedures used by
- a given iSCSI extension item must be described, either in the
- specification of the iSCSI extension item itself or in some other
- publicly available specification, in sufficient detail for the iSCSI
- extension item to be implemented by any competent implementor. Use
- of secret and/or proprietary methods in iSCSI extension items are
- expressly prohibited. In addition, the restrictions imposed by
- [RFC1602] on the standardization of patented algorithms must be
- respected.
-
-13.3. Publication Requirements
-
- All iSCSI extension items must be described by an RFC. The RFC may
- be informational rather than Standards-Track, although Standards
- Track review and approval are encouraged for all iSCSI extension
- items.
-
-13.4. Security Requirements
-
- Any known security issues that arise from the use of the iSCSI
- extension item must be completely and fully described. It is not
- required that the iSCSI extension item be secure or that it be free
- from risks, but that the known risks be identified. Publication of a
- new iSCSI extension item does not require an exhaustive security
- review, and the security considerations section is subject to
- continuing evaluation.
-
- Additional security considerations should be addressed by publishing
- revised versions of the iSCSI extension item specification.
-
- For each of these registries, IANA must record the registered string,
- which MUST conform to the format rules described in Section 13.5.4
- Standard iSCSI extension item-label format for iSCSI extension
- item-labels, and the RFC number that describes it. The key prefix
- (X#, Y# or Z#) is not part of the recorded string.
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 203]
-
-RFC 3720 iSCSI April 2004
-
-
-13.5. Registration Procedure
-
- Registration of a new iSCSI extension item starts with the
- construction of an Internet Draft to become an RFC.
-
-13.5.1. Present the iSCSI extension item to the Community
-
- Send a proposed access type specification to the IPS WG mailing list,
- or if the IPS WG is disbanded at the registration time, to a mailing
- list designated by the IETF Transport Area Director for a review
- period of a month. The intent of the public posting is to solicit
- comments and feedback on the iSCSI extension item specification and a
- review of any security considerations.
-
-13.5.2. iSCSI extension item review and IESG approval
-
- When the one month period has passed, the IPS WG chair or a person
- nominated by the IETF Transport Area Director (the iSCSI extension
- item reviewer) forwards the Internet Draft to the IESG for
- publication as an informational RFC or rejects it. If the
- specification is a standards track document, the usual IETF
- procedures for such documents are followed.
-
- Decisions made by the iSCSI extension item reviewer must be published
- within two weeks after the month-long review period. Decisions made
- by the iSCSI extension item reviewer can be appealed through the IESG
- appeal process.
-
-13.5.3. IANA Registration
-
- Provided that the iSCSI extension item has either passed review or
- has been successfully appealed to the IESG, and the specification is
- published as an RFC, then IANA will register the iSCSI extension item
- and make the registration available to the community.
-
-13.5.4. Standard iSCSI extension item-label format
-
- The following character symbols are used iSCSI extension item-labels
- (the hexadecimal values represent Unicode code points):
-
- (a-z, A-Z) - letters
- (0-9) - digits
- "." (0x2e) - dot
- "-" (0x2d) - minus
- "+" (0x2b) - plus
- "@" (0x40) - commercial at
- "_" (0x5f) - underscore
-
-
-
-
-Satran, et al. Standards Track [Page 204]
-
-RFC 3720 iSCSI April 2004
-
-
- An iSCSI extension item-label is a string of one or more characters
- that consist of letters, digits, dot, minus, plus, commercial at, or
- underscore. An iSCSI extension item-label MUST begin with a capital
- letter and must not exceed 63 characters.
-
-13.6. IANA Procedures for Registering iSCSI extension items
-
- The identity of the iSCSI extension item reviewer is communicated to
- the IANA by the IESG. Then, the IANA only acts in response to iSCSI
- extension item definitions that are approved by the iSCSI extension
- item reviewer and forwarded by the reviewer to the IANA for
- registration, or in response to a communication from the IESG that an
- iSCSI extension item definition appeal has overturned the iSCSI
- extension item reviewer's ruling.
-
-References
-
-Normative References
-
- [CAM] ANSI X3.232-199X, Common Access Method-3.
-
- [EUI] "Guidelines for 64-bit Global Identifier (EUI-64)",
- http:
- //standards.ieee.org/regauth/oui/tutorials/EUI64.html
-
- [OUI] "IEEE OUI and Company_Id Assignments",
- http://standards.ieee.org/regauth/oui
-
- [RFC791] Postel, J., "Internet Protocol", STD 5, RFC 791,
- September 1981.
-
- [RFC793] Postel, J., "Transmission Control Protocol", STD 7,
- RFC 793, September 1981.
-
- [RFC1035] Mockapetris, P., "Domain Names - Implementation and
- Specification", STD 13, RFC 1035, November 1987.
-
- [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts-
- Communication Layer", STD 3, RFC 1122, October 1989.
-
- [RFC1510] Kohl, J. and C. Neuman, "The Kerberos Network
- Authentication Service (V5)", RFC 1510, September
- 1993.
-
- [RFC1737] Sollins, K. and L. Masinter "Functional Requirements
- for Uniform Resource Names"RFC 1737, December 1994.
-
-
-
-
-
-Satran, et al. Standards Track [Page 205]
-
-RFC 3720 iSCSI April 2004
-
-
- [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.
-
- [RFC2025] Adams, C., "The Simple Public-Key GSS-API Mechanism
- (SPKM)", RFC 2025, October 1996.
-
- [RFC2045] Borenstein, N. and N. Freed, "MIME (Multipurpose
- Internet Mail Extensions) Part One: Mechanisms for
- Specifying and Describing the Format of Internet
- Message Bodies", RFC 2045, November 1996.
-
- [RFC2119] Bradner, S. "Key Words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC2279] Yergeau, F., "UTF-8, a Transformation Format of ISO
- 10646", RFC 2279 October 1996.
-
- [RFC2373] Hinden, R. and S. Deering, "IP Version 6 Addressing
- Architecture", RFC 2373, July 1998.
-
- [RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter "Uniform
- Resource Identifiers", RFC 2396, August 1998.
-
- [RFC2401] Kent, S. and R. Atkinson, "Security Architecture for
- the Internet Protocol", RFC 2401, November 1998.
-
- [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.
-
- [RFC2407] Piper, D., "The Internet IP Security Domain of
- Interpretation of ISAKMP", RFC 2407, November 1998.
-
- [RFC2409] Harkins, D. and D. Carrel, "The Internet Key Exchange
- (IKE)", RFC2409, November 1998.
-
- [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing
- an IANA Considerations Section in RFCs.", BCP 26, RFC
- 2434, October 1998.
-
-
-
-
-Satran, et al. Standards Track [Page 206]
-
-RFC 3720 iSCSI April 2004
-
-
- [RFC2451] Pereira, R. and R. Adams " The ESP CBC-Mode Cipher
- Algorithms", RFC 2451, November 1998.
-
- [RFC2732] Hinden, R., Carpenter, B. and L. Masinter, "Format for
- Literal IPv6 Addresses in URL's", RFC 2451, December
- 1999.
-
- [RFC2945] Wu, T., "The SRP Authentication and Key Exchange
- System", RFC 2945, September 2000.
-
- [RFC3066] Alvestrand, H., "Tags for the Identification of
- Languages", STD 47, RFC 3066, January 2001.
-
- [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.
-
- [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, March
- 2004.
-
- [RFC3723] Aboba, B., Tseng, J., Walker, J., Rangan, V. and F.
- Travostino, "Securing Block Storage Protocols over
- IP", RFC 3723, March 2004.
-
- [SAM2] T10/1157D, SCSI Architecture Model - 2 (SAM-2).
-
- [SBC] NCITS.306-1998, SCSI-3 Block Commands (SBC).
-
- [SPC3] T10/1416-D, SCSI Primary Commands-3.
-
- [UNICODE] Unicode Standard Annex #15, "Unicode Normalization
- Forms", http://www.unicode.org/unicode/reports/tr15
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 207]
-
-RFC 3720 iSCSI April 2004
-
-
-Informative References
-
- [BOOT] P. Sarkar, et al., "Bootstrapping Clients using the
- iSCSI Protocol", Work in Progress, July 2003.
-
- [Castagnoli93] G. Castagnoli, S. Braeuer and M. Herrman "Optimization
- of Cyclic Redundancy-Check Codes with 24 and 32 Parity
- Bits", IEEE Transact. on Communications, Vol. 41, No.
- 6, June 1993.
-
- [CORD] Chadalapaka, M. and R. Elliott, "SCSI Command
- Ordering Considerations with iSCSI", Work in Progress.
-
- [RFC3347] Krueger, M., Haagens, R., Sapuntzakis, C. and M.
- Bakke, "Small Computer Systems Interface protocol over
- the Internet (iSCSI) Requirements and Design
- Considerations", RFC 3347, July 2002.
-
- [RFC3385] Sheinwald, D., Staran, J., Thaler, P. and V. Cavanna,
- "Internet Protocol Small Computer System Interface
- (iSCSI) Cyclic Redundancy Check (CRC)/Checksum
- Considerations", RFC 3385, September 2002.
-
- [RFC3721] Bakke M., Hafner, J., Hufferd, J., Voruganti, K. and
- M. Krueger, "Internet Small Computer Systems Interface
- (iSCSI) Naming and Discovery, RFC 3721, March 2004.
-
- [SEQ-EXT] Kent, S., "IP Encapsulating Security Payload (ESP)",
- Work in Progress, July 2002.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 208]
-
-RFC 3720 iSCSI April 2004
-
-
-Appendix A. Sync and Steering with Fixed Interval Markers
-
- This appendix presents a simple scheme for synchronization (PDU
- boundary retrieval). It uses markers that include synchronization
- information placed at fixed intervals in the TCP stream.
-
- A Marker consists of:
-
- 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| Next-iSCSI-PDU-start pointer - copy #1 |
- +---------------+---------------+---------------+---------------+
- 4| Next-iSCSI-PDU-start pointer - copy #2 |
- +---------------+---------------+---------------+---------------+
-
- The Marker scheme uses payload byte stream counting that includes
- every byte placed by iSCSI in the TCP stream except for the markers
- themselves. It also excludes any bytes that TCP counts but are not
- originated by iSCSI.
-
- Markers MUST NOT be included in digest calculation.
-
- The Marker indicates the offset to the next iSCSI PDU header. The
- Marker is eight bytes in length and contains two 32-bit offset fields
- that indicate how many bytes to skip in the TCP stream in order to
- find the next iSCSI PDU header. The marker uses two copies of the
- pointer so that a marker that spans a TCP packet boundary should
- leave at least one valid copy in one of the packets.
-
- The structure and semantics of an inserted marker are independent of
- the marker interval.
-
- The use of markers is negotiable. The initiator and target MAY
- indicate their readiness to receive and/or send markers during login
- separately for each connection. The default is No.
-
-A.1. Markers At Fixed Intervals
-
- A marker is inserted at fixed intervals in the TCP byte stream.
- During login, each end of the iSCSI session specifies the interval at
- which it is willing to receive the marker, or it disables the marker
- altogether. If a receiver indicates that it desires a marker, the
- sender MAY agree (during negotiation) and provide the marker at the
- desired interval. However, in certain environments, a sender that
- does not provide markers to a receiver that wants markers may suffer
- an appreciable performance degradation.
-
-
-
-Satran, et al. Standards Track [Page 209]
-
-RFC 3720 iSCSI April 2004
-
-
- The marker interval and the initial marker-less interval are counted
- in terms of the bytes placed in the TCP stream data by iSCSI.
-
- When reduced to iSCSI terms, markers MUST indicate the offset to a
- 4-byte word boundary in the stream. The least significant two bits
- of each marker word are reserved and are considered 0 for offset
- computation.
-
- Padding iSCSI PDU payloads to 4-byte word boundaries simplifies
- marker manipulation.
-
-A.2. Initial Marker-less Interval
-
- To enable the connection setup including the Login Phase negotiation,
- marking (if any) is only started at the first marker interval after
- the end of the Login Phase. However, in order to enable the marker
- inclusion and exclusion mechanism to work without knowledge of the
- length of the Login Phase, the first marker will be placed in the TCP
- stream as if the Marker-less interval had included markers.
-
- Thus, all markers appear in the stream at locations conforming to the
- formula: [(MI + 8) * n - 8] where MI = Marker Interval, n = integer
- number.
-
- For example, if the marker interval is 512 bytes and the login ended
- at byte 1003 (first iSCSI placed byte is 0), the first marker will be
- inserted after byte 1031 in the stream.
-
-A.3. Negotiation
-
- The following operational key=value pairs are used to negotiate the
- fixed interval markers. The direction (output or input) is relative
- to the initiator.
-
-A.3.1. OFMarker, IFMarker
-
- Use: IO
- Senders: Initiator and Target
- Scope: CO
-
- OFMarker=<boolean-value>
- IFMarker=<boolean-value>
-
- Default is No.
-
- Result function is AND.
-
-
-
-
-
-Satran, et al. Standards Track [Page 210]
-
-RFC 3720 iSCSI April 2004
-
-
- OFMarker is used to turn on or off the initiator to target markers
- on the connection. IFMarker is used to turn on or off the target to
- initiator markers on the connection.
-
- Examples:
-
- I->OFMarker=Yes,IFMarker=Yes
- T->OFMarker=Yes,IFMarker=Yes
-
- Results in the Marker being used in both directions while:
-
- I->OFMarker=Yes,IFMarker=Yes
- T->OFMarker=Yes,IFMarker=No
-
- Results in Marker being used from the initiator to the target, but
- not from the target to initiator.
-
-A.3.2. OFMarkInt, IFMarkInt
-
- Use: IO
- Senders: Initiator and Target
- Scope: CO
- OFMarkInt is Irrelevant when: OFMarker=No
- IFMarkInt is Irrelevant when: IFMarker=No
-
- Offering:
-
- OFMarkInt=<numeric-range-from-1-to-65535>
- IFMarkInt=<numeric-range-from-1-to-65535>
-
- Responding:
-
- OFMarkInt=<numeric-value-from-1-to-65535>|Reject
- IFMarkInt=<numeric-value-from-1-to-65535>|Reject
-
- OFMarkInt is used to set the interval for the initiator to target
- markers on the connection. IFMarkInt is used to set the interval for
- the target to initiator markers on the connection.
-
- For the offering, the initiator or target indicates the minimum to
- maximum interval (in 4-byte words) it wants the markers for one or
- both directions. In case it only wants a specific value, only a
- single value has to be specified. The responder selects a value
- within the minimum and maximum offered or the only value offered or
- indicates through the xFMarker key=value its inability to set and/or
- receive markers. When the interval is unacceptable the responder
- answers with "Reject". Reject is resetting the marker function in
- the specified direction (Output or Input) to No.
-
-
-
-Satran, et al. Standards Track [Page 211]
-
-RFC 3720 iSCSI April 2004
-
-
- The interval is measured from the end of a marker to the beginning of
- the next marker. For example, a value of 1024 means 1024 words (4096
- bytes of iSCSI payload between markers).
-
- The default is 2048.
-
-Appendix B. Examples
-
-B.1. Read Operation Example
-
- +------------------+-----------------------+----------------------+
- |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 | | |
- +------------------+-----------------------+----------------------+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 212]
-
-RFC 3720 iSCSI April 2004
-
-
-B.2. Write Operation Example
-
- +------------------+-----------------------+---------------------+
- |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 | | |
- +------------------+-----------------------+---------------------+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 213]
-
-RFC 3720 iSCSI April 2004
-
-
-B.3. R2TSN/DataSN Use Examples
-
- Output (write) data DataSN/R2TSN Example
-
- +------------------+-----------------------+----------------------+
- |Initiator Function| PDU Type & 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 | | |
- +------------------+-----------------------+----------------------+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 214]
-
-RFC 3720 iSCSI April 2004
-
-
- 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 | | |
- +------------------+-----------------------+----------------------+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 215]
-
-RFC 3720 iSCSI April 2004
-
-
- 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 = 1, F=0 | |
- +------------------+-----------------------+----------------------+
- | * Receive Data | <<< SCSI Data-In | Send Data |
- | | DataSN = 2, F=1 | |
- +------------------+-----------------------+----------------------+
- | * Send Data | SCSI Data-Out >>> | Receive Data |
- | for R2TSN 0 | DataSN = 0, F=1 | |
- +------------------+-----------------------+----------------------+
- | | <<< SCSI Response |Send Status and Sense |
- | | ExpDataSN = 3 | |
- +------------------+-----------------------+----------------------+
- | 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).
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 216]
-
-RFC 3720 iSCSI April 2004
-
-
- Unsolicited and immediate output (write) data with DataSN Example
-
- +------------------+-----------------------+----------------------+
- |Initiator Function| PDU Type & 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 | | |
- +------------------+-----------------------+----------------------+
-
-B.4. CRC Examples
-
- N.B. all Values are Hexadecimal
-
- 32 bytes of zeroes:
-
- Byte: 0 1 2 3
-
- 0: 00 00 00 00
- ...
- 28: 00 00 00 00
-
- CRC: aa 36 91 8a
-
- 32 bytes of ones:
-
- Byte: 0 1 2 3
-
- 0: ff ff ff ff
- ...
- 28: ff ff ff ff
-
-
-
-
-Satran, et al. Standards Track [Page 217]
-
-RFC 3720 iSCSI April 2004
-
-
- CRC: 43 ab a8 62
-
- 32 bytes of incrementing 00..1f:
-
- Byte: 0 1 2 3
-
- 0: 00 01 02 03
- ...
- 28: 1c 1d 1e 1f
-
- CRC: 4e 79 dd 46
-
- 32 bytes of decrementing 1f..00:
-
- Byte: 0 1 2 3
-
- 0: 1f 1e 1d 1c
- ...
- 28: 03 02 01 00
-
- CRC: 5c db 3f 11
-
- An iSCSI - SCSI Read (10) Command PDU
-
- 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 d9
-
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 218]
-
-RFC 3720 iSCSI April 2004
-
-
-Appendix C. Login Phase Examples
-
- In the first example, the initiator and target authenticate each
- other 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=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 contains the Kerberos V5 ticket and authenticator
- with MUTUAL-REQUIRED set in the ap-options field)
-
- If the authentication is successful, the target proceeds 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 the authentication is successful, the initiator may proceed
- 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"
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 219]
-
-RFC 3720 iSCSI April 2004
-
-
- If the initiator's authentication by the target is not
- successful, the target responds with:
-
- T-> Login "login reject"
-
- instead of the Login KRB_AP_REP message, and terminates the
- connection.
-
- If the target's authentication by the initiator is not
- successful, the initiator terminates the connection (without
- responding to the Login KRB_AP_REP message).
-
- In the next example only the initiator is 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 not set in the ap-options field of krb_ap_req)
-
- If the authentication is successful, 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"
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 220]
-
-RFC 3720 iSCSI April 2004
-
-
- In the next example, the initiator and target authenticate each
- other via SPKM1:
-
- 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=SPKM1,KRB5,None
-
- T-> Login (CSG,NSG=0,0 T=0)
- AuthMethod=SPKM1
-
- I-> Login (CSG,NSG=0,0 T=0)
- SPKM_REQ=<spkm-req>
-
- (spkm-req is the SPKM-REQ token with the mutual-state bit in the
- options field of the REQ-TOKEN set)
-
- T-> Login (CSG,NSG=0,0 T=0)
- SPKM_REP_TI=<spkm-rep-ti>
-
- If the authentication is successful, the initiator proceeds:
-
- I-> Login (CSG,NSG=0,1 T=1)
- SPKM_REP_IT=<spkm-rep-it>
-
- If the authentication is successful, the target proceeds with:
-
- T-> Login (CSG,NSG=0,1 T=1)
-
- The initiator may proceed:
-
- 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 target's authentication by the initiator is not
- successful, the initiator terminates the connection (without
- responding to the Login SPKM_REP_TI message).
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 221]
-
-RFC 3720 iSCSI April 2004
-
-
- If the initiator's authentication by the target is not
- successful, the target responds with:
-
- T-> Login "login reject"
-
- instead of the Login "proceed and change stage" message, and
- terminates the connection.
-
-
- In the next example, the initiator and target authenticate each
- other via SPKM2:
-
- 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=SPKM1,SPKM2
-
- T-> Login-PR (CSG,NSG=0,0 T=0)
- AuthMethod=SPKM2
-
- I-> Login (CSG,NSG=0,1 T=1)
- SPKM_REQ=<spkm-req>
-
- (spkm-req is the SPKM-REQ token with the mutual-state bit in the
- options field of the REQ-TOKEN not set)
-
- If the authentication is successful, the target proceeds with:
-
- T-> Login (CSG,NSG=0,1 T=1)
-
- The initiator may proceed:
-
- 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"
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 222]
-
-RFC 3720 iSCSI April 2004
-
-
- In the next example, the initiator and target authenticate each
- other 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=Yes
-
- T-> Login (CSG,NSG=0,0 T=0)
- SRP_GROUP=SRP-1536,SRP-1024
- SRP_s=<s>
-
- I-> Login (CSG,NSG=0,0 T=0)
- SRP_GROUP=SRP-1536
- 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 is successful, the target
- proceeds:
-
- 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 is not successful, the initiator
- terminates 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
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 223]
-
-RFC 3720 iSCSI April 2004
-
-
- 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 is not successful, the target
- responds with:
-
- T-> Login "login reject"
-
- Instead of the T-> Login SRP_HM=<H(A | M | K)> message and
- terminates the connection.
-
- In the next example, the initiator and target authenticate each
- other 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_GROUP=SRP-1536
- SRP_s=<s>
-
- I-> Login (CSG,NSG=0,0 T=0)
- SRP_GROUP=SRP-1536
- 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 is successful, the target
- proceeds:
-
- T-> Login (CSG,NSG=0,1 T=1)
-
-
-
-Satran, et al. Standards Track [Page 224]
-
-RFC 3720 iSCSI April 2004
-
-
-
- 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"
-
- In the next example the initiator and target authenticate each other
- via 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>
-
-
-
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 225]
-
-RFC 3720 iSCSI April 2004
-
-
- If the initiator authentication is successful, the target
- proceeds:
-
- T-> Login (CSG,NSG=0,1 T=1)
- CHAP_N=<N>
- CHAP_R=<R>
-
- If the target authentication is not successful, 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 is not successful, the target
- responds with:
-
- T-> Login "login reject"
-
- Instead of the Login CHAP_R=<response> "proceed and change
- stage" message and terminates the connection.
-
- In the next example, 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>
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 226]
-
-RFC 3720 iSCSI April 2004
-
-
- 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 is successful, the target
- proceeds:
-
- 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"
-
- In the next example, the initiator does not offer any security
- parameters. It therefore may offer iSCSI parameters on the Login PDU
- with the T bit set to 1, and the target may respond with a final
- Login Response PDU immediately:
-
- 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 parameters
-
- In the next example, the initiator does offer security
- parameters on the Login PDU, but the target does not choose
- any (i.e., 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
-
-
-
-Satran, et al. Standards Track [Page 227]
-
-RFC 3720 iSCSI April 2004
-
-
-
- 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"
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 228]
-
-RFC 3720 iSCSI April 2004
-
-
-Appendix D. SendTargets Operation
-
- To reduce the amount of configuration required on an initiator, iSCSI
- provides the SendTargets text request. The initiator uses the
- SendTargets request to get a list of targets to which it may have
- access, as well as the list of addresses (IP address and TCP port) on
- which these targets may be accessed.
-
- To make use of SendTargets, an initiator must first establish one of
- two types of sessions. If the initiator establishes the session
- using the key "SessionType=Discovery", the session is a discovery
- session, and a target name does not need to be specified. Otherwise,
- the session is a normal, operational session. The SendTargets
- command MUST only be sent during the Full Feature Phase of a normal
- or discovery session.
-
- A system that contains targets MUST support discovery sessions on
- each of its iSCSI IP address-port pairs, and MUST support the
- SendTargets command on the discovery session. In a discovery
- session, a target MUST return all path information (target name and
- IP address-port pairs and portal group tags) for the targets on the
- target network entity which the requesting initiator is authorized to
- access.
-
- A target MUST support the SendTargets command on operational
- sessions; these will only return path information about the target to
- which the session is connected, and do not need to return information
- about other target names that may be defined in the responding
- system.
-
- An initiator MAY make use of the SendTargets as it sees fit.
-
- A SendTargets command consists of a single Text request PDU. This
- PDU contains exactly one text key and value. The text key MUST be
- SendTargets. The expected response depends upon the value, as well
- as whether the session is a discovery or operational session.
-
- The value must be one of:
-
- All
-
- The initiator is requesting that information on all relevant
- targets known to the implementation be returned. This value
- MUST be supported on a discovery session, and MUST NOT be
- supported on an operational session.
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 229]
-
-RFC 3720 iSCSI April 2004
-
-
- <iSCSI-target-name>
-
- If an iSCSI target name is specified, the session should respond
- with addresses for only the 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 been returned had value=All had been
- designated.
-
- <nothing>
-
- The session should only respond with addresses for the target to
- which the session is logged in. This MUST be supported on
- operational sessions, and MUST NOT return targets other than
- the one to which the session is logged in.
-
- The response to this command is a text response that contains a list
- of zero or more targets and, optionally, their addresses. Each
- target is returned as a target record. A target record begins with
- the TargetName text key, followed by a list of TargetAddress text
- keys, and bounded by the end of the text response or the next
- TargetName key, which begins a new record. No text keys other than
- TargetName and TargetAddress are permitted within a SendTargets
- response.
-
- For the format of the TargetName, see Section 12.4 TargetName.
-
- In a discovery session, a target MAY respond to a SendTargets request
- with its complete list of targets, or with a list of targets that is
- 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 returned includes zero or more TargetAddress
- fields.
-
- Each target record starts with one text key of the form:
-
- TargetName=<target-name-goes-here>
-
- Followed by zero or more address keys of the form:
-
- TargetAddress=<hostname-or-ipaddress>[:<tcp-port>],
- <portal-group-tag>
-
- The hostname-or-ipaddress contains a domain name, IPv4 address, or
- IPv6 address, as specified for the TargetAddress key.
-
-
-
-Satran, et al. Standards Track [Page 230]
-
-RFC 3720 iSCSI April 2004
-
-
- A hostname-or-ipaddress duplicated in TargetAddress responses for a
- given node (the port is absent or equal) would probably indicate that
- multiple address families are in use at once (IPV6 and IPV4).
-
- Each TargetAddress belongs to a portal group, identified by its
- numeric portal group tag (as in Section 12.9 TargetPortalGroupTag).
- The iSCSI target name, together with this tag, constitutes the SCSI
- port identifier; the tag only needs 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 other addresses in its portal group in the
- same response.
-
- A SendTargets text response can be longer than a single Text Response
- PDU, and makes use of the long text responses as specified.
-
- After obtaining a list of targets from the discovery target session,
- an iSCSI initiator may initiate new sessions to log in to the
- discovered targets for full operation. The initiator MAY keep the
- discovery session open, and MAY send subsequent SendTargets commands
- to discover new targets.
-
- Examples:
-
- This example is the SendTargets response from a single target that
- has no other interface ports.
-
- Initiator sends text request that contains:
-
- SendTargets=All
-
- Target sends a text response that contains:
-
- TargetName=iqn.1993-11.com.example:diskarray.sn.8675309
-
- All the target had to return in the simple case was the target name.
- It is assumed by the initiator that the IP address and TCP port for
- this target are the same as used on the current connection to the
- default iSCSI target.
-
-
-
-
-
-Satran, et al. Standards Track [Page 231]
-
-RFC 3720 iSCSI April 2004
-
-
- The next example has two internal iSCSI targets, each accessible via
- two different ports with different IP addresses. The following is
- 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,2
-
- Both targets share both addresses; the multiple addresses are likely
- used to provide multi-path support. The initiator may connect to
- either target name on either address. Each of the addresses has its
- own portal group tag; they do not support spanning
- multiple-connection sessions with each other. Keep in mind that the
- portal group tags for the two named targets are independent of one
- another; portal group "1" on the first target is not necessarily the
- same as portal group "1" on the second target.
-
- In the above example, 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 spanning sessions
- across multiple addresses, and further illustrates the use of the
- portal group tags:
-
- 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,3
-
- In this example, any of the target addresses can be used to reach the
- same target. A single-connection session can be established to any
- of these TCP addresses. A multiple-connection session could span
- addresses .45 and .46 or .47 and .48, but cannot span any other
- combination. A TargetAddress with its own tag (.49) cannot be
- combined with any other address within the same session.
-
- This SendTargets response does not indicate whether .49 supports
- multiple connections per session; it is communicated via the
- MaxConnections text key upon login to the target.
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 232]
-
-RFC 3720 iSCSI April 2004
-
-
-Appendix E. Algorithmic Presentation of Error Recovery Classes
-
- This appendix illustrates the error recovery classes using a
- pseudo-programming-language. The procedure names are chosen to be
- obvious to most implementers. Each of the recovery classes described
- has initiator procedures as well as target procedures. These
- algorithms focus on outlining the mechanics of error recovery
- classes, and do not exhaustively describe all other aspects/cases.
- Examples of this approach are:
-
-
- - 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 strive to convey the iSCSI error recovery concepts
- in the simplest terms, and are not designed to be optimal.
-
-E.1. General Data Structure and Procedure Description
-
- This section defines the procedures and data structures that are
- commonly used by all the error recovery algorithms. The structures
- may not be the exhaustive representations of what is required for a
- typical implementation.
-
- 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;
-
-
-
-Satran, et al. Standards Track [Page 233]
-
-RFC 3720 iSCSI April 2004
-
-
- 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-a-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);
-
-E.2. Within-command Error Recovery Algorithms
-
-E.2.1. Procedure Descriptions
-
- 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);
-
-
-
-Satran, et al. Standards Track [Page 234]
-
-RFC 3720 iSCSI April 2004
-
-
- 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 used in this section: Handle-Status-SNACK-
- request is defined in Within-connection recovery algorithms.
-
- - The Response processing pseudo-code, shown in the target
- algorithms, applies to all solicited PDUs that carry StatSN -
- SCSI Response, Text Response etc.
-
-E.2.2. Initiator Algorithms
-
-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-a-In-PDU(Connection, CurrentPDU)
-{
- check-basic-validity(CurrentPDU);
- if (Header-Digest-Bad) discard, return;
- Retrieve TCB for CurrentPDU.InitiatorTaskTag.
-
-
-
-Satran, et al. Standards Track [Page 235]
-
-RFC 3720 iSCSI April 2004
-
-
- 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.
-
-
-
-Satran, et al. Standards Track [Page 236]
-
-RFC 3720 iSCSI April 2004
-
-
- 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);
- }
-}
-
-E.2.3. Target Algorithms
-
-Receive-a-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[].
- }
-
-
-
-Satran, et al. Standards Track [Page 237]
-
-RFC 3720 iSCSI April 2004
-
-
- }
- }
- 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 upto CurrentPDU.BegRun as
- acknowledged.
- Free up the retransmission resources for that data.
- } else if (CurrentPDU.type == R-Data SNACK) {
-
-
-
-Satran, et al. Standards Track [Page 238]
-
-RFC 3720 iSCSI April 2004
-
-
- 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);
- }
- }
-}
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 239]
-
-RFC 3720 iSCSI April 2004
-
-
-E.3. Within-connection Recovery Algorithms
-
-E.3.1. Procedure Descriptions
-
-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 tunables:
-InitiatorProactiveSNACKEnabled
-
- Notes:
-
- - The initiator algorithms only deal with unsolicited Nop-In PDUs
- for generating status SNACKs. A solicited Nop-In PDU has an
- assigned StatSN, which, when out of order, could trigger the
- out of order StatSN handling in Within-command algorithms,
- again leading to Recover-Status-if-Possible.
-
-
- - The pseudo-code shown may result in the retransmission of
- unacknowledged commands in more cases than necessary. This
- will not, however, affect the correctness of the operation
- because the target is required to discard the duplicate CmdSNs.
-
- - The procedure Build-And-Send-Async is defined in the Connection
- recovery algorithms.
-
- - The procedure Status-Expect-Timeout-Handler describes how
- initiators may proactively attempt to retrieve the Status if
- they so choose. This procedure is assumed to be triggered much
- before the standard ULP timeout.
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 240]
-
-RFC 3720 iSCSI April 2004
-
-
-E.3.2. Initiator Algorithms
-
-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);
- }
- }
-}
-
-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);
- }
-}
-
-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;
-
-
-
-Satran, et al. Standards Track [Page 241]
-
-RFC 3720 iSCSI April 2004
-
-
- } 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;
-}
-
-Receive-a-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 */
- }
-}
-
-Command-Acknowledge-Timeout-Handler(TCB)
-{
- Retrieve the Connection for TCB.
- Retransmit-Command-if-Possible(Connection, TCB.CmdSN);
-
-
-
-Satran, et al. Standards Track [Page 242]
-
-RFC 3720 iSCSI April 2004
-
-
-}
-
-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);
- }
- }
-}
-
-E.3.3. Target Algorithms
-
-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);
- }
-}
-
-E.4. Connection Recovery Algorithms
-
-E.4.1. Procedure Descriptions
-
-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);
-
-
-
-Satran, et al. Standards Track [Page 243]
-
-RFC 3720 iSCSI April 2004
-
-
-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);
-
-Notes:
- - 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_Handler procedure.
-
-E.4.2. Initiator Algorithms
-
- Receive-a-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;
-
-
-
-Satran, et al. Standards Track [Page 244]
-
-RFC 3720 iSCSI April 2004
-
-
- 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);
- }
- } }
-
- 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 =
-
-
-
-Satran, et al. Standards Track [Page 245]
-
-RFC 3720 iSCSI April 2004
-
-
- CreateTransportConnection(Session.OtherEndInfo);
- Initiate an implicit Logout on NewConnection for
- Connection.CID.
- return;
- }
- }
- Build-And-Send-Logout(NewConnection, Connection.CID,
- RecoveryRemove); }
-
- 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;
- } }
-
-E.4.3. Target Algorithms
-
- Receive-a-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,
-
-
-
-Satran, et al. Standards Track [Page 246]
-
-RFC 3720 iSCSI April 2004
-
-
- 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, "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,
-
-
-
-Satran, et al. Standards Track [Page 247]
-
-RFC 3720 iSCSI April 2004
-
-
- 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;
- }
- }
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 248]
-
-RFC 3720 iSCSI April 2004
-
-
-Appendix F. Clearing Effects of Various Events on Targets
-
-F.1. Clearing Effects on iSCSI Objects
-
- The following tables describe the target behavior on receiving the
- events specified in the rows of the table. The second table is an
- extension of the first table and defines clearing actions for more
- objects on the same events. The legend is:
-
- Y = Yes (cleared/discarded/reset on the event specified in the
- row). Unless otherwise noted, the clearing action is only
- applicable for the issuing initiator port.
- N = No (not affected on the event specified in the row, i.e.,
- stays at previous value).
- NA = Not Applicable or Not Defined.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 249]
-
-RFC 3720 iSCSI April 2004
-
-
- +-----+-----+-----+-----+-----+
- |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 |Y |Y |Y |Y |
- +---------------------+-----+-----+-----+-----+-----+
- |target warm reset(16)|Y |Y |Y |Y |Y |
- +---------------------+-----+-----+-----+-----+-----+
- |LU reset(19) |Y |Y |Y |Y |Y |
- +---------------------+-----+-----+-----+-----+-----+
- |powercycle(16) |Y |Y |Y |Y |Y |
- +---------------------+-----+-----+-----+-----+-----+
-
- 1. Incomplete TTTs - Target Transfer Tags on which the target is
- still expecting PDUs to be received. Examples include TTTs received
- via R2T, NOP-IN, etc.
-
- 2. Immediate Commands - immediate commands, but waiting for
- execution on a target. For example, Abort Task Set.
-
-
-
-
-
-Satran, et al. Standards Track [Page 250]
-
-RFC 3720 iSCSI April 2004
-
-
- 5. Connection Tasks - tasks that are active on the iSCSI connection
- in question.
-
- 6. Session Tasks - tasks that are active on the entire iSCSI
- session. A union of "connection tasks" on all participating
- connections.
-
- 7. Partial PDUs (if any) - PDUs that are partially sent and waiting
- for transport window credit to complete the transmission.
-
- 8. Connection failure is a connection exception condition - one of
- the transport connections shutdown, transport connections reset, or
- transport connections timed out, which abruptly terminated the iSCSI
- full-feature phase connection. A connection failure always takes the
- connection state machine to the CLEANUP_WAIT state.
-
- 9. Connection state timeout happens if a connection spends more time
- that agreed upon during Login negotiation in the CLEANUP_WAIT state,
- and this takes the connection to the FREE state (M1 transition in
- connection cleanup state diagram).
-
- 10. These are defined in Section 5.3.5 Session Reinstatement,
- Closure, and Timeout.
-
- 11. This clearing effect is "Y" only if it is a connection
- reinstatement and the operational ErrorRecoveryLevel is less than 2.
-
- 12. Session continuation is defined in Section 5.3.6 Session
- Continuation and Failure.
-
- 13. This clearing effect is only valid if the connection is being
- logged out on a different connection and when the connection being
- logged out on the target may have some partial PDUs pending to be
- sent. In all other cases, the effect is "NA".
-
- 14. This clearing effect is only valid for a "close the session"
- logout in a multi-connection session. In all other cases, the effect
- is "NA".
-
- 15. Only applicable if this leading connection login is a session
- reinstatement. If this is not the case, it is "NA".
-
- 16. This operation affects all logged-in initiators.
-
- 18. Session failure is defined in Section 5.3.6 Session Continuation
- and Failure.
-
-
-
-
-
-Satran, et al. Standards Track [Page 251]
-
-RFC 3720 iSCSI April 2004
-
-
- 19. This operation affects all logged-in initiators and the clearing
- effects are only applicable to the LU being reset.
-
- +-----+-----+-----+-----+-----+
- |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 |
- +---------------------+-----+-----+-----+-----+-----+
- |powercycle |Y |Y |Y |Y(10)|NA |
- +---------------------+-----+-----+-----+-----+-----+
-
- 1. Discontiguous Commands - commands allegiant to the connection in
- question and waiting to be reordered in the iSCSI layer. All "Y"s in
- this column assume that the task causing the event (if indeed the
- event is the result of a task) is issued as an immediate command,
- because the discontiguities can be ahead of the task.
-
-
-
-
-
-Satran, et al. Standards Track [Page 252]
-
-RFC 3720 iSCSI April 2004
-
-
- 2. Discontiguous Data - data PDUs received for the task in question
- and waiting to be reordered due to prior discontiguities in DataSN.
-
- 3. StatSN
-
- 4. CmdSN
-
- 5. DataSN
-
- 7. It clears the StatSN on all the connections.
-
- 8. This sequence number is instantiated on this event.
-
- 9. A logout failure drives the connection state machine to the
- CLEANUP_WAIT state, similar to the connection failure event. Hence,
- it has a similar effect on this and several other protocol aspects.
-
- 10. This is cleared by virtue of the fact that all sessions with all
- initiators are terminated.
-
- 11. This clearing effect is "Y" if it is a connection reinstatement.
-
- 12. This clearing effect is "Y" only if it is a connection
- reinstatement and the operational ErrorRecoveryLevel is 2.
-
- 13. This clearing effect is "N" only if it is a connection
- reinstatement and the operational ErrorRecoveryLevel is 2.
-
-F.2. Clearing Effects on SCSI Objects
-
- The only iSCSI protocol action that can effect clearing actions on
- SCSI objects is the "I_T nexus loss" notification (Section 4.3.5.1
- Loss of Nexus notification). [SPC3] describes the clearing effects
- of this notification on a variety of SCSI attributes. In addition,
- SCSI standards documents (such as [SAM2] and [SBC]) define additional
- clearing actions that may take place for several SCSI objects on SCSI
- events such as 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 must also be
- considered as the power-on reset event in interpreting the actions
- defined in the SCSI standards.
-
- When the iSCSI session is reconstructed (between the same SCSI ports
- with the same nexus identifier) reestablishing the same I_T nexus,
- all SCSI objects that are defined to not clear on the "I_T nexus
- loss" notification event, such as persistent reservations, are
- automatically associated to this new session.
-
-
-
-Satran, et al. Standards Track [Page 253]
-
-RFC 3720 iSCSI April 2004
-
-
-Acknowledgements
-
- This protocol was developed by a design team that, in addition to the
- authors, included Daniel Smith, Ofer Biran, Jim Hafner and John
- Hufferd (IBM), Mark Bakke (Cisco), Randy Haagens (HP), Matt Wakeley
- (Agilent, now Sierra Logic), Luciano Dalle Ore (Quantum), and Paul
- Von Stamwitz (Adaptec, now TrueSAN Networks).
-
- Furthermore, a large group of people contributed to this work through
- their review, comments, and valuable insights. We are grateful to
- all of them. We especially thank those people who found the time and
- patience to take part in our weekly phone conferences and
- intermediate meetings in Almaden and Haifa, which helped shape this
- document: Prasenjit Sarkar, Meir Toledano, John Dowdy, Steve Legg,
- Alain Azagury (IBM), Dave Nagle (CMU), David Black (EMC), John Matze
- (Veritas - now Okapi Software), Steve DeGroote, Mark Schrandt
- (Cisco), Gabi Hecht (Gadzoox), Robert Snively and Brian Forbes
- (Brocade), Nelson Nachum (StorAge), and Uri Elzur (Broadcom). Many
- others helped edit and improve this document within the IPS working
- group. We are especially grateful to David Robinson and Raghavendra
- Rao (Sun), Charles Monia, Joshua Tseng (Nishan), Somesh Gupta
- (Silverback), Michael Krause, Pierre Labat, Santosh Rao, Matthew
- Burbridge, Bob Barry, Robert Elliott, Nick Martin (HP), Stephen
- Bailey (Sandburst), Steve Senum, Ayman Ghanem, Dave Peterson (Cisco),
- Barry Reinhold (Trebia Networks), Bob Russell (UNH), Eddy Quicksall
- (iVivity, Inc.), Bill Lynn and Michael Fischer (Adaptec), Vince
- Cavanna, Pat Thaler (Agilent), Jonathan Stone (Stanford), Luben
- Tuikov (Splentec), Paul Koning (EqualLogic), Michael Krueger
- (Windriver), Martins Krikis (Intel), Doug Otis (Sanlight), John
- Marberg (IBM), Robert Griswold and Bill Moody (Crossroads), Bill
- Studenmund (Wasabi Systems), Elizabeth Rodriguez (Brocade) and Yaron
- Klein (Sanrad). The recovery chapter was enhanced with the help of
- Stephen Bailey (Sandburst), Somesh Gupta (Silverback), and Venkat
- Rangan (Rhapsody Networks). Eddy Quicksall contributed some examples
- and began the Definitions section. Michael Fischer and Bob Barry
- started the Acronyms section. Last, but not least, we thank Ralph
- Weber for keeping us in line with T10 (SCSI) standardization.
-
- We would like to thank Steve Hetzler for his unwavering support and
- for coming up with such a good name for the protocol, and Micky
- Rodeh, Jai Menon, Clod Barrera, and Andy Bechtolsheim for helping
- make this work happen.
-
- In addition to this document, we recommend you acquaint yourself with
- the following in order to get a full understanding of the iSCSI
- specification: "iSCSI Naming & Discovery"[RFC3721], "Bootstrapping
- Clients using the iSCSI Protocol" [BOOT], "Securing Block Storage
- Protocols over IP" [RFC3723] documents, "iSCSI Requirements and
-
-
-
-Satran, et al. Standards Track [Page 254]
-
-RFC 3720 iSCSI April 2004
-
-
- Design Considerations" [RFC3347] and "SCSI Command Ordering
- Considerations with iSCSI" [CORD].
-
- The "iSCSI Naming & Discovery" document is authored by:
-
- Mark Bakke (Cisco), Jim Hafner, John Hufferd, Kaladhar Voruganti
- (IBM), and Marjorie Krueger (HP).
-
- The "Bootstrapping Clients using the iSCSI Protocol" document is
- authored by:
-
- Prasenjit Sarkar (IBM), Duncan Missimer (HP), and Costa
- Sapuntzakis (Cisco).
-
- The "Securing Block Storage Protocols over IP" document is authored
- by:
-
- Bernard Aboba (Microsoft), Joshua Tseng (Nishan), Jesse Walker
- (Intel), Venkat Rangan (Rhapsody Networks), and Franco
- Travostino (Nortel Networks).
-
- The "iSCSI Requirements and Design Considerations" document is
- authored by:
-
- Marjorie Krueger, Randy Haagens (HP), Costa Sapuntzakis, and Mark
- Bakke (Cisco).
-
- The "SCSI Command Ordering Considerations with iSCSI" document is
- authored by:
-
- Mallikarjun Chadalapaka, Rob Elliot (HP)
-
- We are grateful to all of them for their good work and for helping us
- correlate this document with the ones they produced.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 255]
-
-RFC 3720 iSCSI April 2004
-
-
-Authors' Addresses
-
- Julian Satran
- IBM Research Laboratory in Haifa
- Haifa University Campus - Mount Carmel
- Haifa 31905, Israel
-
- Phone +972.4.829.6264
- EMail: Julian_Satran@il.ibm.com
-
-
- Kalman Meth
- IBM Research Laboratory in Haifa
- Haifa University Campus - Mount Carmel
- Haifa 31905, Israel
-
- Phone +972.4.829.6341
- EMail: meth@il.ibm.com
-
-
- Costa Sapuntzakis
- Stanford University
- 353 Serra Mall Dr #407
- Stanford, CA 94305
-
- Phone: +1.650.723.2458
- EMail: csapuntz@alum.mit.edu
-
-
- Efri Zeidner
- XIV Ltd.
- 1 Azrieli Center,
- Tel-Aviv 67021, Israel
-
- Phone: +972.3.607.4722
- EMail: efri@xiv.co.il
-
-
- Mallikarjun Chadalapaka
- Hewlett-Packard Company
- 8000 Foothills Blvd.
- Roseville, CA 95747-5668, USA
-
- Phone: +1.916.785.5621
- EMail: cbm@rose.hp.com
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 256]
-
-RFC 3720 iSCSI April 2004
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2004). This document is subject
- to the rights, licenses and restrictions contained in BCP 78, and
- except as set forth therein, the authors retain all their rights.
-
- This document and the information contained herein are provided on an
- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Intellectual Property
-
- The IETF takes no position regarding the validity or scope of any
- Intellectual Property Rights or other rights that might be claimed to
- pertain to the implementation or use of the technology described in
- this document or the extent to which any license under such rights
- might or might not be available; nor does it represent that it has
- made any independent effort to identify any such rights. Information
- on the procedures with respect to rights in RFC documents can be
- found in BCP 78 and BCP 79.
-
- Copies of IPR disclosures made to the IETF Secretariat and any
- assurances of licenses to be made available, or the result of an
- attempt made to obtain a general license or permission for the use of
- such proprietary rights by implementers or users of this
- specification can be obtained from the IETF on-line IPR repository at
- http://www.ietf.org/ipr.
-
- The IETF invites any interested party to bring to its attention any
- copyrights, patents or patent applications, or other proprietary
- rights that may cover technology that may be required to implement
- this standard. Please address the information to the IETF at ietf-
- ipr@ietf.org.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-Satran, et al. Standards Track [Page 257]
-
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/utils/open-isns/doc/rfc3722.txt open-iscsi-2.0-872-rc4-bnx2i.work/utils/open-isns/doc/rfc3722.txt
--- open-iscsi-2.0-872-rc4-bnx2i/utils/open-isns/doc/rfc3722.txt 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/utils/open-isns/doc/rfc3722.txt 1969-12-31 18:00:00.000000000 -0600
@@ -1,451 +0,0 @@
-
-
-
-
-
-
-Network Working Group M. Bakke
-Request for Comments: 3722 Cisco
-Category: Standards Track April 2004
-
-
- String Profile for Internet Small Computer
- Systems Interface (iSCSI) Names
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2004). All Rights Reserved.
-
-Abstract
-
- This document describes how to prepare internationalized iSCSI names
- to increase the likelihood that name input and comparison work in
- ways that make sense for typical users throughout the world.
-
- The Internet Small Computer Systems Interface (iSCSI) protocol
- provides a way for hosts to access SCSI devices over an IP network.
- The iSCSI end-points, called initiators and targets, each have a
- globally-unique name that must be transcribable, as well as easily
- compared.
-
-1. Introduction
-
- The iSCSI protocol [RFC3720] provides a way for hosts to access SCSI
- [SAM2] devices over an IP network. The iSCSI end-points, called
- initiators and targets, each have a globally-unique name, defined in
- [RFC3721].
-
- An iSCSI name is a string of UTF-8 [RFC3629] characters that includes
- a type designator, a naming authority based on domain names, and a
- unique part within the naming authority. The unique part may be
- generated based on anything the naming authority deems useful, and
- may include user input.
-
- These names may need to be transcribed (sent between two
- administrators via email, voice, paper, etc), so a case-insensitive
- comparison would be desirable. However, these names must often be
-
-
-
-Bakke Standards Track [Page 1]
-
-RFC 3722 String Profile for iSCSI Names April 2004
-
-
- compared by initiator and target implementations, most of which are
- done in simple, embedded software. This makes case-sensitive
- comparison highly desirable for these implementors.
-
- However, a completely case-sensitive implementation would result in
- identifiers such as "example-name" and "Example-Name" being
- different, which could lead to confusion as these names are
- transcribed.
-
- The goal, then, is to generate iSCSI names that can be transcribed
- and entered by users, and also compared byte-for-byte, with minimal
- confusion. To attain these goals, iSCSI names are generalized using
- a normalized character set (converted to lower case or equivalent),
- with no white space allowed, and very limited punctuation.
-
- For those using only ASCII characters (U+0000 to U+007F), the
- following characters are allowed:
-
- - ASCII dash character ('-' = U+002d)
- - ASCII dot character ('.' = U+002e)
- - ASCII colon character (':' = U+003a)
- - ASCII lower-case characters ('a'..'z' = U+0061..U+007a)
- - ASCII digit characters ('0'..'9' = U+0030..U+0039)
-
- In addition, any upper-case characters input via a user interface
- MUST be mapped to their lower-case equivalents.
-
- This document specifies the valid character set for iSCSI names,
- along with the rules for normalizing and generating iSCSI names based
- on user input or other information that contains international
- characters.
-
- In particular, it defines the following, as required by [RFC3454]:
-
- - The intended applicability of the profile: internationalized iSCSI
- names.
-
- - The character repertoire that is the input and output to
- stringprep: Unicode 3.2, specified in section 3.
-
- - The mappings used: specified in section 4.
-
- - The Unicode normalization used: specified in section 5.
-
- - The characters that are prohibited as output: specified in section
- 6.
-
- This profile MUST be used with the iSCSI protocol.
-
-
-
-Bakke Standards Track [Page 2]
-
-RFC 3722 String Profile for iSCSI Names April 2004
-
-
-2. Terminology
-
- 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 [RFC2119].
-
- Examples in this document use the notation for code points and names
- from the Unicode Standard [Unicode3.2] and ISO/IEC 10646 [ISO10646].
- For example, the letter "a" may be represented as either "U+0061" or
- "LATIN SMALL LETTER A". In the lists of prohibited characters, the
- "U+" is left off to make the lists easier to read. The comments for
- character ranges are shown in square brackets (such as "[SYMBOLS]")
- and do not come from the standards.
-
-3. Character Repertoire
-
- This profile uses Unicode 3.2, as defined in [RFC3454] Appendix A.
-
-4. Mapping
-
- This profile specifies mapping using the following tables from
- [RFC3454]. The following mapping tables MUST be used when generating
- iSCSI names from Unicode characters.
-
- Table B.1
- Table B.2
-
-5. Normalization
-
- Unicode normalization form KC MUST be used with this profile, as
- described in [RFC3454].
-
-6. Prohibited Output
-
- This profile specifies prohibiting using the following tables from
- [RFC3454]. Characters appearing within these tables MUST NOT be used
- within an iSCSI name.
-
- Table C.1.1
- Table C.1.2
- Table C.2.1
- Table C.2.2
- Table C.3
- Table C.4
- Table C.5
- Table C.6
-
-
-
-
-
-Bakke Standards Track [Page 3]
-
-RFC 3722 String Profile for iSCSI Names April 2004
-
-
- Table C.7
- Table C.8
- Table C.9
-
- Important note: this profile MUST be used with the iSCSI protocol.
- The iSCSI protocol has additional naming rules that are checked
- outside of this profile.
-
- In addition, this profile adds the following prohibitions. The full
- set of prohibited characters are those from the tables above plus
- those listed individually below.
-
-6.1. Inappropriate Characters from Common Input Mechanisms
-
- u+3002 is used as if it were u+002e in many domain name input
- mechanisms used by applications, particularly in Asia. The character
- u+3002 MUST NOT be used in an iSCSI name.
-
- 3002; ideographic full stop
-
-6.2. Currently-prohibited ASCII characters
-
- Some of the ASCII characters that are currently prohibited in iSCSI
- names by [RFC3721] are also used in protocol elements such as URIs.
- Some examples are described in [RFC2396] and [RFC2732]. Note that
- there are many other RFCs that define additional URI schemes.
-
- The other characters in the range U+0000 to U+007F that are not
- currently allowed are prohibited in iSCSI names to reserve them for
- future use in protocol elements. Note that the dash (U+002D), dot
- (U+002E), and colon (U+003A) are not prohibited.
-
- The following characters MUST NOT be used in iSCSI names:
-
- 0000-002C; [ASCII CONTROL CHARACTERS and SPACE through ,]
- 002F; [ASCII /]
- 003B-0040; [ASCII ; through @]
- 005B-0060; [ASCII [ through `]
- 007B-007F; [ASCII { through DEL]
-
-7. Bidirectional Characters
-
- This profile specifies checking bidirectional strings as described in
- [RFC3454] section 6.
-
-
-
-
-
-
-
-Bakke Standards Track [Page 4]
-
-RFC 3722 String Profile for iSCSI Names April 2004
-
-
-8. Unassigned Code Points in Internationalized Domain Names
-
- If the processing in [RFC3720] specifies that a list of unassigned
- code points be used, the system uses table A.1 from [RFC3454] as its
- list of unassigned code points.
-
-9. Security Considerations
-
- ISO/IEC 10646 has many characters that look similar. In many cases,
- users of security protocols might do visual matching, such as when
- comparing the names of trusted third parties. This profile does
- nothing to map similar-looking characters together.
-
- iSCSI names may be used by an initiator to verify that a target it
- has discovered is the correct one, and by a target to verify that an
- initiator is to be allowed access. If these names are interpreted
- and compared differently by different iSCSI implementations, an
- initiator could gain access to the wrong target, or could be denied
- access to a legitimate target.
-
-10. IANA Considerations
-
- This is a profile of stringprep. It has been registered in the IANA
- "Stringprep Profiles" registry. This process is described in the
- IANA Considerations section of [RFC3454].
-
-11. Summary
-
- This document describes a stringprep profile to be used with programs
- generating names for iSCSI initiators and targets.
-
-12. Acknowledgements
-
- This document was produced as a result of discussions on iSCSI name
- formats with Joe Czap, Jim Hafner, Howard Hall, Jack Harwood, John
- Hufferd, Marjorie Krueger, Lawrence Lamers, Todd Sperry, Joshua
- Tseng, and Kaladhar Voruganti, as well as discussions on the
- normalization of names into identifiers with Paul Hoffman and Marc
- Blanchet.
-
- Thanks also to Bob Snively for suggesting the use of the nameprep
- process for iSCSI name normalization.
-
- Most of this document was copied from the stringprep profile for
- Internationalized Domain Names [RFC3491], written by Paul Hoffman and
- Marc Blanchet.
-
-
-
-
-
-Bakke Standards Track [Page 5]
-
-RFC 3722 String Profile for iSCSI Names April 2004
-
-
-13. References
-
-13.1. Normative References
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC3454] Hoffman, P. and M. Blanchet, "Preparation of
- Internationalized Strings ("stringprep")", RFC 3454,
- December 2002.
-
- [RFC3720] Satran, J., Meth, K., Sapuntzakis, C. Chadalapaka, M.
- and E. Zeidner, "Internet Small Computer Systems
- Interface (iSCSI)", RFC 3720, April 2004.
-
-13.2. Informative References
-
- [RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform
- Resource Identifiers", RFC 2396, August 1998.
-
- [RFC2732] Hinden, R., Carpenter, B. and L. Masinter, "Format for
- Literal IPv6 Addresses in URL's", RFC 2732, December
- 1999.
-
- [RFC3491] Hoffman, P. and M. Blanchet, "Nameprep: A Stringprep
- Profile for Internationalized Domain Names", RFC 3491,
- March 2003.
- [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
- 10646", STD 63, RFC 3629, November 2003.
-
- [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.
-
- [SAM2] ANSI T10. "SCSI Architectural Model 2", March 2000.
-
- [Unicode3.2] The Unicode Standard, Version 3.2.0: The Unicode
- Consortium. The Unicode Standard, Version 3.2.0 is
- defined by The Unicode Standard, Version 3.0 (Reading,
- MA, Addison-Wesley, 2000. ISBN 0-201-61633-5), as
- amended by the Unicode Standard Annex #27: Unicode 3.1
- (http://www.unicode.org/unicode/reports/tr27/) and by
- the Unicode Standard Annex #28: Unicode 3.2
- (http://www.unicode.org/unicode/reports/tr28/).
-
-
-
-
-
-
-
-Bakke Standards Track [Page 6]
-
-RFC 3722 String Profile for iSCSI Names April 2004
-
-
- [ISO10646] ISO/IEC 10646-1:2000. International Standard --
- Information technology -- Universal Multiple-Octet Coded
- Character Set (UCS) -- Part 1: Architecture and Basic
- Multilingual Plane.
-
-14. Author's Address
-
- Mark Bakke
- Cisco Systems, Inc.
- 6450 Wedgwood Road
- Maple Grove, MN
- USA 55311
-
- Voice: +1 763-398-1000
- EMail: mbakke@cisco.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Bakke Standards Track [Page 7]
-
-RFC 3722 String Profile for iSCSI Names April 2004
-
-
-15. Full Copyright Statement
-
- Copyright (C) The Internet Society (2004). This document is subject
- to the rights, licenses and restrictions contained in BCP 78, and
- except as set forth therein, the authors retain all their rights.
-
- This document and the information contained herein are provided on an
- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Intellectual Property
-
- The IETF takes no position regarding the validity or scope of any
- Intellectual Property Rights or other rights that might be claimed to
- pertain to the implementation or use of the technology described in
- this document or the extent to which any license under such rights
- might or might not be available; nor does it represent that it has
- made any independent effort to identify any such rights. Information
- on the procedures with respect to rights in RFC documents can be
- found in BCP 78 and BCP 79.
-
- Copies of IPR disclosures made to the IETF Secretariat and any
- assurances of licenses to be made available, or the result of an
- attempt made to obtain a general license or permission for the use of
- such proprietary rights by implementers or users of this
- specification can be obtained from the IETF on-line IPR repository at
- http://www.ietf.org/ipr.
-
- The IETF invites any interested party to bring to its attention any
- copyrights, patents or patent applications, or other proprietary
- rights that may cover technology that may be required to implement
- this standard. Please address the information to the IETF at ietf-
- ipr@ietf.org.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-Bakke Standards Track [Page 8]
-
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/utils/open-isns/doc/rfc4018.txt open-iscsi-2.0-872-rc4-bnx2i.work/utils/open-isns/doc/rfc4018.txt
--- open-iscsi-2.0-872-rc4-bnx2i/utils/open-isns/doc/rfc4018.txt 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/utils/open-isns/doc/rfc4018.txt 1969-12-31 18:00:00.000000000 -0600
@@ -1,1291 +0,0 @@
-
-
-
-
-
-
-Network Working Group M. Bakke
-Request for Comments: 4018 Cisco
-Category: Standards Track J. Hufferd
- K. Voruganti
- IBM
- M. Krueger
- HP
- T. Sperry
- Adaptec
- April 2005
-
-
- Finding Internet Small Computer Systems Interface (iSCSI) Targets
- and Name Servers by Using Service Location Protocol version 2 (SLPv2)
-
-Status of This Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2005).
-
-Abstract
-
- The iSCSI protocol provides a way for hosts to access SCSI devices
- over an IP network. This document defines the use of the Service
- Location Protocol (SLP) by iSCSI hosts, devices, and management
- services, along with the SLP service type templates that describe the
- services they provide.
-
-Table of Contents
-
- 1. Introduction................................................ 2
- 2. Notation Conventions........................................ 2
- 3. Terminology................................................. 3
- 4. Using SLP for iSCSI Service Discovery....................... 4
- 5. iSCSI SLP Templates......................................... 11
- 6. Security Considerations..................................... 18
- 7. IANA Considerations......................................... 19
- 8. Summary..................................................... 19
- 9. Normative References........................................ 19
- 10. Informative References...................................... 20
- 11. Acknowledgements............................................ 21
-
-
-
-Bakke & Hufferd Standards Track [Page 1]
-
-RFC 4018 iSCSI and SLPv2 April 2005
-
-
-1. Introduction
-
- iSCSI [RFC3720] is a protocol used to transport SCSI [SAM2] commands,
- data, and status across an IP network. This protocol is connection-
- oriented and is currently defined over TCP. iSCSI uses a client-
- server relationship. The client end of the connection is an
- initiator, and it sends SCSI commands; the server end of the
- connection is called a target, and it receives and executes the
- commands.
-
- There are several methods an iSCSI initiator can use to find the
- targets to which it should connect. Two of these methods can be
- accomplished without the use of SLP:
-
- - Each target and its address can be statically configured on the
- initiator.
-
- - Each address providing targets can be configured on the initiator;
- iSCSI provides a mechanism by which the initiator can query the
- address for a list of targets.
-
- The above methods are further defined in "iSCSI Naming and Discovery
- Requirements" [RFC3721].
-
- Each of the above methods requires a small amount of configuration to
- be done on each initiator. The ability to discover targets and name
- services without having to configure initiators is a desirable
- feature. The Service Location Protocol (SLP) [RFC2608] is an IETF
- standards track protocol providing several features that will
- simplify locating iSCSI services. This document describes how SLP
- can be used in iSCSI environments to discover targets, addresses
- providing targets, and storage management servers.
-
-2. Notation Conventions
-
- In this document, the key words "MUST", "MUST NOT", "REQUIRED",
- "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
- and "OPTIONAL" are to be interpreted as described in [RFC2119].
-
-
-
-
-
-
-
-
-
-
-
-
-
-Bakke & Hufferd Standards Track [Page 2]
-
-RFC 4018 iSCSI and SLPv2 April 2005
-
-
-3. Terminology
-
- Here are some definitions that may aid readers who are unfamiliar
- with SLP, SCSI, or iSCSI. Some of these definitions have been
- reproduced from [RFC2608] and "Finding an RSIP Server with SLP"
- [RFC3105].
-
- User Agent (UA) A process working on the client's behalf
- to establish contact with some service.
- The UA retrieves service information from
- the Service Agents or Directory Agents.
-
- Service Agent (SA) A process working on behalf of one or more
- services to advertise the services and
- their capabilities.
-
- Directory Agent (DA) A process that collects service
- advertisements. There can only be one DA
- present per given host.
-
- Scope A named set of services, typically making
- up a logical administrative group.
-
- Service Advertisement A URL, attributes, and a lifetime
- (indicating how long the advertisement is
- valid) providing service access
- information and capabilities description
- for a particular service.
-
- Initiator A logical entity, typically within a host,
- that sends SCSI commands to targets to be
- executed. An initiator is usually present
- in the form of a device driver.
-
- Target A logical entity, typically within a
- storage controller or gateway that
- receives SCSI commands from an initiator
- and executes them. A target includes one
- or more Logical Units (LUs); each LU is a
- SCSI device, such as a disk or tape drive.
-
- iSCSI Name A UTF-8 character string that serves as a
- unique identifier for iSCSI initiators and
- targets. Its format and usage is further
- defined in [RFC3721].
-
- iSCSI Client A logical entity, typically a host that
- includes at least one iSCSI Initiator.
-
-
-
-Bakke & Hufferd Standards Track [Page 3]
-
-RFC 4018 iSCSI and SLPv2 April 2005
-
-
- iSCSI Server A logical entity, typically a storage
- controller or gateway that includes at
- least one iSCSI Target.
-
- Storage Management Server An addressable entity that provides
- management services that benefit an iSCSI
- environment. "Storage management server"
- is used as a generic term and does not
- indicate a specific protocol or service.
-
-4. Using SLP for iSCSI Service Discovery
-
- Two entities are involved in iSCSI discovery. The end result is that
- an iSCSI initiator (e.g., a host) discovers iSCSI targets, usually
- provided by storage controllers or gateways.
-
- iSCSI targets are registered with SLP as a set of service URLs, one
- for each address on which the target may be accessed. Initiators
- discover these targets by using SLP service requests. Targets that
- do not directly support SLP or that are under the control of a
- management service may be registered by a proxy service agent as part
- of the software providing this service.
-
- iSCSI entities may also use SLP to discover higher-level management
- services when these are needed.
-
- This section first describes the use of SLP for discovery of targets
- by iSCSI initiators, it then describes the use of SLP to discover
- storage management servers.
-
- This document assumes that SLPv2 will be used for discovering iSCSI-
- related services; no attempt is made to include support for SLPv1.
-
-4.1. Discovering iSCSI Targets with SLP
-
- The following diagram shows the relationship among iSCSI clients,
- servers, initiators, and targets. An iSCSI client includes at least
- one iSCSI initiator, and an SLP user agent (UA). An iSCSI server
- includes at least one iSCSI target an SLP service agent (SA). Some
- entities, such as extended copy engines, include both initiators and
- targets. These include both an SA, for its targets to be discovered,
- and a UA, for its initiator(s) to discover other targets.
-
-
-
-
-
-
-
-
-
-Bakke & Hufferd Standards Track [Page 4]
-
-RFC 4018 iSCSI and SLPv2 April 2005
-
-
- +---------------------------------+
- | iSCSI Client |
- | +-----------+ |
- | | iSCSI | |
- | | initiator | |
- | | "myhost" | |
- | +-----------+ |
- | |
- +--------------------------+------+
- | iSCSI Driver | UA |
- +--------------------------+------+
- | TCP/UDP/IP |
- +----------------+----------------+
- | Interface 1 | Interface 2 |
- +----------------+----------------+
- | |
- +------------+ | | +------------+
- | SLP DA | | | | SLP DA |
- | (optional) |----+ IP Networks +----| (optional) |
- +------------+ | | +------------+
- | |
- +-----------------+-----------------|
- | Interface 1 | Interface 2 |
- | 192.0.2.131 | 192.0.2.3 |
- +-----------------+-----------------+
- | TCP/UDP/IP |
- +---------------------------+-------+
- | iSCSI Driver | SA |
- +---------------------------+-------|
- | |
- | +--------+ +--------+ +---------+ |
- | | iSCSI | | iSCSI | | iSCSI | |
- | | target | | target | | target | |
- | | "one" | | "two" | | "three" | |
- | +--------+ +--------+ +---------+ |
- | iSCSI Server |
- +-----------------------------------+
-
- In the above drawing, the iSCSI server has three iSCSI targets that
- the client could discover, named "one", "two" and "three". The iSCSI
- client has an iSCSI initiator with the name "myhost". The iSCSI
- client may use the initiator name in its SLP Service Requests as a
- filter to discover only targets that are configured to accept iSCSI
- connections from "myhost".
-
- Each iSCSI target and initiator has a unique name, called an iSCSI
- Name. This identifier is the same regardless of the network path
- (through adapter cards, networks, and interfaces on the storage
-
-
-
-Bakke & Hufferd Standards Track [Page 5]
-
-RFC 4018 iSCSI and SLPv2 April 2005
-
-
- device) over which the target is discovered and accessed. For this
- example, the iSCSI names "one", "two", and "three" are used for the
- targets; the initiator uses the name "myhost". An actual iSCSI name
- would incorporate more structure, including a naming authority, and
- is not described here.
-
- Each of the iSCSI targets in the drawing can appear at two addresses,
- since two network interfaces are present. Each target would have two
- service URLs, unless a single service URL included a DNS host name
- mapping to both addresses.
-
- An iSCSI target URL consists of its fully qualified host name or IP
- address, the TCP port on which it is listening, and its iSCSI name.
- An iSCSI server must register each of its individual targets at each
- of its network addresses.
-
- The iSCSI server constructs a service advertisement of the type
- "service:iscsi:target" for each of the service URLs it wishes to
- register. The advertisement contains a lifetime, along with other
- attributes that are defined in the service template.
-
- If the server in the above drawing is listening at TCP port 3260 for
- both network addresses, the service URLs registered would be
-
- - 192.0.2.131:3260/one
-
- - 192.0.2.131:3260/two
-
- - 192.0.2.131:3260/three
-
- - 192.0.2.3:3260/one
-
- - 192.0.2.3:3260/two
-
- - 192.0.2.3:3260/three
-
- The remainder of the discovery procedure is identical to that used by
- any client/server pair implementing SLP:
-
- 1. If an SLP DA is found, the SA contacts the DA and registers the
- service advertisement. Whether or not one or more SLPv2 DAs are
- discovered, the SA maintains the advertisement itself and answers
- multicast UA queries directly.
-
- 2. When the iSCSI initiator requires contact information for an
- iSCSI target, the UA either contacts the DA by using unicast or
- the SA by using multicast. If a UA is configured with the
- address of the SA, it may avoid multicast and may contact an SA
-
-
-
-Bakke & Hufferd Standards Track [Page 6]
-
-RFC 4018 iSCSI and SLPv2 April 2005
-
-
- by using unicast. The UA includes a query based on the
- attributes to indicate the characteristics of the target(s) it
- requires.
-
- 3. Once the UA has the host name or address of the iSCSI server, as
- well as the port number and iSCSI Target Name, it can begin the
- normal iSCSI login to the target.
-
- As information contained in the iSCSI target template may exceed
- common network datagram sizes, the SLP implementation for both UAs
- and SAs supporting this template MUST implement SLP over TCP.
-
-4.1.1. Finding Targets Based on Initiator Credentials
-
- To be allowed access to an iSCSI target, an initiator must be
- authenticated. The initiator may be required by the target to
- produce one or more of the following credentials:
-
- - An iSCSI Initiator Name
-
- - An IP address
-
- - A CHAP, SRP, or Kerberos credential
-
- - Any combination of the above
-
- Most iSCSI targets allow access to only one or two initiators. In
- the ideal discovery scenario, an initiator would send an SLP request
- and receive responses ONLY for targets to which the initiator is
- guaranteed a successful login. To achieve this goal, the iSCSI
- target template contains the following attributes, each of which
- allows a list of values:
-
- 1. auth-name: This attribute contains the list of initiator names
- allowed to access this target, or the value "any", indicating
- that no specific initiator name is required.
-
- 2. auth-addr: This attribute contains the list of host names
- and/or IP addresses that will be allowed access to this target,
- or the value "any", indicating that no specific address or
- host name is required. If a large number of addresses is to
- be allowed (perhaps a subnet), this attribute may contain the
- value "any".
-
-
-
-
-
-
-
-
-Bakke & Hufferd Standards Track [Page 7]
-
-RFC 4018 iSCSI and SLPv2 April 2005
-
-
- 3. auth-cred: This attribute contains a list of "method/identifier"
- credentials that will be allowed access to the target, provided
- they can produce the correct password or other verifier during
- the login process. If no specific credentials are required, the
- value "any" is used.
-
- The list of valid method strings for auth-cred are defined in
- [RFC3720], section 11.1, "AuthMethod". The identifier used after the
- "/" is defined by the specific AuthMethod, also in [RFC3720].
- Examples showing initiator searches based on auth-xxxx attributes are
- shown in the target-specific template section below.
-
- Also note that the auth-xxxx attributes are considered security
- policy information. If these attributes are distributed, IPsec MUST
- be implemented as specified in the Security Implementation section
- below.
-
-4.1.2. Supporting Access by Multiple Identities to the Same Target
-
- If a target is to allow access to multiple host identities, more than
- one combination of auth-xxxx attributes will have to be allowed. In
- some of these cases, it is not possible to express the entire set of
- valid combinations of auth-xxxx attributes within a single registered
- service URL. For example, if a target can be addressed by
-
- auth-name=myhost1 AND auth-cred=CHAP/user1 (identity1)
-
- OR
-
- auth-name-myhost2 AND auth-cred=CHAP/user2 (identity2)
-
- the above cannot be specified in a single registered service URL,
- since (auth-name=myhost1, auth-name=myhost2, auth-cred=CHAP/user1,
- auth-cred=CHAP/user2) would allow either auth-name to be used with
- either auth-cred. This necessitates the ability to register a target
- and address under more than one service URL; one for (identity1) and
- one for (identity2).
-
- Because service URLs must be unique, (identity1) and (identity2) must
- each be registered under a unique service URL. For systems that
- support the configuration of multiple identities to access a target,
- the service URL must contain an additional, opaque string defining
- the identity. This appears after the iSCSI name in the URL string
- and is separated by a "/". Each registered (target-address, target-
- name, initiator-identity) tuple can then register a set of auth-xxxx
- attributes.
-
-
-
-
-
-Bakke & Hufferd Standards Track [Page 8]
-
-RFC 4018 iSCSI and SLPv2 April 2005
-
-
-4.1.3. Using SLP in a Non-multicast Environment
-
- In some networks, the use of multicast for discovery purposes is
- either unavailable or not allowed. These include public or service-
- provider networks that are placed between an iSCSI client and a
- server. These are probably most common between two iSCSI gateways,
- one at a storage service provider site, and one at a customer site.
-
- In these networks, an initiator may allow the addresses of one or
- more SAs to be configured instead of or in addition to its DA
- configuration. The initiator would then make unicast SLP service
- requests directly to these SAs, without the use of multicast to
- discover them first.
-
- This functionality is well within the scope of the current SLP
- protocol. The main consequence for implementors is that an initiator
- configured to make direct unicast requests to an SA will have to add
- this to the SLP API, if it is following the service location API
- defined in [RFC2614].
-
-4.2. Discovering Storage Management Services with SLP
-
- Storage management servers can be built to manage and control access
- to targets in a variety of ways. They can provide extended services
- beyond discovery, which could include storage allocation and
- management. None of these services are defined here; the intent of
- this document is to allow these services to be discovered by both
- clients and servers, in addition to the target discovery already
- being performed.
-
- The following drawing shows an iSCSI client, an iSCSI server, and a
- storage management server. To simplify the drawing, the second IP
- network is not shown but is assumed to exist. The storage management
- server would use its own protocol (smsp) to provide capabilities to
- iSCSI clients and servers; these clients and servers can both use SLP
- to discover the storage management server.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Bakke & Hufferd Standards Track [Page 9]
-
-RFC 4018 iSCSI and SLPv2 April 2005
-
-
- +---------------------------+
- | iSCSI Client |
- | |
- | +-----------+ |
- | | iSCSI | |
- | | initiator | |
- | +-----------+ |
- | |
- +---------------+------+----+ +------------+
- | iSCSI Driver | smsp | UA | | SLP DA |
- +---------------+------+----+ | |
- | TCP/UDP/IP | | (optional) |
- +---------------+------+----+ +------------+
- | |
- | IP Network |
- ------------------------------------------
- | |
- | |
- +---------------+-----------+ +---------------------+
- | TCP/UDP/IP | | TCP/UDP/IP |
- +---------------+------+----+ +---------------------+
- | iSCSI Driver | smsp | UA | | SA | smsp |
- +---------------+------+----+ +---------------------+
- | | | |
- | +--------+ +--------+ | | storage mgmt server |
- | | iSCSI | | iSCSI | | | |
- | | target | | target | | +---------------------+
- | | 1 | | 2 | |
- | +--------+ +--------+ |
- | |
- | iSCSI Server |
- +---------------------------+
-
- Note the difference between the storage management server model and
- the previously defined target discovery model. When target discovery
- was used, the iSCSI Server implemented an SA, to be discovered by the
- initiator's UA. In the storage management server model, the iSCSI
- clients and servers both implement UAs, and the management server
- implements the SA.
-
- A storage management server's URL contains the domain name or IP
- address and TCP or UDP port number. No other information is
- required.
-
- The storage management server constructs a service advertisement of
- the type "service:iscsi:sms" for each of the addresses at which it
- appears. The advertisement contains the URL and a lifetime, along
- with other attributes that are defined in the service template.
-
-
-
-Bakke & Hufferd Standards Track [Page 10]
-
-RFC 4018 iSCSI and SLPv2 April 2005
-
-
- The remainder of the discovery procedure is identical to that used to
- discover iSCSI targets, except that both initiators and targets would
- normally be "clients" of the storage management service.
-
- Targets that support a storage management service implement a UA in
- addition to the SA. A target may alternatively just implement the UA
- and allow the storage management service to advertise its targets
- appropriately by providing an SA and registering the appropriate
- service:iscsi:target registrations on the target's behalf: The target
- device would not have to advertise its own targets. This has no
- impact on the initiator.
-
- This allows the initiators' discovery of targets to be completely
- interoperable regardless of which storage management service is used,
- or whether one is used at all, or whether the target registrations
- are provided directly by the target or by the management service.
-
-4.3. Internationalization Considerations
-
- SLP allows internationalized strings to be registered and retrieved.
- Attributes in the template that are not marked with an 'L' (literal)
- will be registered in a localized manner. An "en" (English)
- localization MUST be registered, and others MAY be registered.
-
- Attributes that include non-ASCII characters will be encoded by using
- UTF-8, as discussed in [RFC3722] and [RFC3491].
-
-5. iSCSI SLP Templates
-
- Three templates are provided: an iSCSI target template, a management
- service template, and an abstract template to encapsulate the two.
-
-5.1. The iSCSI Abstract Service Type Template
-
- This template defines the abstract service "service:iscsi". It is
- used as a top-level service to encapsulate all other iSCSI-related
- services.
-
- Name of submitter: Mark Bakke
- Language of service template: en
- Security Considerations: See section 6.
-
- Template Text:
- -------------------------template begins here-----------------------
- template-type=iscsi
- template-version=1.0
-
- template-description=
-
-
-
-Bakke & Hufferd Standards Track [Page 11]
-
-RFC 4018 iSCSI and SLPv2 April 2005
-
-
- This is an abstract service type. The purpose of the iscsi
- service type is to encompass all of the services used to support
- the iSCSI protocol.
-
- template-url-syntax=
- url-path= ; Depends on the concrete service type.
-
- --------------------------template ends here------------------------
-
-5.2. The iSCSI Target Concrete Service Type Template
-
- This template defines the service "service:iscsi:target". An entity
- containing iSCSI targets that wishes them discovered via SLP would
- register each of them, with each of their addresses, as this service
- type.
-
- Initiators (and perhaps management services) wishing to discover
- targets in this way will generally use one of the following queries:
-
- 1. Find a specific target, given its iSCSI Target Name:
-
- Service: service:iscsi:target
- Scope: initiator-scope-list
- Query: (iscsi-name=iqn.2001-04.com.example:sn.456)
-
- 2. Find all of the iSCSI Target Names that may allow access to a
- given initiator:
-
- Service: service:iscsi:target
- Scope: initiator-scope-list
- Query: (auth-name=iqn.1998-03.com.example:hostid.045A7B)
-
- 3. Find all of the iSCSI Target Names that may allow access to
- any initiator:
-
- Service: service:iscsi:target
- Scope: initiator-scope-list
- Query: (auth-name=any)
-
- 4. Find all of the iSCSI Target Names that may allow access to
- this initiator, or that will allow access to any initiator:
-
- Service: service:iscsi:target
- Scope: initiator-scope-list
- Query: &(auth-name=iqn.1998-03.com.example:hostid.045A7B)
- (auth-name=any)
-
-
-
-
-
-Bakke & Hufferd Standards Track [Page 12]
-
-RFC 4018 iSCSI and SLPv2 April 2005
-
-
- 5. Find all of the iSCSI Target Names that may allow access to
- a given CHAP user name:
-
- Service: service:iscsi:target
- Scope: initiator-scope-list
- Query: (auth-cred=chap/my-user-name)
-
- 6. Find all of the iSCSI Target Names that may allow access to a
- given initiator that supports two IP addresses, a CHAP credential
- and SRP credential, and an initiator name:
-
- Service: service:iscsi:target
- Scope: initiator-scope-list
- Query: &(|(auth-name=iqn.com.example:host47)(auth-name=any)
- |(auth-addr=192.0.2.3)(auth-addr=192.0.2.131)(auth-addr=any)
- |(auth-cred=chap/foo)(auth-cred=srp/my-user-name)
- (auth-cred=any))
-
- 7. Find the iSCSI Target Names from which the given initiator is
- allowed to boot:
-
- Service: service:iscsi:target
- Scope: initiator-scope-list
- Query: (boot-list=iqn.1998-03.com.example:hostid.045A7B)
-
- 8. In addition, a management service may wish to discover all
- targets:
-
- Service: service:iscsi:target
- Scope: management-server-scope-list
- Query: <empty-string>
-
- More details on booting from an iSCSI target are defined in [BOOT].
-
- Name of submitter: Mark Bakke
- Language of service template: en
- Security Considerations: see section 6.
-
- Template Text:
- -------------------------template begins here-----------------------
- template-type=iscsi:target
- template-version=1.0
-
- template-description=
-
- This is a concrete service type. The iscsi:target service type is
- used to register individual target addresses to be discovered
- by others. UAs will generally search for these by including one of
-
-
-
-Bakke & Hufferd Standards Track [Page 13]
-
-RFC 4018 iSCSI and SLPv2 April 2005
-
-
- the following:
-
- - the iSCSI target name
- - iSCSI initiator identifiers (iSCSI name, credential, IP address)
- - the service URL
-
- template-url-syntax=
- url-path = hostport "/" iscsi-name [ "/" identity ]
- hostport = host [ ":" port ]
- host = hostname / hostnumber ; DNS name or IP address
- hostname = *( domainlabel "." ) toplabel
- alphanum = ALPHA / DIGIT
- domainlabel = alphanum / alphanum *[alphanum / "-"] alphanum
- toplabel = ALPHA / ALPHA *[ alphanum / "-" ] alphanum
- hostnumber = ipv4-number / ipv6-addr ; IPv4 or IPv6 address
- ipv4-number = 1*3DIGIT 3("." 1*3DIGIT)
- ipv6-addr = "[" ipv6-number "]"
- ipv6-number = 6( h16 ":" ) ls32
- / "::" 5( h16 ":" ) ls32
- / [ h16 ] "::" 4( h16 ":" ) ls32
- / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32
- / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32
- / [ *3( h16 ":" ) h16 ] "::" h16 ":" ls32
- / [ *4( h16 ":" ) h16 ] "::" ls32
- / [ *5( h16 ":" ) h16 ] "::" h16
- / [ *6( h16 ":" ) h16 ] "::"
- ls32 = ( h16 ":" h16 ) / ipv4-number
- ; least-significant 32 bits of ipv6 address
- h16 = 1*4HEXDIG
- port = 1*DIGIT
- iscsi-name = iscsi-char ; iSCSI target name
- identity = iscsi-char ; optional identity string
- iscsi-char = ALPHA / DIGIT / escaped / ":" / "-" / "."
- ; Intended to allow UTF-8 encoded strings
- escaped = 1*("\" HEXDIG HEXDIG)
- ;
- ; The iscsi-name part of the URL is required and must be the iSCSI
- ; name of the target being registered.
- ; A device representing multiple targets must individually
- ; register each target/address combination with SLP.
- ; The identity part of the URL is optional, and is used to
- ; indicate an identity that is allowed to access this target.
- ;
- ; Example (split into two lines for clarity):
- ; service:iscsi:target://192.0.2.3:3260/
- ; iqn.2001-04.com.example:sn.45678
- ;
- ; IPv6 addresses are also supported; they use the notation
-
-
-
-Bakke & Hufferd Standards Track [Page 14]
-
-RFC 4018 iSCSI and SLPv2 April 2005
-
-
- ; specified above and in [RFC3513], section 2.2
-
- iscsi-name = string
- # The iSCSI Name of this target.
- # This must match the iscsi-name in the url-path.
-
- portal-group = integer
- # The iSCSI portal group tag for this address. Addresses sharing
- # the same iscsi-name and portal-group tag can be used within the
- # same iSCSI session. Portal groups are described in [RFC3720].
-
- transports = string M L
- tcp
- # This is a list of transport protocols that the registered
- # entity supports. iSCSI is currently supported over TCP,
- # but it is anticipated that it could be supported over other
- # transports, such as SCTP, in the future.
- tcp
-
- mgmt-entity = string O
- # The fully qualified domain name, or IP address in dotted-decimal
- # notation, of the management interface of the entity containing
- # this target.
- #
-
- alias = string O
- # The alias string contains a descriptive name of the target.
-
- auth-name = string M X
- # A list of iSCSI Initiator Names that can access this target.
- # Normal iSCSI names will be 80 characters or less; max length
- # is 255.
- # Normally, only one or a few values will be in the list.
- # Using the equivalence search on this will evaluate to "true"
- # if any one of the items in this list matches the query.
- # If this list contains the default name "any", any initiator
- # is allowed to access this target, provided it matches
- # the other auth-xxx attributes.
- #
- # This attribute contains security policy information. If this
- # attribute is distributed via an Attribute Reply message,
- # IPsec MUST be implemented.
-
- auth-addr = string M X
- # A list of initiator IP addresses (or host names) which will
- # be allowed access to this target. If this list contains the
- # default name "any", any IP address is allowed access to this
- # target, provided it matches the other auth-xxx attributes.
-
-
-
-Bakke & Hufferd Standards Track [Page 15]
-
-RFC 4018 iSCSI and SLPv2 April 2005
-
-
- #
- # This attribute contains security policy information. If this
- # attribute is distributed via an Attribute Reply message,
- # IPsec MUST be implemented.
-
- auth-cred = string M X
- # A list of credentials which will be allowed access to the target
- # (provided they can provide the correct password or other
- # authenticator). Entries in this list are of the form
- # "method/identifier", where the currently defined methods are
- # "chap" and "srp", both of which take usernames as their
- # identifiers.
- #
- # This attribute contains security policy information. If this
- # attribute is distributed via an Attribute Reply message,
- # IPsec MUST be implemented.
-
- boot-list = string M O
- # A list of iSCSI Initiator Names that can boot from this target.
- # This list works precisely like the auth-name attribute. A name
- # appearing in this list must either appear in the access-list,
- # or the access-list must contain the initiator name "iscsi".
- # Otherwise, an initiator will be unable to find its boot
- # target. If boot-list contains the name "iscsi", any host can boot
- # from it, but I am not sure if this is useful to anyone. If this
- # attribute is not registered, this target is not "bootable".
- #
- # Note that the LUN the host boots from is not specified here; a
- # host will generally attempt to boot from LUN 0.
- #
- # It is quite possible that other attributes will need to be defined
- # here for booting as well.
- #
- # This attribute contains security policy information. If this
- # attribute is distributed via an Attribute Reply message,
- # IPsec MUST be implemented.
-
- --------------------------template ends here------------------------
-
-5.3. iSCSI Storage Management Service Templates
-
- This template defines the service "service:iscsi:sms". An entity
- supporting one or more iSCSI management service protocols may
- register itself with SLP as this service type. iSCSI clients and
- servers wishing to discover storage management services using SLP
- will usually search for them by the protocol(s) they support:
-
-
-
-
-
-Bakke & Hufferd Standards Track [Page 16]
-
-RFC 4018 iSCSI and SLPv2 April 2005
-
-
- Service: service:iscsi:sms
- Scope: initiator-scope-list
- Query: (protocols=isns)
-
- Name of submitter: Mark Bakke
- Language of service template: en
- Security Considerations: see section 6.
-
- Template Text:
- -------------------------template begins here-----------------------
- template-type=iscsi:sms
- template-version=1.0
-
- template-description=
- This is a concrete service type. The iscsi:sms service type
- provides the capability for entities supporting iSCSI to discover
- appropriate management services.
-
- template-url-syntax=
- url-path = ; The URL of the management service [RFC2608].
-
- protocols = string M
- # The list of protocols supported by this name service. This
- # list may be expanded in the future. There is no default.
- #
- # "isns" - This management service supports the use of the iSNS
- # protocol for access management, health monitoring, and
- # discovery management services. This protocol is defined
- # in [ISNS].
- isns
-
- transports = string M L
- tcp
- # This is a list of transport protocols that the registered
- # entity supports.
- tcp, udp
-
- server-priority = integer
- # The priority a client should give this server, when choosing
- # between multiple servers with the same protocol type.
- # When multiple servers are discovered for a given protocol type,
- # this parameter indicates their relative precedence. Server
- # precedence is protocol-specific; for some protocols, the primary
- # server may have the highest server-priority value, while for
-
-
-
-
-
-
-
-Bakke & Hufferd Standards Track [Page 17]
-
-RFC 4018 iSCSI and SLPv2 April 2005
-
-
- # others it may have the lowest. For example, with iSNS, the primary
- # server has the lowest value (value 0).
-
- --------------------------template ends here------------------------
-
-6. Security Considerations
-
- The SLPv2 security model as specified in [RFC2608] does not provide
- confidentiality but does provide an authentication mechanism for UAs
- to ensure that service advertisements only come from trusted SAs,
- with the exception that it does not provide a mechanism to
- authenticate "zero-result responses". See [RFC3723] for a discussion
- of the SLPv2 [RFC2608] security model.
-
- Once a target or management server is discovered, authentication and
- authorization are handled by the iSCSI protocol, or by the management
- server's protocol. It is the responsibility of the providers of
- these services to ensure that an inappropriately advertised or
- discovered service does not compromise their security.
-
- When no security is used for SLPv2, there is a risk of distribution
- of false discovery information. The primary countermeasure for this
- risk is authentication. When this risk is a significant concern,
- IPsec SAs and iSCSI in-band authentication SHOULD be used for iSCSI
- traffic subject to this risk to ensure that iSCSI traffic only flows
- between endpoints that have participated in IKE authentication and
- iSCSI in-band authentication. For example, if an attacker
- distributes discovery information falsely claiming that it is an
- iSCSI target, it will lack the secret information necessary to
- complete IKE authentication or iSCSI in-band authentication
- successfully and therefore will be prevented from falsely sending or
- receiving iSCSI traffic.
-
- A risk remains of a denial of service attack based on repeated use of
- false discovery information that will cause initiation of IKE
- negotiation. The countermeasures for this are administrative
- configuration of each iSCSI Target to limit the peers it is willing
- to communicate with (i.e., by IP address range and/or DNS domain),
- and maintenance of a negative authentication cache to avoid
- repeatedly contacting an iSCSI Target that fails to authenticate.
- These three measures (i.e., IP address range limits, DNS domain
- limits, negative authentication cache) MUST be implemented.
-
- The auth-name, auth-addr, auth-cred, and boot-list attributes
- comprise security policy information. When these are distributed,
- IPsec MUST be implemented.
-
-
-
-
-
-Bakke & Hufferd Standards Track [Page 18]
-
-RFC 4018 iSCSI and SLPv2 April 2005
-
-
-6.1. Security Implementation
-
- Security for SLPv2 in an IP storage environment is specified in
- [RFC3723]. IPsec is mandatory-to-implement for IPS clients and
- servers. Thus, all IP storage clients, including those invoking SLP,
- can be assumed to support IPsec. SLP servers, however, cannot be
- assumed to implement IPsec, since there is no such requirement in
- standard SLP. In particular, SLP Directory Agents (DA) may be
- running on machines other than those running the IPS protocols.
-
- IPsec SHOULD be implemented for SLPv2 as specified in [RFC3723]; this
- includes ESP with a non-null transform to provide both authentication
- and confidentiality.
-
- When SLPv2 can be used to distribute auth-name, auth-addr, auth-cred,
- and boot-list information (see section 5.2 above), IPsec MUST be
- implemented, as these items are considered sensitive security policy
- information. If IPsec is not implemented, auth-name, auth-addr,
- auth-cred, and boot-list information MUST NOT be distributed via
- SLPv2 and MUST NOT be used if discovered via SLPv2.
-
- Because the IP storage services have their own authentication
- capabilities when located, SLPv2 authentication is OPTIONAL to
- implement and use (as discussed in more detail in [RFC3723]).
-
-7. IANA Considerations
-
- This document describes three SLP Templates. They have been reviewed
- and approved by the IESG and registered in the IANA's "SVRLOC
- Templates" registry. This process is described in the IANA
- Considerations section of [RFC2609].
-
-8. Summary
-
- This document describes how SLP can be used by iSCSI initiators to
- find iSCSI targets and storage management servers. Service type
- templates for iSCSI targets and storage management servers are
- presented.
-
-9. Normative References
-
- [RFC2608] Guttman, E., Perkins, C., Veizades, J., and M. Day,
- "Service Location Protocol, Version 2", RFC 2608, June
- 1999.
-
- [RFC2609] Guttman, E., Perkins, C., and J. Kempf, "Service
- Templates and Service: Schemes", RFC 2609, June 1999.
-
-
-
-
-Bakke & Hufferd Standards Track [Page 19]
-
-RFC 4018 iSCSI and SLPv2 April 2005
-
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC3491] Hoffman, P. and M. Blanchet, "Nameprep: A Stringprep
- Profile for Internationalized Domain Names (IDN)", RFC
- 3491, March 2003.
-
- [RFC3513] Hinden, R. and S. Deering, "Internet Protocol Version 6
- (IPv6) Addressing Architecture", RFC 3513, April 2003.
-
- [RFC3720] Satran, J., Meth, K., Sapuntzakis, C., Chadalapaka, M.,
- and E. Zeidner, "Internet Small Computer Systems
- Interface (iSCSI)", RFC 3720, April 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.
-
-10. Informative References
-
- [RFC2614] Kempf, J. and E. Guttman, "An API for Service Location",
- RFC 2614, June 1999.
-
- [SAM2] ANSI T10. "SCSI Architectural Model 2", March 2000.
-
- [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.
-
- [ISNS] Tseng, J., Gibbons, K., Travostino, F., Du Laney, C. and
- J. Souza, "Internet Storage Name Service", Work in
- Progress, February 2004.
-
- [BOOT] Sarkar, P., Missimer, D. and C. Sapuntzakis, "A Standard
- for Bootstrapping Clients using the iSCSI Protocol", Work
- in Progress, March 2004.
-
- [RFC3105] Kempf, J. and G. Montenegro, "Finding an RSIP Server with
- SLP", RFC 3105, October 2001.
-
-
-
-
-
-
-
-
-
-Bakke & Hufferd Standards Track [Page 20]
-
-RFC 4018 iSCSI and SLPv2 April 2005
-
-
-11. Acknowledgements
-
- This document was produced by the iSCSI Naming and Discovery team,
- including Joe Czap, Jim Hafner, John Hufferd, and Kaladhar Voruganti
- (IBM), Howard Hall (Pirus), Jack Harwood (EMC), Yaron Klein (Sanrad),
- Marjorie Krueger (HP), Lawrence Lamers (San Valley), Todd Sperry
- (Adaptec), and Joshua Tseng (Nishan). Thanks also to Julian Satran
- (IBM) for suggesting the use of SLP for iSCSI discovery, and to Matt
- Peterson (Caldera) and James Kempf (Sun) for reviewing the document
- from an SLP perspective.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Bakke & Hufferd Standards Track [Page 21]
-
-RFC 4018 iSCSI and SLPv2 April 2005
-
-
-Authors' Addresses
-
- Mark Bakke
- Cisco Systems, Inc.
- 7900 International Drive, Suite 400
- Bloomington, MN
- USA 55425
-
- EMail: mbakke@cisco.com
-
-
- Kaladhar Voruganti
- IBM Almaden Research Center
- 650 Harry Road
- San Jose, CA 95120
-
- EMail: kaladhar@us.ibm.com
-
-
- John L. Hufferd
- IBM Storage Systems Group
- 5600 Cottle Road
- San Jose, CA 95193
-
- Phone: +1 408 997-6136
- EMail: jlhufferd@comcast.net
-
-
- Marjorie Krueger
- Hewlett-Packard Corporation
- 8000 Foothills Blvd
- Roseville, CA 95747-5668, USA
-
- Phone: +1 916 785-2656
- EMail: marjorie_krueger@hp.com
-
-
- Todd Sperry
- Adaptec, Inc.
- 691 South Milpitas Boulevard
- Milpitas, Ca. 95035
-
- Phone: +1 408 957-4980
- EMail: todd_sperry@adaptec.com
-
-
-
-
-
-
-
-Bakke & Hufferd Standards Track [Page 22]
-
-RFC 4018 iSCSI and SLPv2 April 2005
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2005).
-
- This document is subject to the rights, licenses and restrictions
- contained in BCP 78, and except as set forth therein, the authors
- retain all their rights.
-
- This document and the information contained herein are provided on an
- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Intellectual Property
-
- The IETF takes no position regarding the validity or scope of any
- Intellectual Property Rights or other rights that might be claimed to
- pertain to the implementation or use of the technology described in
- this document or the extent to which any license under such rights
- might or might not be available; nor does it represent that it has
- made any independent effort to identify any such rights. Information
- on the procedures with respect to rights in RFC documents can be
- found in BCP 78 and BCP 79.
-
- Copies of IPR disclosures made to the IETF Secretariat and any
- assurances of licenses to be made available, or the result of an
- attempt made to obtain a general license or permission for the use of
- such proprietary rights by implementers or users of this
- specification can be obtained from the IETF on-line IPR repository at
- http://www.ietf.org/ipr.
-
- The IETF invites any interested party to bring to its attention any
- copyrights, patents or patent applications, or other proprietary
- rights that may cover technology that may be required to implement
- this standard. Please address the information to the IETF at ietf-
- ipr@ietf.org.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-Bakke & Hufferd Standards Track [Page 23]
-
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/utils/open-isns/doc/rfc4171.txt open-iscsi-2.0-872-rc4-bnx2i.work/utils/open-isns/doc/rfc4171.txt
--- open-iscsi-2.0-872-rc4-bnx2i/utils/open-isns/doc/rfc4171.txt 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/utils/open-isns/doc/rfc4171.txt 1969-12-31 18:00:00.000000000 -0600
@@ -1,6891 +0,0 @@
-
-
-
-
-
-
-Network Working Group J. Tseng
-Request for Comments: 4171 Riverbed Technology
-Category: Standards Track K. Gibbons
- McDATA Corporation
- F. Travostino
- Nortel
- C. Du Laney
- Rincon Research Corporation
- J. Souza
- Microsoft
- September 2005
-
-
- Internet Storage Name Service (iSNS)
-
-Status of This Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2005).
-
-Abstract
-
- This document specifies the Internet Storage Name Service (iSNS)
- protocol, used for interaction between iSNS servers and iSNS clients,
- which facilitates automated discovery, management, and configuration
- of iSCSI and Fibre Channel devices (using iFCP gateways) on a TCP/IP
- network. iSNS provides intelligent storage discovery and management
- services comparable to those found in Fibre Channel networks,
- allowing a commodity IP network to function in a capacity similar to
- that of a storage area network. iSNS facilitates a seamless
- integration of IP and Fibre Channel networks due to its ability to
- emulate Fibre Channel fabric services and to manage both iSCSI and
- Fibre Channel devices. iSNS thereby provides value in any storage
- network comprised of iSCSI devices, Fibre Channel devices (using iFCP
- gateways), or any combination thereof.
-
-
-
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 1]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-Table of Contents
-
- 1. Introduction................................................... 6
- 1.1. Conventions Used in This Document........................ 6
- 1.2. Purpose of This Document................................. 6
- 2. iSNS Overview.................................................. 6
- 2.1. iSNS Architectural Components ........................... 7
- 2.1.1. iSNS Protocol (iSNSP) ........................... 7
- 2.1.2. iSNS Client...................................... 7
- 2.1.3. iSNS Server...................................... 7
- 2.1.4. iSNS Database ................................... 7
- 2.1.5. iSCSI............................................ 7
- 2.1.6. iFCP............................................. 7
- 2.2. iSNS Functional Overview................................. 8
- 2.2.1. Name Registration Service........................ 8
- 2.2.2. Discovery Domain and Login Control Service....... 8
- 2.2.3. State Change Notification Service............... 10
- 2.2.4. Open Mapping between
- Fibre Channel and iSCSI Devices................. 11
- 2.3. iSNS Usage Model........................................ 11
- 2.3.1. iSCSI Initiator................................. 12
- 2.3.2. iSCSI Target.................................... 12
- 2.3.3. iSCSI-FC Gateway................................ 12
- 2.3.4. iFCP Gateway.................................... 12
- 2.3.5. Management Station.............................. 12
- 2.4. Administratively Controlled iSNS Settings............... 13
- 2.5. iSNS Server Discovery .................................. 14
- 2.5.1. Service Location Protocol (SLP)................. 14
- 2.5.2. Dynamic Host Configuration Protocol (DHCP)...... 14
- 2.5.3. iSNS Heartbeat Message.......................... 14
- 2.6. iSNS and Network Address Translation (NAT).............. 14
- 2.7. Transfer of iSNS Database Records between iSNS Servers.. 15
- 2.8. Backup iSNS Servers..................................... 17
- 2.9. Transport Protocols..................................... 19
- 2.9.1. Use of TCP for iSNS Communication............... 19
- 2.9.2. Use of UDP for iSNS Communication............... 20
- 2.9.3. iSNS Multicast and Broadcast Messages........... 20
- 2.10. Simple Network Management Protocol (SNMP) Requirements.. 21
- 3. iSNS Object Model............................................. 21
- 3.1. Network Entity Object .................................. 22
- 3.2. Portal Object .......................................... 22
- 3.3. Storage Node Object..................................... 22
- 3.4. Portal Group Object..................................... 23
- 3.5. FC Device Object........................................ 24
- 3.6. Discovery Domain Object................................. 24
- 3.7. Discovery Domain Set Object............................. 24
- 3.8. iSNS Database Model..................................... 24
- 4. iSNS Implementation Requirements.............................. 25
-
-
-
-Tseng, et al. Standards Track [Page 2]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- 4.1. iSCSI Requirements...................................... 25
- 4.1.1. Required Attributes for Support of iSCSI........ 26
- 4.1.2. Examples: iSCSI Object Model Diagrams........... 28
- 4.1.3. Required Commands and
- Response Messages for Support of iSCSI.......... 30
- 4.2. iFCP Requirements....................................... 31
- 4.2.1. Required Attributes for Support of iFCP......... 31
- 4.2.2. Example: iFCP Object Model Diagram.............. 32
- 4.2.3. Required Commands and
- Response Messages for Support of iFCP........... 34
- 5. iSNSP Message Format.......................................... 35
- 5.1. iSNSP PDU Header........................................ 35
- 5.1.1. iSNSP Version................................... 36
- 5.1.2. iSNSP Function ID............................... 36
- 5.1.3. iSNSP PDU Length................................ 36
- 5.1.4. iSNSP Flags..................................... 36
- 5.1.5. iSNSP Transaction ID............................ 36
- 5.1.6. iSNSP Sequence ID............................... 37
- 5.2. iSNSP Message Segmentation and Reassembly............... 37
- 5.3. iSNSP PDU Payload....................................... 37
- 5.3.1. Attribute Value 4-Byte Alignment................ 38
- 5.4. iSNSP Response Status Codes............................. 39
- 5.5. Authentication for iSNS Multicast and Broadcast Messages 39
- 5.6. Registration and Query Messages......................... 41
- 5.6.1. Source Attribute................................ 42
- 5.6.2. Message Key Attributes.......................... 42
- 5.6.3. Delimiter Attribute............................. 42
- 5.6.4. Operating Attributes............................ 43
- 5.6.5. Registration and Query Request Message Types ... 44
- 5.7. Response Messages....................................... 66
- 5.7.1. Status Code..................................... 66
- 5.7.2. Message Key Attributes in Response.............. 66
- 5.7.3. Delimiter Attribute in Response................. 67
- 5.7.4. Operating Attributes in Response................ 67
- 5.7.5. Registration and Query Response Message Type.... 67
- 5.8. Vendor-Specific Messages................................ 72
- 6. iSNS Attributes............................................... 73
- 6.1. iSNS Attribute Summary.................................. 73
- 6.2. Entity Identifier-Keyed Attributes...................... 76
- 6.2.1. Entity Identifier (EID)......................... 76
- 6.2.2. Entity Protocol................................. 76
- 6.2.3. Management IP Address .......................... 77
- 6.2.4. Entity Registration Timestamp .................. 77
- 6.2.5. Protocol Version Range.......................... 77
- 6.2.6. Registration Period............................. 78
- 6.2.7. Entity Index.................................... 78
- 6.2.8. Entity Next Index............................... 79
- 6.2.9. Entity ISAKMP Phase-1 Proposals................. 79
-
-
-
-Tseng, et al. Standards Track [Page 3]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- 6.2.10. Entity Certificate.............................. 79
- 6.3. Portal-Keyed Attributes................................. 80
- 6.3.1. Portal IP Address............................... 80
- 6.3.2. Portal TCP/UDP Port............................. 80
- 6.3.3. Portal Symbolic Name............................ 80
- 6.3.4. Entity Status Inquiry Interval.................. 81
- 6.3.5. ESI Port........................................ 82
- 6.3.6. Portal Index.................................... 82
- 6.3.7. SCN Port........................................ 82
- 6.3.8. Portal Next Index............................... 83
- 6.3.9. Portal Security Bitmap.......................... 83
- 6.3.10. Portal ISAKMP Phase-1 Proposals................. 84
- 6.3.11. Portal ISAKMP Phase-2 Proposals................. 84
- 6.3.12. Portal Certificate.............................. 84
- 6.4. iSCSI Node-Keyed Attributes............................. 84
- 6.4.1. iSCSI Name...................................... 85
- 6.4.2. iSCSI Node Type................................. 85
- 6.4.3. iSCSI Node Alias................................ 86
- 6.4.4. iSCSI Node SCN Bitmap .......................... 86
- 6.4.5. iSCSI Node Index................................ 87
- 6.4.6. WWNN Token...................................... 87
- 6.4.7. iSCSI Node Next Index .......................... 89
- 6.4.8. iSCSI AuthMethod................................ 89
- 6.5. Portal Group (PG) Object-Keyed Attributes............... 89
- 6.5.1. Portal Group iSCSI Name......................... 90
- 6.5.2. PG Portal IP Addr............................... 90
- 6.5.3. PG Portal TCP/UDP Port.......................... 90
- 6.5.4. Portal Group Tag (PGT).......................... 90
- 6.5.5. Portal Group Index.............................. 90
- 6.5.6. Portal Group Next Index......................... 91
- 6.6. FC Port Name-Keyed Attributes .......................... 91
- 6.6.1. FC Port Name (WWPN)............................. 91
- 6.6.2. Port ID (FC_ID)................................. 91
- 6.6.3. FC Port Type.................................... 92
- 6.6.4. Symbolic Port Name.............................. 92
- 6.6.5. Fabric Port Name (FWWN)......................... 92
- 6.6.6. Hard Address.................................... 92
- 6.6.7. Port IP Address................................. 92
- 6.6.8. Class of Service (COS).......................... 93
- 6.6.9. FC-4 Types...................................... 93
- 6.6.10. FC-4 Descriptor................................. 93
- 6.6.11. FC-4 Features .................................. 93
- 6.6.12. iFCP SCN Bitmap................................. 93
- 6.6.13. Port Role....................................... 94
- 6.6.14. Permanent Port Name (PPN)....................... 95
- 6.7. Node-Keyed Attributes .................................. 95
- 6.7.1. FC Node Name (WWNN)............................. 95
- 6.7.2. Symbolic Node Name.............................. 95
-
-
-
-Tseng, et al. Standards Track [Page 4]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- 6.7.3. Node IP Address................................. 95
- 6.7.4. Node IPA........................................ 96
- 6.7.5. Proxy iSCSI Name................................ 96
- 6.8. Other Attributes........................................ 96
- 6.8.1. FC-4 Type Code.................................. 96
- 6.8.2. iFCP Switch Name................................ 96
- 6.8.3. iFCP Transparent Mode Commands.................. 97
- 6.9. iSNS Server-Specific Attributes......................... 97
- 6.9.1. iSNS Server Vendor OUI.......................... 98
- 6.10. Vendor-Specific Attributes.............................. 98
- 6.10.1. Vendor-Specific Server Attributes............... 98
- 6.10.2. Vendor-Specific Entity Attributes............... 98
- 6.10.3. Vendor-Specific Portal Attributes............... 99
- 6.10.4. Vendor-Specific iSCSI Node Attributes........... 99
- 6.10.5. Vendor-Specific FC Port Name Attributes......... 99
- 6.10.6. Vendor-Specific FC Node Name Attributes......... 99
- 6.10.7. Vendor-Specific Discovery Domain Attributes..... 99
- 6.10.8. Vendor-Specific Discovery Domain Set Attributes. 99
- 6.10.9. Other Vendor-Specific Attributes................ 99
- 6.11. Discovery Domain Registration Attributes............... 100
- 6.11.1. DD Set ID Keyed Attributes..................... 100
- 6.11.2. DD ID Keyed Attributes......................... 101
- 7. Security Considerations...................................... 103
- 7.1. iSNS Security Threat Analysis ......................... 103
- 7.2. iSNS Security Implementation and Usage Requirements.... 104
- 7.3. Discovering Security Requirements of Peer Devices...... 105
- 7.4. Configuring Security Policies of iFCP/iSCSI Devices.... 106
- 7.5. Resource Issues........................................ 107
- 7.6. iSNS Interaction with IKE and IPSec.................... 107
- 8. IANA Considerations.......................................... 107
- 8.1. Registry of Block Storage Protocols.................... 107
- 8.2. Registry of Standard iSNS Attributes .................. 108
- 8.3. Block Structure Descriptor (BSD) Registry.............. 108
- 9. Normative References......................................... 109
- 10. Informative References....................................... 110
- Appendix A: iSNS Examples........................................ 112
- A.1. iSCSI Initialization Example........................... 112
- A.1.1. Simple iSCSI Target Registration............... 112
- A.1.2. Target Registration and DD Configuration....... 114
- A.1.3. Initiator Registration and Target Discovery.... 117
- Acknowledgements................................................. 121
-
-
-
-
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 5]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-1. Introduction
-
-1.1. Conventions Used in This Document
-
- "iSNS" refers to the storage network model and associated services
- covered in the text of this document.
-
- 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 [RFC2119].
-
- All frame formats are in big endian network byte order.
-
- All unused fields and bitmaps, including those that are RESERVED,
- SHOULD be set to zero when sending and ignored when receiving.
-
-1.2. Purpose of This Document
-
- This is a standards track document containing normative text
- specifying the iSNS Protocol, used by iSCSI and iFCP devices to
- communicate with the iSNS server. This document focuses on the
- interaction between iSNS servers and iSNS clients; interactions among
- multiple authoritative primary iSNS servers are a potential topic for
- future work.
-
-2. iSNS Overview
-
- iSNS facilitates scalable configuration and management of iSCSI and
- Fibre Channel (FCP) storage devices in an IP network by providing a
- set of services comparable to that available in Fibre Channel
- networks. iSNS thus allows a commodity IP network to function at a
- level of intelligence comparable to a Fibre Channel fabric. iSNS
- allows the administrator to go beyond a simple device-by-device
- management model, where each storage device is manually and
- individually configured with its own list of known initiators and
- targets. Using the iSNS, each storage device subordinates its
- discovery and management responsibilities to the iSNS server. The
- iSNS server thereby serves as the consolidated configuration point
- through which management stations can configure and manage the entire
- storage network, including both iSCSI and Fibre Channel devices.
-
- iSNS can be implemented to support iSCSI and/or iFCP protocols as
- needed; an iSNS implementation MAY provide support for one or both of
- these protocols as desired by the implementor. Implementation
- requirements within each of these protocols are further discussed in
- Section 5. Use of iSNS is OPTIONAL for iSCSI and REQUIRED for iFCP.
-
-
-
-
-
-Tseng, et al. Standards Track [Page 6]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-2.1. iSNS Architectural Components
-
-2.1.1. iSNS Protocol (iSNSP)
-
- The iSNS Protocol (iSNSP) is a flexible and lightweight protocol that
- specifies how iSNS clients and servers communicate. It is suitable
- for various platforms, including switches and targets as well as
- server hosts.
-
-2.1.2. iSNS Client
-
- iSNS clients initiate transactions with iSNS servers using the iSNSP.
- iSNS clients are processes that are co-resident in the storage
- device, and that can register device attribute information, download
- information about other registered clients in a common Discovery
- Domain (DD), and receive asynchronous notification of events that
- occur in their DD(s). Management stations are a special type of iSNS
- client that have access to all DDs stored in the iSNS.
-
-2.1.3. iSNS Server
-
- iSNS servers respond to iSNS protocol queries and requests, and
- initiate iSNS protocol State Change Notifications. Properly
- authenticated information submitted by a registration request is
- stored in an iSNS database.
-
-2.1.4. iSNS Database
-
- The iSNS database is the information repository for the iSNS
- server(s). It maintains information about iSNS client attributes. A
- directory-enabled implementation of iSNS may store client attributes
- in an LDAP directory infrastructure.
-
-2.1.5. iSCSI
-
- iSCSI (Internet SCSI) is an encapsulation of SCSI for a new
- generation of storage devices interconnected with TCP/IP [iSCSI].
-
-2.1.6. iFCP
-
- iFCP (Internet FCP) is a gateway-to-gateway protocol designed to
- interconnect existing Fibre Channel and SCSI devices using TCP/IP.
- iFCP maps the existing FCP standard and associated Fibre Channel
- services to TCP/IP [iFCP].
-
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 7]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-2.2. iSNS Functional Overview
-
- There are four main functions of the iSNS:
-
- 1) A Name Service Providing Storage Resource Discovery
-
- 2) Discovery Domain (DD) and Login Control Service
-
- 3) State Change Notification Service
-
- 4) Open Mapping of Fibre Channel and iSCSI Devices
-
-2.2.1. Name Registration Service
-
- The iSNS provides a registration function to allow all entities in a
- storage network to register and query the iSNS database. Both
- targets and initiators can register in the iSNS database, as well as
- query for information about other initiators and targets. This
- allows, for example, a client initiator to obtain information about
- target devices from the iSNS server. This service is modeled on the
- Fibre Channel Generic Services Name Server described in FC-GS-4, with
- extensions, operating within the context of an IP network.
-
- The naming registration service also provides the ability to obtain a
- network-unique Domain ID for iFCP gateways when one is required.
-
-2.2.2. Discovery Domain and Login Control Service
-
- The Discovery Domain (DD) Service facilitates the partitioning of
- Storage Nodes into more manageable groupings for administrative and
- login control purposes. It allows the administrator to limit the
- login process of each host to the more appropriate subset of targets
- registered in the iSNS. This is particularly important for reducing
- the number of unnecessary logins (iSCSI logins or Fibre Channel Port
- Logins), and for limiting the amount of time that the host spends
- initializing login relationships as the size of the storage network
- scales up. Storage Nodes must be in at least one common enabled DD
- in order to obtain information about each other. Devices can be
- members of multiple DDs simultaneously.
-
- Login Control allows targets to delegate their access
- control/authorization policies to the iSNS server. This is
- consistent with the goal of centralizing management of those storage
- devices using the iSNS server. The target node or device downloads
- the list of authorized initiators from the iSNS. Each node or device
- is uniquely identified by an iSCSI Name or FC Port Name. Only
-
-
-
-
-
-Tseng, et al. Standards Track [Page 8]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- initiators that match the required identification and authorization
- provided by the iSNS will be allowed access by that target Node
- during session establishment.
-
- Placing Portals of a Network Entity into Discovery Domains allows
- administrators to indicate the preferred IP Portal interface through
- which storage traffic should access specific Storage Nodes of that
- Network Entity. If no Portals of a Network Entity have been placed
- into a DD, then queries scoped to that DD SHALL report all Portals of
- that Network Entity. If one or more Portals of a Network Entity have
- been placed into a DD, then queries scoped to that DD SHALL report
- only those Portals that have been explicitly placed in the DD.
-
- DDs can be managed offline through a separate management workstation
- using the iSNSP or SNMP. If the target opts to use the Login Control
- feature of the iSNS, the target delegates management of access
- control policy (i.e., the list of initiators allowed to log in to
- that target) to the management workstations that are managing the
- configuration in the iSNS database.
-
- If administratively authorized, a target can upload its own Login
- Control list. This is accomplished using the DDReg message and
- listing the iSCSI name of each initiator to be registered in the
- target's DD.
-
- An implementation MAY decide that newly registered devices that have
- not explicitly been placed into a DD by the management station will
- be placed into a "default DD" contained in a "default DDS" whose
- initial DD Set Status value is "enabled". This makes them visible to
- other devices in the default DD. Other implementations MAY decide
- that they are registered with no DD, making them inaccessible to
- source-scoped iSNSP messages.
-
- The iSNS server uses the Source Attribute of each iSNSP message to
- determine the originator of the request and to scope the operation to
- a set of Discovery Domains. In addition, the Node Type (specified in
- the iFCP or iSCSI Node Type bitmap field) may also be used to
- determine authorization for the specified iSNS operation. For
- example, only Control Nodes are authorized to create or delete
- discovery domains.
-
- Valid and active Discovery Domains (DDs) belong to at least one
- active Discovery Domain Set (DDS). Discovery Domains that do not
- belong to an activated DDS are not enabled. The iSNS server MUST
- maintain the state of DD membership for all Storage Nodes, even for
- those that have been deregistered. DD membership is persistent
- regardless of whether a Storage Node is actively registered in the
- iSNS database.
-
-
-
-Tseng, et al. Standards Track [Page 9]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-2.2.3. State Change Notification Service
-
- The State Change Notification (SCN) service allows the iSNS Server to
- issue notifications about network events that affect the operational
- state of Storage Nodes. The iSNS client may register for
- notifications on behalf of its Storage Nodes for notification of
- events detected by the iSNS Server. SCNs notify iSNS clients of
- explicit or implicit changes to the iSNS database; they do not
- necessarily indicate the state of connectivity to peer storage
- devices in the network. The response of a storage device to receipt
- of an SCN is implementation-specific; the policy for responding to
- SCNs is outside of the scope of this document.
-
- There are two types of SCN registrations: regular registrations and
- management registrations. Management registrations result in
- management SCNs, whereas regular registrations result in regular
- SCNs. The type of registration and SCN message is indicated in the
- SCN bitmap (see Sections 6.4.4 and 6.6.12).
-
- A regular SCN registration indicates that the Discovery Domain
- Service SHALL be used to control the distribution of SCN messages.
- Receipt of regular SCNs is limited to the discovery domains in which
- the SCN-triggering event takes place. Regular SCNs do not contain
- information about discovery domains.
-
- A management SCN registration can only by requested by Control Nodes.
- Management SCNs resulting from management registrations are not bound
- by the Discovery Domain service. Authorization to request management
- SCN registrations may be administratively controlled.
-
- The iSNS server SHOULD be implemented with hardware and software
- resources sufficient to support the expected number of iSNS clients.
- However, if resources are unexpectedly exhausted, then the iSNS
- server MAY refuse SCN service by returning an SCN Registration
- Rejected (Status Code 17). The rejection might occur in situations
- where the network size or current number of SCN registrations has
- passed an implementation-specific threshold. A client not allowed to
- register for SCNs may decide to monitor its sessions with other
- storage devices directly.
-
-
- The specific notification mechanism by which the iSNS server learns
- of the events that trigger SCNs is implementation-specific, but can
- include examples such as explicit notification messages from an iSNS
- client to the iSNS server, or a hardware interrupt to a switch-hosted
- iSNS server as a result of link failure.
-
-
-
-
-
-Tseng, et al. Standards Track [Page 10]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-2.2.4. Open Mapping between Fibre Channel and iSCSI Devices
-
- The iSNS database stores naming and discovery information about both
- Fibre Channel and iSCSI devices. This allows the iSNS server to
- store mappings of a Fibre Channel device to a proxy iSCSI device
- "image" in the IP network. Similarly, mappings of an iSCSI device to
- a "proxy WWN" can be stored under the WWNN Token field for that iSCSI
- device.
-
- Furthermore, through use of iSCSI-FC gateways, Fibre Channel-aware
- management stations can interact with the iSNS server to retrieve
- information about Fibre Channel devices, and use this information to
- manage Fibre Channel and iSCSI devices. This allows management
- functions such as Discovery Domains and State Change Notifications to
- be applied seamlessly to both iSCSI and Fibre Channel devices,
- facilitating integration of IP networks with Fibre Channel devices
- and fabrics.
-
- Note that Fibre Channel attributes are stored as iFCP attributes, and
- that the ability to store this information in the iSNS server is
- useful even if the iFCP protocol is not implemented. In particular,
- tag 101 can be used to store a "Proxy iSCSI Name" for Fibre Channel
- devices registered in the iSNS server. This field is used to
- associate the FC device with an iSCSI registration entry that is used
- for the Fibre Channel device to communicate with iSCSI devices in the
- IP network. Conversely, tag 37 (see Section 6.1) contains a WWNN
- Token field, which can be used to store an FC Node Name (WWNN) value
- used by iSCSI-FC gateways to represent an iSCSI device in the Fibre
- Channel domain.
-
- By storing the mapping between Fibre Channel and iSCSI devices in the
- iSNS server, this information becomes open to any authorized iSNS
- client wishing to retrieve and use this information. In many cases,
- this provides advantages over storing the information internally
- within an iSCSI-FC gateway, where the mapping is inaccessible to
- other devices except by proprietary mechanisms.
-
-2.3. iSNS Usage Model
-
- The following is a high-level description of how each type of device
- in a storage network can utilize iSNS. Each type of device interacts
- with the iSNS server as an iSNS client and must register itself in
- the iSNS database in order to access services provided by the iSNS.
-
-
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 11]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-2.3.1. iSCSI Initiator
-
- An iSCSI initiator will query the iSNS server to discover the
- presence and location of iSCSI target devices. It may also request
- state change notifications (SCNs) so that it can be notified of new
- targets that appear on the network after the initial bootup and
- discovery. SCNs can also inform the iSCSI initiator of targets that
- have been removed from or no longer available in the storage network,
- so that incomplete storage sessions can be gracefully terminated and
- resources for non-existent targets can be reallocated.
-
-2.3.2. iSCSI Target
-
- An iSCSI target allows itself to be discovered by iSCSI initiators by
- registering its presence in the iSNS server. It may also register
- for SCNs in order to detect the addition or removal of initiators for
- resource allocation purposes. The iSCSI target device may also
- register for Entity Status Inquiry (ESI) messages, which allow the
- iSNS to monitor the target device's availability in the storage
- network.
-
-2.3.3. iSCSI-FC Gateway
-
- An iSCSI-FC gateway bridges devices in a Fibre Channel network to an
- iSCSI/IP network. It may use the iSNS server to store FC device
- attributes discovered in the FC name server, as well as mappings of
- FC device identifiers to iSCSI device identifiers. iSNS has the
- capability to store all attributes of both iSCSI and Fibre Channel
- devices; iSCSI devices are managed through direct interaction using
- iSNS, while FC devices can be indirectly managed through iSNS
- interactions with the iSCSI-FC gateway. This allows both iSCSI and
- Fibre Channel devices to be managed in a seamless management
- framework.
-
-2.3.4. iFCP Gateway
-
- An iFCP gateway uses iSNS to emulate the services provided by a Fibre
- Channel name server for FC devices in its gateway region. iSNS
- provides basic discovery and zoning configuration information to be
- enforced by the iFCP gateway. When queried, iSNS returns information
- on the N_Port network address used to establish iFCP sessions between
- FC devices supported by iFCP gateways.
-
-2.3.5. Management Station
-
- A management station uses iSNS to monitor storage devices and to
- enable or disable storage sessions by configuring discovery domains.
- A management station usually interacts with the iSNS server as a
-
-
-
-Tseng, et al. Standards Track [Page 12]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- Control Node endowed with access to all iSNS database records and
- with special privileges to configure discovery domains. Through
- manipulation of discovery domains, the management station controls
- the scope of device discovery for iSNS clients querying the iSNS
- server.
-
-2.4. Administratively Controlled iSNS Settings
-
- Some important operational settings for the iSNS server are
- configured using administrative means, such as a configuration file,
- a console port, an SNMP, or another implementation-specific method.
- These administratively-controlled settings cannot be configured using
- the iSNS Protocol, and therefore the iSNS server implementation MUST
- provide for such an administrative control interface.
-
- The following is a list of parameters that are administratively
- controlled for the iSNS server. In the absence of alternative
- settings provided by the administrator, the following specified
- default settings MUST be used.
-
- Setting Default Setting
- ------- ---------------
- ESI Non-Response Threshold 3 (see 5.6.5.13)
- Management SCNs (Control Nodes only) enabled (see 5.6.5.8)
- Default DD/DDS disabled
- DD/DDS Modification
- - Control Node enabled
- - iSCSI Target Node Type disabled
- - iSCSI Initiator Node Type disabled
- - iFCP Target Port Role disabled
- - iFCP Initiator Port Role disabled
- Authorized Control Nodes N/A
-
- ESI Non-Response Threshold: determines the number of ESI messages
- sent without receiving a response before the network
- entity is deregistered from the iSNS database.
-
- Management SCN for Control Node: determines whether a registered
- Control Node is permitted to register to receive
- Management SCNs.
-
- Default DD/DDS: determines whether a newly registered device not
- explicitly placed into a discovery domain (DD) and
- discovery domain set (DDS) is placed into a default
- DD/DDS.
-
- DD/DDS Modification: determines whether the specified type of Node is
- allowed to add, delete or update DDs and DDSs.
-
-
-
-Tseng, et al. Standards Track [Page 13]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- Authorized Control Nodes: a list of Nodes identified by iSCSI Name or
- FC Port Name WWPN that are authorized to register as
- Control Nodes.
-
-2.5. iSNS Server Discovery
-
-2.5.1. Service Location Protocol (SLP)
-
- The Service Location Protocol (SLP) provides a flexible and scalable
- framework for providing hosts with access to information about the
- existence, location, and configuration of networked services,
- including the iSNS server. SLP can be used by iSNS clients to
- discover the IP address or FQDN of the iSNS server. To implement
- discovery through SLP, a Service Agent (SA) should be cohosted in the
- iSNS server, and a User Agent (UA) should be in each iSNS client.
- Each client multicasts a discovery message requesting the IP address
- of the iSNS server(s). The SA responds to this request. Optionally,
- the location of the iSNS server can be stored in the SLP Directory
- Agent (DA).
-
- Note that a complete description and specification of SLP can be
- found in [RFC2608], and is beyond the scope of this document. A
- service template for using SLP to locate iSNS servers can be found in
- [iSCSI-SLP].
-
-2.5.2. Dynamic Host Configuration Protocol (DHCP)
-
- The IP address of the iSNS server can be stored in a DHCP server to
- be downloaded by iSNS clients using a DHCP option. The DHCP option
- number to be used for distributing the iSNS server location is found
- in [iSNSOption].
-
-2.5.3. iSNS Heartbeat Message
-
- The iSNS heartbeat message is described in Section 5.6.5.14. It
- allows iSNS clients within the broadcast or multicast domain of the
- iSNS server to discover the location of the active iSNS server and
- any backup servers.
-
-2.6. iSNS and Network Address Translation (NAT)
-
- The existence of NAT will have an impact upon information retrieved
- from the iSNS server. If the iSNS client exists in an addressing
- domain different from that of the iSNS server, then IP address
- information stored in the iSNS server may not be correct when
- interpreted in the domain of the iSNS client.
-
-
-
-
-
-Tseng, et al. Standards Track [Page 14]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- There are several possible approaches to allow operation of iSNS
- within a NAT network. The first approach is to require use of the
- canonical TCP port number by both targets and initiators when
- addressing targets across a NAT boundary, and for the iSNS client not
- to query for nominal IP addresses. Rather, the iSNS client queries
- for the DNS Fully Qualified Domain Name stored in the Entity
- Identifier field when seeking addressing information. Once
- retrieved, the DNS name can be interpreted in each address domain and
- mapped to the appropriate IP address by local DNS servers.
-
- A second approach is to deploy a distributed network of iSNS servers.
- Local iSNS servers are deployed inside and outside NAT boundaries,
- with each local server storing relevant IP addresses for their
- respective NAT domains. Updates among the network of decentralized,
- local iSNS servers are handled using LDAP and appropriate NAT
- translation rules implemented within the update mechanism in each
- server.
-
- Finally, note that it is possible for an iSNS server in the private
- addressing domain behind a NAT boundary to exclusively support iSNS
- clients that are operating in the global IP addressing domain. If
- this is the case, the administrator only needs to ensure that the
- appropriate mappings are configured on the NAT gateways to allow the
- iSNS clients to initiate iSNSP sessions to the iSNS server. All
- registered addresses contained in the iSNS server are thus public IP
- addresses for use outside the NAT boundary. Care should be taken to
- ensure that there are no iSNS clients querying the server from inside
- the NAT boundary.
-
-2.7. Transfer of iSNS Database Records between iSNS Servers
-
- Transfer of iSNS database records between iSNS servers has important
- applications, including the following:
-
- 1) An independent organization needs to transfer storage information
- to a different organization. Each organization independently
- maintains its own iSNS infrastructure. To facilitate discovery
- of storage assets of the peer organization using IP, iSNS
- database records can be transferred between authoritative iSNS
- servers from each organization. This allows storage sessions to
- be established directly between devices residing in each
- organization's storage network infrastructure over a common IP
- network.
-
- 2) Multiple iSNS servers are desired for redundancy. Backup servers
- need to maintain copies of the primary server's dynamically
- changing database.
-
-
-
-
-Tseng, et al. Standards Track [Page 15]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- To support the above applications, information in an iSNS server can
- be distributed to other iSNS servers either using the iSNS protocol,
- or through out-of-band mechanisms using non-iSNS protocols. The
- following examples illustrate possible methods for transferring data
- records between iSNS servers. In the first example, a back-end LDAP
- information base is used to support the iSNS server, and the data is
- transferred using the LDAP protocol. Once the record transfer of the
- remote device is completed, it becomes visible and accessible to
- local devices using the local iSNS server. This allows local devices
- to establish sessions with remote devices (provided that firewall
- boundaries can be negotiated).
-
- +-------------------------+ +-------------------------+
- |+------+ iSNSP | | iSNSP +-----+ |
- ||dev A |<----->+------+ | | +------+<----->|dev C| |
- |+------+ | | | | | | +-----+ |
- |+------+ iSNSP |local | | | |remote| iSNSP +-----+ |
- ||dev B |<----->| iSNS | | | | iSNS |<----->|dev D| |
- |+------+ |server| | | |server| +-----+ |
- |........ +--+---+ | WAN | +---+--+ |
- |.dev C'. | | Link | | |
- |........ | ============= | |
- | | | | | |
- | +--+---+ | | +---+--+ |
- | | local|<--- <--- <--- <-|remote| |
- | | LDAP | | LDAP: | | LDAP | |
- | +------+ Xfer "dev C"| +------+ |
- +-------------------------+ +-------------------------+
- Enterprise Enterprise
- Network A Network B
-
- In the above diagram, two business partners wish to share storage
- "dev C". Using LDAP, the record for "dev C" can be transferred from
- Network B to Network A. Once accessible to the local iSNS server in
- Network A, local devices A and B can now discover and connect to "dev
- C".
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 16]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- +-------------------------+ +-------------------------+
- |+------+ iSNSP | | iSNSP +-----+ |
- ||dev A |<----->+------+ | | +------+<----->|dev C| |
- |+------+ | | | | | | +-----+ |
- |+------+ iSNSP |local | | | |remote| iSNSP +-----+ |
- ||dev B |<----->| iSNS | | | | iSNS |<----->|dev D| |
- |+------+ |server| | | |server| +-----+ |
- |........ +------+ | WAN | +---+--+ |
- |.dev C'. ^ | Link | | |
- |........ | ============= v |
- | | | | |SNMP |
- | | | | | |
- | +--+----+ | | v |
- | | SNMP |<--- <--- <--- <---- |
- | | Mgmt | | SNMP: Xfer "dev C" |
- | |Station| | | |
- | +-------+ | | |
- +-------------------------+ +-------------------------+
- Enterprise Enterprise
- Network A Network B
-
- The above diagram illustrates a second example of how iSNS records
- can be shared. This method uses an SNMP-based management station to
- retrieve (GET) the desired record for "dev C" manually, and then to
- store (SET) it on the local iSNS server directly. Once the record is
- transferred to the local iSNS server in Network A, "dev C" becomes
- visible and accessible (provided that firewall boundaries can be
- negotiated) to other devices in Network A.
-
- Other methods, including proprietary protocols, can be used to
- transfer device records between iSNS servers. Further discussion and
- explanation of these methodologies is beyond the scope of this
- document.
-
-2.8. Backup iSNS Servers
-
- This section offers a broad framework for implementation and
- deployment of iSNS backup servers. Server failover and recovery are
- topics of continuing research, and adequate resolution of issues such
- as split brain and primary server selection is dependent on the
- specific implementation requirements and deployment needs. The
- failover mechanisms discussed in this document focus on the
- interaction between iSNS clients and iSNS servers. Specifically,
- what is covered in this document includes the following:
-
- - iSNS client behavior and the iSNS protocol interaction between the
- client and multiple iSNS servers, some of which are backup
- servers.
-
-
-
-Tseng, et al. Standards Track [Page 17]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- - Required failover behaviors of the collection of iSNS servers that
- includes active and backup servers.
-
- However, note that this document does not specify the complete
- functional failover requirements of each iSNS server. In particular,
- it does not specify the complete set of protocol interactions among
- the iSNS servers that are required to achieve stable failover
- operation in an interoperable manner.
-
- For the purposes of this discussion, the specified backup mechanisms
- pertain to interaction among different logical iSNS servers. Note
- that it is possible to create multiple physical iSNS servers to form
- a single logical iSNS server cluster, and thus to distribute iSNS
- transaction processing among multiple physical servers. However, a
- more detailed discussion of the interactions between physical servers
- within a logical iSNS server cluster is beyond the scope of this
- document.
-
- Multiple logical iSNS servers can be used to provide redundancy in
- the event that the active iSNS server fails or is removed from the
- network. The methods described in Section 2.7 above can be used to
- transfer name server records to backup iSNS servers. Each backup
- server maintains a redundant copy of the name server database found
- in the primary iSNS server, and can respond to iSNS protocol messages
- in the same way as the active server. Each backup server SHOULD
- monitor the health and status of the active iSNS server, including
- checking to make sure its own database is synchronized with the
- active server's database. How each backup server accomplishes this
- is implementation-dependent, and may (or may not) include using the
- iSNS protocol. If the iSNS protocol is used, then the backup server
- MAY register itself in the active server's iSNS database as a Control
- Node, allowing it to receive state-change notifications.
-
- Generally, the administrator or some automated election process is
- responsible for initial and subsequent designation of the primary
- server and each backup server.
-
- A maximum of one logical backup iSNS server SHALL exist at any
- individual IP address, in order to avoid conflicts from multiple
- servers listening on the same canonical iSNS TCP or UDP port number.
-
- The iSNS heartbeat can also be used to coordinate the designation and
- selection of primary and backup iSNS servers.
-
- Each backup server MUST note its relative precedence in the active
- server's list of backup servers. If its precedence is not already
- known, each backup server MAY learn it from the iSNS heartbeat
- message, by noting the position of its IP address in the ordered list
-
-
-
-Tseng, et al. Standards Track [Page 18]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- of backup server IP addresses. For example, if it is the first
- backup listed in the heartbeat message, then its backup precedence is
- 1. If it is the third backup server listed, then its backup
- precedence is 3.
-
- If a backup server establishes that it has lost connectivity to the
- active server and other backup servers of higher precedence, then it
- SHOULD assume that it is the active server. The method of
- determining whether connectivity has been lost is implementation-
- specific. One possible approach is to assume that if the backup
- server does not receive iSNS heartbeat messages for a period of time,
- then connectivity to the active server has been lost. Alternatively,
- the backup server may establish TCP connections to the active server
- and other backup servers, with loss of connectivity determined
- through non-response to periodic echo or polling messages (using
- iSNSP, SNMP, or other protocols).
-
- When a backup server becomes the active server, it SHALL assume all
- active server responsibilities, including (if used) transmission of
- the iSNS heartbeat message. If transmitting the iSNS heartbeat, the
- backup server replaces the active Server IP Address and TCP/UDP Port
- entries with its own IP address and TCP/UDP Port, and begins
- incrementing the counter field from the last known value from the
- previously-active iSNS server. However, it MUST NOT change the
- original ordered list of backup server IP Address and TCP/UDP Port
- entries. If the primary backup server or other higher-precedence
- backup server returns, then the existing active server is responsible
- for ensuring that the new active server's database is up-to-date
- before demoting itself to its original status as backup.
-
- Since the primary and backup iSNS servers maintain a coordinated
- database, no re-registration by an iSNS Client is required when a
- backup server takes the active server role. Likewise, no re-
- registration by an iSNS Client is required when the previous primary
- server returns to the active server role.
-
-2.9. Transport Protocols
-
- The iSNS Protocol is transport-neutral. Query and registration
- messages are transported over TCP or UDP. iSNS heartbeat messages
- are transported using IP multicast or broadcast.
-
-2.9.1. Use of TCP for iSNS Communication
-
- It MUST be possible to use TCP for iSNS communication. The iSNS
- server MUST accept TCP connections for client registrations. To
- receive Entity Status Inquiry (ESI) (see Section 5.6.5.13) monitoring
- the use of TCP, the client registers the Portal ESI Interval and the
-
-
-
-Tseng, et al. Standards Track [Page 19]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- port number of the TCP port that will be used to receive ESI
- messages. The iSNS server initiates the TCP connection used to
- deliver the ESI message. This TCP connection does not need to be
- continuously open.
-
- To receive SCN notifications using TCP, the client registers the
- iSCSI or iFCP SCN Bitmap and the port number of the TCP port in the
- Portal used to receive SCNs. The iSNS server initiates the TCP
- connection used to deliver the SCN message. This TCP connection does
- not need to be continuously open.
-
- It is possible for an iSNS client to use the same TCP connection for
- SCN, ESI, and iSNS queries. Alternatively, separate connections may
- be used.
-
-2.9.2. Use of UDP for iSNS Communication
-
- The iSNS server MAY accept UDP messages for client registrations.
- The iSNS server MUST accept registrations from clients requesting
- UDP-based ESI and SCN messages.
-
- To receive UDP-based ESI monitoring messages, the client registers
- the port number of the UDP port in at least one Portal to be used to
- receive and respond to ESI messages from the iSNS server. If a
- Network Entity has multiple Portals with registered ESI UDP Ports,
- then ESI messages SHALL be delivered to every Portal registered to
- receive such messages.
-
- To receive UDP-based SCN notification messages, the client registers
- the port number of the UDP port in at least one Portal to be used to
- receive SCN messages from the iSNS server. If a Network Entity has
- multiple Portals with registered SCN UDP Ports, then SCN messages
- SHALL be delivered to each Portal registered to receive such
- messages.
-
- When using UDP to transport iSNS messages, each UDP datagram MUST
- contain exactly one iSNS PDU (see Section 5).
-
-2.9.3. iSNS Multicast and Broadcast Messages
-
- iSNS multicast messages are transported using IP multicast or
- broadcast. The iSNS heartbeat is the only iSNS multicast or
- broadcast message. This message is originated by the iSNS server and
- sent to all iSNS clients that are listening on the IP multicast
- address allocated for the iSNS heartbeat.
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 20]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-2.10. Simple Network Management Protocol (SNMP) Requirements
-
- The iSNS Server may be managed via the iSNS MIB [iSNSMIB] using an
- SNMP management framework [RFC3411]. For a detailed overview of the
- documents that describe the current Internet-Standard Management
- Framework, please refer to Section 7 of RFC 3410 [RFC3410]. The iSNS
- MIB provides the ability to configure and monitor an iSNS server
- without using the iSNS protocol directly. SNMP management frameworks
- have several requirements for object indexing in order for objects to
- be accessed or added.
-
- SNMP uses an Object Identifier (OID) for object identification. The
- size of each OID is restricted to a maximum of 128 sub-identifiers.
- Both the iSCSI and iFCP protocol contain identifiers, such as the
- iSCSI Name, that are greater the 128 characters in length. Using
- such identifiers as an index would result in more than 128 sub-
- identifiers per OID. In order to support objects that have key
- identifiers whose maximum length is longer than the maximum SNMP-
- supported length, the iSNS server provides secondary non-zero integer
- index identifiers. These indexes SHALL be persistent for as long as
- the server is active. Furthermore, index values for recently
- deregistered objects SHOULD NOT be reused in the short term. Object
- attributes, including indexes, are described in detail in Section 6.
-
- For SNMP based management applications to create a new entry in a
- table of objects, a valid OID must be available to specify the table
- row. The iSNS server supports this by providing, for each type of
- object that can be added via SNMP, an object attribute that returns
- the next available non-zero integer index. This allows an SNMP
- client to request an OID to be used for registering a new object in
- the server. Object attributes, including next available index
- attributes, are described in detail in Section 6.
-
-3. iSNS Object Model
-
- iSNS provides the framework for the registration, discovery, and
- management of iSCSI devices and Fibre Channel-based devices (using
- iFCP). This architecture framework provides elements needed to
- describe various storage device objects and attributes that may exist
- on an IP storage network. Objects defined in this architecture
- framework include Network Entity, Portal, Storage Node, FC Device,
- Discovery Domain, and Discovery Domain Set. Each of these objects is
- described in greater detail in the following sections.
-
-
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 21]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-3.1. Network Entity Object
-
- The Network Entity object is a container of Storage Node objects and
- Portal objects. It represents the infrastructure supporting access
- to a unique set of one or more Storage Nodes. The Entity Identifier
- attribute uniquely distinguishes a Network Entity, and is the key
- used to register a Network Entity object in an iSNS server. All
- Storage Nodes and Portals contained within a single Network Entity
- object operate as a cohesive unit.
-
- Note that it is possible for a single physical device or gateway to
- be represented by more than one logical Network Entity in the iSNS
- database. For example, one of the Storage Nodes on a physical device
- may be accessible from only a subset of the network interfaces (i.e.,
- Portals) available on that device. In this case, a logical network
- entity (i.e., a "shadow entity") is created and used to contain the
- Portals and Storage Nodes that can operate cooperatively. No object
- (Portals, Storage Nodes, etc.) can be contained in more than one
- logical Network Entity.
-
- Similarly, it is possible for a logical Network Entity to be
- supported by more than one physical device or gateway. For example,
- multiple FC-iSCSI gateways may be used to bridge FC devices in a
- single Fibre Channel network. Collectively, the multiple gateways
- can be used to support a single logical Network Entity that is used
- to contain all the devices in that Fibre Channel network.
-
-3.2. Portal Object
-
- The Portal object is an interface through which access to Storage
- Nodes within the Network Entity can be obtained. The IP address and
- TCP/UDP Port number attributes uniquely distinguish a Portal object,
- and combined are the key used to register a Portal object in an iSNS
- server. A Portal is contained in one and only one Network Entity,
- and may be contained in one or more DDs (see Section 3.6).
-
-3.3. Storage Node Object
-
- The Storage Node object is the logical endpoint of an iSCSI or iFCP
- session. In iFCP, the session endpoint is represented by the World
- Wide Port Name (WWPN). In iSCSI, the session endpoint is represented
- by the iSCSI Name of the device. For iSCSI, the iSCSI Name attribute
- uniquely distinguishes a Storage Node, and is the key used to
- register a Storage Node object in an iSNS Server. For iFCP, the FC
- Port Name (WWPN) attribute uniquely distinguishes a Storage Node, and
- is the key used to register a Storage Node object in the iSNS Server.
- Storage Node is contained in only one Network Entity object and may
- be contained in one or more DDs (see Section 3.6).
-
-
-
-Tseng, et al. Standards Track [Page 22]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-3.4. Portal Group Object
-
- The Portal Group (PG) object represents an association between a
- Portal and an iSCSI Node. Each Portal and iSCSI Storage Node
- registered in an Entity can be associated using a Portal Group (PG)
- object. The PG Tag (PGT), if non-NULL, indicates that the associated
- Portal provides access to the associated iSCSI Storage Node in the
- Entity. All Portals that have the same PGT value for a specific
- iSCSI Storage Node allow coordinated access to that node.
-
- A PG object MAY be registered when a Portal or iSCSI Storage Node is
- registered. Each Portal to iSCSI Node association is represented by
- one and only one PG object. In order for a Portal to provide access
- to an iSCSI Node, the PGT of the PG object MUST be non-NULL. If the
- PGT value registered for a specified Portal and iSCSI Node is NULL,
- or if no PGT value is registered, then the Portal does not provide
- access to that iSCSI Node in the Entity.
-
- The PGT value indicates whether access to an iSCSI Node can be
- coordinated across multiple Portals. All Portals that have the same
- PGT value for a specific iSCSI Node can provide coordinated access to
- that iSCSI Node. According to the iSCSI Specification, coordinated
- access to an iSCSI node indicates the capability of coordinating an
- iSCSI session with connections that span these Portals [iSCSI].
-
- The PG object is uniquely distinguished by the iSCSI Name, Portal IP
- Address, and Portal TCP Port values of the associated Storage Node
- and Portal objects. These are represented in the iSNS Server by the
- PG iSCSI Name, PG Portal IP Address, and PG Portal TCP/UDP Port
- attributes, respectively. The PG object is also uniquely
- distinguished in the iSNS Server by the PG Index value.
-
- A new PG object can only be registered by referencing its associated
- iSCSI Storage Node or Portal object. A pre-existing PG object can be
- modified or queried by using its Portal Group Index as message key,
- or by referencing its associated iSCSI Storage Node or Portal object.
- A 0-length Tag, Length, Value TLV is used to register a PGT NULL
- value.
-
- The PG object is deregistered if and only if its associated iSCSI
- Node and Portal objects are both removed.
-
-
-
-
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 23]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-3.5. Device Object
-
- The FC Device represents the Fibre Channel Node. This object
- contains information that may be useful in the management of the
- Fibre Channel device. The FC Node Name (WWNN) attribute uniquely
- distinguishes an FC Device, and is the key used to register an FC
- Device object in the iSNS Server.
-
- The FC Device is contained in one or more Storage Node objects.
-
-3.6. Discovery Domain Object
-
- Discovery Domains (DD) are a security and management mechanism used
- to administer access and connectivity to storage devices. For query
- and registration purposes, they are considered containers for Storage
- Node and Portal objects. A query by an iSNS client that is not from
- a Control Node only returns information about objects with which it
- shares at least one active DD. The only exception to this rule is
- with Portals; if Storage Nodes of a Network Entity are registered in
- the DD without Portals, then all Portals of that Network Entity are
- implicit members of that DD. The Discovery Domain ID (DD_ID)
- attribute uniquely distinguishes a Discovery Domain object, and is
- the key used to register a Discovery Domain object in the iSNS
- Server.
-
- A DD is considered active if it is a member of at least one active DD
- Set. DDs that are not members of at least one enabled DDS are
- considered disabled. A Storage Node can be a member of one or more
- DDs. An enabled DD establishes connectivity among the Storage Nodes
- in that DD.
-
-3.7. Discovery Domain Set Object
-
- The Discovery Domain Set (DDS) is a container object for Discovery
- Domains (DDs). DDSs may contain one or more DDs. Similarly, each DD
- can be a member of one or more DDSs. DDSs are a mechanism to store
- coordinated sets of DD mappings in the iSNS server. Active DDs are
- members of at least one active DD Set. Multiple DDSs may be
- considered active at the same time. The Discovery Domain Set ID
- (DDS_ID) attribute uniquely distinguishes a Discovery Domain Set
- object, and is the key used to register a Discovery Domain Set object
- in the iSNS Server.
-
-3.8. Database Model
-
- As presented to the iSNS client, each object of a specific type in
- the iSNS database MUST have an implicit internal linear ordering
- based on the key(s) for that object type. This ordering provides the
-
-
-
-Tseng, et al. Standards Track [Page 24]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- ability to respond to DevGetNext queries (see Section 5.6.5.3). The
- ordering of objects in the iSNS database SHOULD NOT be changed with
- respect to that implied ordering, as a consequence of object
- insertions and deletions. That is, the relative order of surviving
- object entries in the iSNS database SHOULD be preserved so that the
- DevGetNext message encounters generally reasonable behavior.
-
- The following diagram shows the various objects described above and
- their relationship to each other.
-
- +--------------+ +-----------+
- | NETWORK |1 *| |
- | ENTITY |----| PORTAL |
- | | | |
- +--------------+ +-----------+
- |1 |1 |*
- | | |
- | |* |
- | +----------+ |
- | | PORTAL | |
- | | GROUP | |
- | +----------+ |
- | |* |
- | | |
- |* |1 |*
- +-----------+ +--------------+ +-----------+ +-----------+
- | FC |1 *| STORAGE |* *| DISCOVERY |* *| DISCOVERY |
- | DEVICE |----| NODE |----| DOMAIN |----| DOMAIN |
- | | | | | | | SET |
- +-----------+ +--------------+ +-----------+ +-----------+
-
- * represents 0 to many possible relationships
-
-4. iSNS Implementation Requirements
-
- This section details specific requirements for support of each of
- these IP storage protocols. Implementation requirements for security
- are described in Section 7.
-
-4.1. iSCSI Requirements
-
- Use of iSNS in support of iSCSI is OPTIONAL. iSCSI devices MAY be
- manually configured with the iSCSI Name and IP address of peer
- devices, without the aid or intervention of iSNS. iSCSI devices may
- also use SLP [RFC2608] to discover peer iSCSI devices. However, iSNS
- is useful for scaling a storage network to a larger number of iSCSI
- devices.
-
-
-
-
-Tseng, et al. Standards Track [Page 25]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-4.1.1. Required Attributes for Support of iSCSI
-
- The following attributes are available to support iSCSI. Attributes
- indicated in the REQUIRED for Server column MUST be implemented by an
- iSNS server used to support iSCSI. Attributes indicated in the
- REQUIRED for Client column MUST be implemented by an iSCSI device
- that elects to use the iSNS. Attributes indicated in the K (Key)
- column uniquely identify the object type in the iSNS Server. A more
- detailed description of each attribute is found in Section 6.
-
- REQUIRED for:
- Object Attribute K Server Client
- ------ --------- - ------ ------
- NETWORK ENTITY Entity Identifier * * *
- Entity Protocol * *
- Management IP Address *
- Timestamp *
- Protocol Version Range *
- Registration Period *
- Entity Index *
- Entity IKE Phase-1 Proposal
- Entity Certificate
-
- PORTAL IP Address * * *
- TCP/UDP Port * * *
- Portal Symbolic Name *
- ESI Interval *
- ESI Port *
- Portal Index *
- SCN Port *
- Portal Security Bitmap *
- Portal IKE Phase-1 Proposal
- Portal IKE Phase-2 Proposal
- Portal Certificate
-
- PORTAL GROUP PG iSCSI Name * * *
- PG IP Address * * *
- PG TCP/UDP Port * * *
- PG Tag * *
- PG Index *
-
-
-
-
-
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 26]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- STORAGE NODE iSCSI Name * * *
- iSCSI Node Type * *
- Alias *
- iSCSI SCN Bitmap *
- iSCSI Node Index *
- WWNN Token
- iSCSI AuthMethod
- iSCSI Node Certificate
-
- DISCOVERY DOMAIN DD ID * * *
- DD Symbolic Name *
- DD Member iSCSI Node Index *
- DD Member iSCSI Name *
- DD Member Portal Index *
- DD Member Portal IP Addr *
- DD Member Portal TCP/UDP *
- DD Features *
-
- DISCOVERY DOMAIN DDS Identifier * *
- SET DDS Symbolic Name *
- DDS Status *
-
- All iSCSI user-specified and vendor-specified attributes are OPTIONAL
- to implement and use.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 27]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-4.1.2. Examples: iSCSI Object Model Diagrams
-
- The following diagram models how a simple iSCSI-based initiator and
- target is represented using database objects stored in the iSNS
- server. In this implementation, each target and initiator is
- attached to a single Portal.
-
- +----------------------------------------------------------------+
- | IP Network |
- +------------+--------------------------------------+------------+
- | |
- | |
- +-----+------+------+-----+ +-----+------+------+-----+
- | | PORTAL | | | | PORTAL | |
- | | -IP Addr 1 | | | | -IP Addr 2 | |
- | | -TCP Port 1 | | | | -TCP Port 2 | |
- | +-----+ +-----+ | | +-----+ +-----+ |
- | | | | | | | |
- | +-----+ +-----+ | | +-----+ +-----+ |
- | | PORTAL GROUP| | | | PORTAL GROUP| |
- | | -Prtl Tag 1 | | | | -Prtl Tag 2 | |
- | +-----+ +-----+ | | +-----+ +-----+ |
- | | | | | | | |
- | +--------+ +--------+ | | +-------+ +--------+ |
- | | | | | | | |
- | | STORAGE NODE | | | | STORAGE NODE | |
- | | -iSCSI Name | | | | -iSCSI Name | |
- | | -Alias: "server1"| | | | -Alias: "disk1"| |
- | | -Type: initiator | | | | -Type: target | |
- | | | | | | | |
- | +-------------------+ | | +------------------+ |
- | | | |
- | NETWORK ENTITY | | NETWORK ENTITY |
- | -Entity ID (FQDN): | | -Entity ID (FQDN): |
- | "strg1.example.com" | | "strg2.example.net" |
- | -Protocol: iSCSI | | -Protocol: iSCSI |
- | | | |
- +-------------------------+ +-------------------------+
-
- The object model can be expanded to describe more complex devices,
- such as an iSCSI device with more than one storage controller, in
- which each controller is accessible through any of multiple Portal
- interfaces, possibly using multiple Portal Groups. The storage
- controllers on this device can be accessed through alternate Portal
- interfaces if any original interface should fail. The following
- diagram describes such a device:
-
-
-
-
-
-Tseng, et al. Standards Track [Page 28]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- +---------------------------------------------------------------+
- | IP Network |
- +-------------------+-----------------------+-------------------+
- | |
- | |
- +------------+------+------+---------+------+------+------------+
- | | PORTAL 1 | | PORTAL 2 | |
- | | -IP Addr 1 | | -IP Addr 2 | |
- | | -TCP Port 1 | | -TCP Port 2 | |
- | +-----+ +-----+ +-----+ +-----+ |
- | | | | | |
- | +---------------+ +---------------------+ +---------------+ |
- | +-------+ +----------------+ +-------------------+ +------+ |
- | | | | | | | |
- | +-------+ +-------+ +------+ +--------+ +--------+ +------+ |
- | | | | | | | |
- | | STORAGE NODE 1 | | STORAGE NODE 2 | | STORAGE NODE 3 | |
- | | -iSCSI Name 1 | | -iSCSI Name 2 | | -iSCSI Name 3 | |
- | | -Alias: "disk1"| | -Alias: "disk2"| | -Alias: "disk3"| |
- | | -Type: target | | -Type: target | | -Type: target | |
- | | | | | | | |
- | +-----------------+ +-----------------+ +-----------------+ |
- | |
- | NETWORK ENTITY |
- | -Entity ID (FQDN): "dev1.example.com" |
- | -Protocol: iSCSI |
- | |
- | Portal Group Object Table |
- | Storage-Node Portal Portal-Group-Tag |
- | 1 1 10 |
- | 1 2 NULL (no access permitted) |
- | 2 1 20 |
- | 2 2 20 |
- | 3 1 30 |
- | 3 2 10 |
- | |
- +---------------------------------------------------------------+
-
- Storage Node 1 is accessible via Portal 1 with a PGT of 10. It does
- not have a Portal Group Tag (PGT) assigned for Portal 2, so Storage
- Node 1 cannot be accessed via Portal 2.
-
- Storage Node 2 can be accessed via both Portal 1 and Portal 2. Since
- Storage Node 2 has the same PGT value assigned to both Portal 1 and
- Portal 2, in this case 20, coordinated access via the Portals is
- available [iSCSI].
-
-
-
-
-
-Tseng, et al. Standards Track [Page 29]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- Storage Node 3 can be accessed via Portal 1 or Portal 2. However,
- since Storage Node 3 has different PGT values assigned to each
- Portal, in this case 10 and 30, access is not coordinated [iSCSI].
- Because PGTs are assigned within the context of a Storage Node, the
- PGT value of 10 used for Storage Node 1 and Storage Node 3 are not
- interrelated.
-
-4.1.3. Required Commands and Response Messages for Support of iSCSI
-
- The following iSNSP messages and responses are available in support
- of iSCSI. Messages indicated in the REQUIRED for Server column MUST
- be implemented in iSNS servers used for iSCSI devices. Messages
- indicated in the REQUIRED for Client column MUST be implemented in
- iSCSI devices that elect to use the iSNS server.
-
- REQUIRED for:
- Message Description Abbreviation Func_ID Server Client
- ------------------- ------------ ------- ------ ------
- RESERVED 0x0000
- Device Attr Reg Request DevAttrReg 0x0001 * *
- Dev Attr Query Request DevAttrQry 0x0002 * *
- Dev Get Next Request DevGetNext 0x0003 *
- Deregister Dev Request DevDereg 0x0004 * *
- SCN Register Request SCNReg 0x0005 *
- SCN Deregister Request SCNDereg 0x0006 *
- SCN Event SCNEvent 0x0007 *
- State Change Notification SCN 0x0008 *
- DD Register DDReg 0x0009 * *
- DD Deregister DDDereg 0x000A * *
- DDS Register DDSReg 0x000B * *
- DDS Deregister DDSDereg 0x000C * *
- Entity Status Inquiry ESI 0x000D *
- Name Service Heartbeat Heartbeat 0x000E
- RESERVED 0x000F-0x00FF
- Vendor Specific 0x0100-0x01FF
- RESERVED 0x0200-0x7FFF
-
- The following are iSNSP response messages used in support of iSCSI:
-
- REQUIRED for:
- Response Message Desc Abbreviation Func_ID Server Client
- --------------------- ------------ ------- ------ ------
- RESERVED 0x8000
- Device Attr Register Rsp DevAttrRegRsp 0x8001 * *
- Device Attr Query Rsp DevAttrQryRsp 0x8002 * *
- Device Get Next Rsp DevGetNextRsp 0x8003 *
- Device Dereg Rsp DevDeregRsp 0x8004 * *
- SCN Register Rsp SCNRegRsp 0x8005 *
-
-
-
-Tseng, et al. Standards Track [Page 30]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- SCN Deregister Rsp SCNDeregRsp 0x8006 *
- SCN Event Rsp SCNEventRsp 0x8007 *
- SCN Response SCNRsp 0x8008 *
- DD Register Rsp DDRegRsp 0x8009 * *
- DD Deregister Rsp DDDeregRsp 0x800A * *
- DDS Register Rsp DDSRegRsp 0x800B * *
- DDS Deregister Rsp DDSDeregRsp 0x800C * *
- Entity Stat Inquiry Rsp ESIRsp 0x800D *
- RESERVED 0x800E-0x80FF
- Vendor Specific 0x8100-0x81FF
- RESERVED 0x8200-0xFFFF
-
-4.2. iFCP Requirements
-
- In iFCP, use of iSNS is REQUIRED. No alternatives exist for support
- of iFCP Naming & Discovery functions.
-
-4.2.1. Required Attributes for Support of iFCP
-
- The following table displays attributes that are used by iSNS to
- support iFCP. Attributes indicated in the REQUIRED for Server column
- MUST be implemented by the iSNS server that supports iFCP.
- Attributes indicated in the REQUIRED for Client column MUST be
- supported by iFCP gateways. Attributes indicated in the K (Key)
- column uniquely identify the object type in the iSNS Server. A more
- detailed description of each attribute is found in Section 6.
-
- REQUIRED for:
- Object Attribute K Server Client
- ------ --------- - ------ ------
- NETWORK ENTITY Entity Identifier * * *
- Entity Protocol * *
- Management IP Address *
- Timestamp *
- Protocol Version Range *
- Registration period
- Entity Index
- Entity IKE Phase-1 Proposal
- Entity Certificate
-
- PORTAL IP Address * * *
- TCP/UDP Port * * *
- Symbolic Name *
- ESI Interval *
- ESI Port *
- SCN Port *
- Portal IKE Phase-1 Proposal
- Portal IKE Phase-2 Proposal
-
-
-
-Tseng, et al. Standards Track [Page 31]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- Portal Certificate
- Security Bitmap *
-
- STORAGE NODE FC Port Name (WWPN) * * *
- (FC Port) Port_ID * *
- FC Port Type * *
- Port Symbolic Name *
- Fabric Port Name (FWWN) *
- Hard Address *
- Port IP Address *
- Class of Service *
- FC FC-4 Types *
- FC FC-4 Descriptors *
- FC FC-4 Features *
- SCN Bitmap *
- iFCP Port Role *
- Permanent Port Name *
-
- FC DEVICE FC Node Name (WWNN) * * *
- (FC Node) Node Symbolic Name *
- Node IP Address *
- Node IPA *
- Proxy iSCSI Name
-
- DISCOVERY DOMAIN DD ID * * *
- DD Symbolic Name *
- DD Member FC Port Name *
- DD Member Portal Index *
- DD Member Portal IP Addr *
- DD Member Portal TCP/UDP *
-
- DISCOVERY DOMAIN DDS ID * *
- SET DDS Symbolic Name *
- DDS Status *
-
- OTHER Switch Name
- Preferred_ID
- Assigned_ID
- Virtual_Fabric_ID
-
- All iFCP user-specified and vendor-specified attributes are OPTIONAL
- to implement and use.
-
-4.2.2. Example: iFCP Object Model Diagram
-
- The iFCP protocol allows native Fibre Channel devices or Fibre
- Channel fabrics connected to an iFCP gateway to be directly
- internetworked using IP.
-
-
-
-Tseng, et al. Standards Track [Page 32]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- When supporting iFCP, the iSNS server stores Fibre Channel device
- attributes, iFCP gateway attributes, and Fibre Channel fabric switch
- attributes that might also be stored in an FC name server.
-
- The following diagram shows a representation of a gateway supporting
- multiple Fibre Channel devices behind it. The two Portal objects
- represent IP interfaces on the iFCP gateway that can be used to
- access any of the three Storage Node objects behind it. Note that
- the FC Device object is not contained in the Network Entity object.
- However, each FC Device has a relationship to one or more Storage
- Node objects.
-
- +--------------------------------------------------------+
- | IP Network |
- +--------+-----------------+-----------------------------+
- | |
- +-+------+------+---+------+------+----------------------+
- | | PORTAL | | PORTAL | NETWORK ENTITY |
- | | -IP Addr 1 | | -IP Addr 2 | -Entity ID (FQDN): |
- | | -TCP Port 1 | | -TCP Port 2 | "gtwy1.example.com" |
- | +-----+ +-----+ +-----+ +-----+ -Protocol: iFCP |
- | | | | | |
- | +-----+ +---------------+ +----------------------+ |
- | +-----+ +---------------+ +-------------+ +------+ |
- | | | | | | | |
- | +-----+ +-----+ +----+ +------+ +----+ +------+ |
- | |STORAGE NODE | |STORAGE NODE | |STORAGE NODE | |
- | | -WWPN 1 | | -WWPN 2 | | -WWPN 3 | |
- | | -Port ID 1 | | -Port ID 2 | | -Port ID 3 | |
- | | -FWWN 1 | | -FWWN 2 | | -FWWN 3 | |
- | | -FC COS | | -FC COS | | -FC COS | |
- | +------+------+ +-------+-----+ +----+--------+ |
- +--------|-------------------|------------|--------------+
- | | |
- +------+------+ +---+------------+---+
- | FC DEVICE | | FC DEVICE |
- | -WWNN 1 | | -WWNN 2 |
- | | | |
- +-------------+ +--------------------+
-
-
-
-
-
-
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 33]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-4.2.3. Required Commands and Response Messages for Support of iFCP
-
- The iSNSP messages and responses displayed in the following tables
- are available to support iFCP gateways. Messages indicated in the
- REQUIRED TO IMPLEMENT column MUST be supported by the iSNS server
- used by iFCP gateways. Messages indicated in the REQUIRED TO USE
- column MUST be supported by the iFCP gateways themselves.
-
- REQUIRED for:
- Message Description Abbreviation Func ID Server Client
- ------------------- ------------ ------- ------ ------
- RESERVED 0x0000
- Device Attr Reg Request DevAttrReg 0x0001 * *
- Device Attr Query Request DevAttrQry 0x0002 * *
- Device Get Next Request DevGetNext 0x0003 *
- Device Dereg Request DevDereg 0x0004 * *
- SCN Register Request SCNReg 0x0005 *
- SCN Deregister Request SCNDereg 0x0006 *
- SCN Event SCNEvent 0x0007 *
- State Change Notification SCN 0x0008 *
- DD Register DDReg 0x0009 * *
- DD Deregister DDDereg 0x000A * *
- DDS Register DDSReg 0x000B * *
- DDS Deregister DDSDereg 0x000C * *
- Entity Status Inquiry ESI 0x000D *
- Name Service Heartbeat Heartbeat 0x000E *
- Reserved Reserved 0x000F-0x0010
- Request FC_DOMAIN_ID RqstDomId 0x0011
- Release FC_DOMAIN_ID RlseDomId 0x0012
- Get FC_DOMAIN_IDs GetDomId 0x0013
- RESERVED 0x0014-0x00FF
- Vendor Specific 0x0100-0x01FF
- RESERVED 0x0200-0x7FFF
-
- The following are iSNSP response messages in support of iFCP:
-
- REQUIRED for:
- Response Message Desc Abbreviation Func_ID Server Client
- --------------------- ------------ ------- ------ ------
- RESERVED 0x8000
- Device Attr Reg Rsp DevAttrRegRsp 0x8001 * *
- Device Attr Query Rsp DevAttrQryRsp 0x8002 * *
- Device Get Next Rsp DevGetNextRsp 0x8003 *
- Device Deregister Rsp DevDeregRsp 0x8004 * *
- SCN Register Rsp SCNRegRsp 0x8005 *
- SCN Deregister Rsp SCNDeregRsp 0x8006 *
- SCN Event Rsp SCNEventRsp 0x8007 *
- SCN Rsp SCNRsp 0x8008 *
-
-
-
-Tseng, et al. Standards Track [Page 34]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- DD Register Rsp DDRegRsp 0x8009 * *
- DD Deregister Rsp DDDeregRsp 0x800A * *
- DDS Register Rsp DDSRegRsp 0x800B * *
- DDS Deregister Rsp DDSDeregRsp 0x800C * *
- Entity Status Inquiry Rsp ESIRsp 0x800D *
- NOT USED 0x800E
- RESERVED 0x800F-0x8010
- Request FC_DOMAIN_ID Rsp RqstDomIdRsp 0x8011
- Release FC_DOMAIN_ID Rsp RlseDomIdRsp 0x8012
- Get FC_DOMAIN_IDs GetDomIdRsp 0x0013
- RESERVED 0x8014-0x80FF
- Vendor Specific 0x8100-0x81FF
- RESERVED 0x8200-0xFFFF
-
-5. iSNSP Message Format
-
- The iSNSP message format is similar to the format of other common
- protocols such as DHCP, DNS and BOOTP. An iSNSP message may be sent
- in one or more iSNS Protocol Data Units (PDU). Each PDU is 4-byte
- aligned. The following describes the format of the iSNSP PDU:
-
- Byte MSb LSb
- Offset 0 15 16 31
- +---------------------+----------------------+
- 0 | iSNSP VERSION | FUNCTION ID | 4 Bytes
- +---------------------+----------------------+
- 4 | PDU LENGTH | FLAGS | 4 Bytes
- +---------------------+----------------------+
- 8 | TRANSACTION ID | SEQUENCE ID | 4 Bytes
- +---------------------+----------------------+
- 12 | |
- | PDU PAYLOAD | N Bytes
- | ... |
- +--------------------------------------------+
- 12+N | AUTHENTICATION BLOCK (Multicast/Broadcast) | L Bytes
- +--------------------------------------------+
- Total Length = 12 + N + L
-
-5.1. iSNSP PDU Header
-
- The iSNSP PDU header contains the iSNSP VERSION, FUNCTION ID, PDU
- LENGTH, FLAGS, TRANSACTION ID, and SEQUENCE ID fields as defined
- below.
-
-
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 35]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-5.1.1. iSNSP Version
-
- The iSNSP version described in this document is 0x0001. All other
- values are RESERVED. The iSNS server MAY reject messages for iSNSP
- version numbers that it does not support.
-
-5.1.2. iSNSP Function ID
-
- The FUNCTION ID defines the type of iSNS message and the operation to
- be executed. FUNCTION_ID values with the leading bit cleared
- indicate query, registration, and notification messages, whereas
- FUNCTION_ID values with the leading bit set indicate response
- messages.
-
- See Section 4 under the appropriate protocol (i.e., iSCSI or iFCP)
- for a mapping of the FUNCTION_ID value to the iSNSP Command or
- Response message. All PDUs comprising an iSNSP message must have the
- same FUNCTION_ID value.
-
-5.1.3. iSNSP PDU Length
-
- The iSNS PDU Length specifies the length of the PDU PAYLOAD field in
- bytes. The PDU Payload contains TLV attributes for the operation.
-
- Additionally, response messages contain a success/failure code. The
- PDU Length MUST be 4-byte aligned.
-
-5.1.4. iSNSP Flags
-
- The FLAGS field indicates additional information about the message
- and the type of Network Entity that generated the message. The
- following table displays the valid flags:
-
- Bit Position Enabled (1) means:
- ------------ -----------------
- 16 Sender is the iSNS client
- 17 Sender is the iSNS server
- 18 Authentication block is present
- 19 Replace flag (for DevAttrReg)
- 20 Last PDU of the iSNS message
- 21 First PDU of the iSNS message
- 22-31 RESERVED
-
-5.1.5. iSNSP Transaction ID
-
- The TRANSACTION ID MUST be set to a unique value for each
- concurrently outstanding request message. Replies MUST use the same
- TRANSACTION ID value as the associated iSNS request message. If a
-
-
-
-Tseng, et al. Standards Track [Page 36]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- message is retransmitted, the original TRANSACTION ID value MUST be
- used. All PDUs comprising an iSNSP message must have the same
- TRANSACTION ID value.
-
-5.1.6. iSNSP Sequence ID
-
- The SEQUENCE ID has a unique value for each PDU within a single
- transaction. The SEQUENCE_ID value of the first PDU transmitted in a
- given iSNS message MUST be zero (0), and each SEQUENCE_ID value in
- each PDU MUST be numbered sequentially in the order in which the PDUs
- are transmitted. Note that the two-byte SEQUENCE ID allows for up to
- 65536 PDUs per iSNS message.
-
-5.2. iSNSP Message Segmentation and Reassembly
-
- iSNS messages may be carried in one or more iSNS PDUs. If only one
- iSNS PDU is used to carry the iSNS message, then bit 21 (First PDU)
- and bit 20 in the FLAGS field (Last PDU) SHALL both be set. If
- multiple PDUs are used to carry the iSNS message, then bit 21 SHALL
- be set in the first PDU of the message, and bit 20 SHALL be set in
- the last PDU.
-
- All PDUs comprising the same iSNSP message SHALL have the same
- FUNCTION_ID and TRANSACTION_ID values. Each PDU comprising an iSNSP
- message SHALL have a unique SEQUENCE_ID value.
-
-5.3. iSNSP PDU Payload
-
- The iSNSP PDU PAYLOAD is of variable length and contains attributes
- used for registration and query operations. The attribute data items
- use a format similar to that of other protocols, such as DHCP
- [RFC2131] options. Each iSNS attribute is specified in the PDU
- Payload using Tag-Length-Value (TLV) data format, as shown below:
-
- Byte MSb LSb
- Offset 0 31
- +--------------------------------------------+
- 0 | Attribute Tag | 4 Bytes
- +--------------------------------------------+
- 4 | Attribute Length (N) | 4 Bytes
- +--------------------------------------------+
- 8 | |
- | Attribute Value | N Bytes
- | |
- +--------------------------------------------+
- Total Length = 8 + N
-
-
-
-
-
-Tseng, et al. Standards Track [Page 37]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- Attribute Tag: a 4-byte field that identifies the attribute as
- defined in Section 6.1. This field contains the
- tag value from the indicated table.
-
- Attribute Length: a 4-byte field that indicates the length, in bytes,
- of the value field to follow in the TLV. For
- variable-length attributes, the value field MUST
- contain padding bytes, if necessary, in order to
- achieve 4-byte alignment. A "zero-length TLV"
- contains only the attribute tag and length fields.
-
- Attribute Value: a variable-length field containing the attribute
- value and padding bytes (if necessary).
-
- The above format is used to identify each attribute in the PDU
- Payload. Note that TLV boundaries need not be aligned with PDU
- boundaries; PDUs may carry one or more TLVs, or any fraction thereof.
- The Response Status Code, contained in response message PDU Payloads
- and described below, is not in TLV format. PDU Payloads for messages
- that do not contain iSNS attributes, such as the Name Service
- Heartbeat, do not use the TLV format.
-
-5.3.1. Attribute Value 4-Byte Alignment
-
- All attribute values are aligned to 4-byte boundaries. For variable
- length attributes, if necessary, the TLV length MUST be increased to
- the next 4-byte boundary through padding with bytes containing zero
- (0). If an attribute value is padded, a combination of the tag and
- attribute value itself is used to determine the actual value length
- and number of pad bytes. There is no explicit count of the number of
- pad bytes provided in the TLV.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 38]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-5.4. iSNSP Response Status Codes
-
- All iSNSP response messages contain a 4-byte Status Code field as the
- first field in the iSNSP PDU PAYLOAD. If the original iSNSP request
- message was processed normally by the iSNS server, or by the iSNS
- client for ESI and SCN messages, then this field SHALL contain a
- status code of 0 (Successful). A non-zero status code indicates
- rejection of the entire iSNS client request message.
-
- Status Code Status Description
- ----------- -----------------
- 0 Successful
- 1 Unknown Error
- 2 Message Format Error
- 3 Invalid Registration
- 4 RESERVED
- 5 Invalid Query
- 6 Source Unknown
- 7 Source Absent
- 8 Source Unauthorized
- 9 No Such Entry
- 10 Version Not Supported
- 11 Internal Error
- 12 Busy
- 13 Option Not Understood
- 14 Invalid Update
- 15 Message (FUNCTION_ID) Not Supported
- 16 SCN Event Rejected
- 17 SCN Registration Rejected
- 18 Attribute Not Implemented
- 19 FC_DOMAIN_ID Not Available
- 20 FC_DOMAIN_ID Not Allocated
- 21 ESI Not Available
- 22 Invalid Deregistration
- 23 Registration Feature Not Supported
- 24 and above RESERVED
-
-5.5. Authentication for iSNS Multicast and Broadcast Messages
-
- For iSNS multicast and broadcast messages (see Section 2.9.3), the
- iSNSP provides authentication capability. The following section
- details the iSNS Authentication Block, which is identical in format
- to the SLP authentication block [RFC2608]. iSNS unicast messages
- SHOULD NOT include the authentication block, but rather should rely
- upon IPSec security mechanisms.
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 39]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- If a message contains an authentication block, then the
- "Authentication block present" bit in the iSNSP PDU header FLAGS
- field SHALL be enabled.
-
- If a PKI is available with an [X.509] Certificate Authority (CA),
- then public key authentication of the iSNS server is possible. The
- authentication block leverages the DSA with SHA-1 algorithm, which
- can easily integrate into a public key infrastructure.
-
- The authentication block contains a digital signature for the
- multicast message. The digital signature is calculated on a per-PDU
- basis. The authentication block contains the following information:
-
- 1. A time stamp, to prevent replay attacks.
- 2. A structured authenticator containing a signature calculated over
- the time stamp and the message being secured.
- 3. An indicator of the cryptographic algorithm that was used to
- calculate the signature.
- 4. An indicator of the keying material and algorithm parameters,
- used to calculate the signature.
-
- The authentication block is described in the following figure:
-
- Byte MSb LSb
- Offset 0 31
- +----------------------------------+
- 0 | BLOCK STRUCTURE DESCRIPTOR | 4 Bytes
- +----------------------------------+
- 4 | AUTHENTICATION BLOCK LENGTH | 4 Bytes
- +----------------------------------+
- 8 | TIMESTAMP | 8 Bytes
- +----------------------------------+
- 16 | SPI STRING LENGTH | 4 Bytes
- +----------------------------------+
- 20 | SPI STRING | N Bytes
- +----------------------------------+
- 20 + N | STRUCTURED AUTHENTICATOR | M Bytes
- +----------------------------------+
- Total Length = 20 + N + M
-
- BLOCK STRUCTURE DESCRIPTOR (BSD): Defines the structure and algorithm
- to use for the STRUCTURED AUTHENTICATOR. BSD values from
- 0x00000000 to 0x00007FFF are assigned by IANA, while
- values 0x00008000 to 0x00008FFF are for private use.
-
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 40]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- AUTHENTICATION BLOCK LENGTH: Defines the length of the authentication
- block, beginning with the BSD field and running through
- the last byte of the STRUCTURED AUTHENTICATOR.
-
- TIMESTAMP: This is an 8-byte unsigned, fixed-point integer giving the
- number of seconds since 00:00:00 GMT on January 1, 1970.
-
- SPI STRING LENGTH: The length of the SPI STRING field.
-
- SPI STRING (Security Parameters Index): Index to the key and
- algorithm used by the message recipient to decode the
- STRUCTURED AUTHENTICATOR field.
-
- STRUCTURED AUTHENTICATOR: Contains the digital signature. For the
- default BSD value of 0x0002, this field SHALL contain the
- binary ASN.1 encoding of output values from the DSA with
- SHA-1 signature calculation as specified in Section 2.2.2
- of [RFC3279].
-
-5.6. Registration and Query Messages
-
- The iSNSP registration and query message PDU Payloads contain a list
- of attributes, and have the following format:
-
- +----------------------------------------+
- | Source Attribute (Requests Only) |
- +----------------------------------------+
- | Message Key Attribute[1] (if present) |
- +----------------------------------------+
- | Message Key Attribute[2] (if present) |
- +----------------------------------------+
- | . . . |
- +----------------------------------------+
- | - Delimiter Attribute - |
- +----------------------------------------+
- | Operating Attribute[1] (if present) |
- +----------------------------------------+
- | Operating Attribute[2] (if present) |
- +----------------------------------------+
- | Operating Attribute[3] (if present) |
- +----------------------------------------+
- | . . . |
- +----------------------------------------+
-
- Each Source, Message Key, Delimiter, and Operating attribute is
- specified in the PDU Payload using the Tag-Length-Value (TLV) data
- format. iSNS Registration and Query messages are sent by iSNS Clients
-
-
-
-
-Tseng, et al. Standards Track [Page 41]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- to the iSNS server IP Address and well-known TCP/UDP Port. The iSNS
- Responses will be sent to the iSNS Client IP address and TCP/UDP port
- number from the original request message.
-
-5.6.1. Source Attribute
-
- The Source Attribute is used to identify the Storage Node to the iSNS
- server for queries and other messages that require source
- identification. The Source Attribute uniquely identifies the source
- of the message. Valid Source Attribute types are shown below.
-
- Valid Source Attributes
- -----------------------
- iSCSI Name
- FC Port Name WWPN
-
- For a query operation, the Source Attribute is used to limit the
- scope of the specified operation to the Discovery Domains of which
- the source is a member. Special Control Nodes, identified by the
- Source Attribute, may be administratively configured to perform the
- specified operation on all objects in the iSNS database without
- scoping to Discovery Domains.
-
- For messages that change the contents of the iSNS database, the iSNS
- server MUST verify that the Source Attribute identifies either a
- Control Node or a Storage Node that is a part of the Network Entity
- containing the added, deleted, or modified objects.
-
-5.6.2. Message Key Attributes
-
- Message Key attributes are used to identify matching objects in the
- iSNS database for iSNS query and registration messages. If present,
- the Message Key MUST be a Registration or Query Key for an object as
- described in Sections 5.6.5 and 6.1. A Message Key is not required
- when a query spans the entire set of objects available to the Source
- or a registration is for a new Entity.
-
- iSCSI Names used in the Message Key MUST be normalized according to
- the stringprep template [STRINGPREP]. Entity Identifiers (EIDs) used
- in the Message Key MUST be normalized according to the nameprep
- template [NAMEPREP].
-
-5.6.3. Delimiter Attribute
-
- The Delimiter Attribute separates the Message Key attributes from the
- Operating Attributes in a PDU Payload. The Delimiter Attribute has a
- tag value of 0 and a length value of 0. The Delimiter Attribute is
- always 8 bytes long (a 4-byte tag field and a 4-byte length field,
-
-
-
-Tseng, et al. Standards Track [Page 42]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- all containing zeros). If a Message Key is not required for a
- message, then the Delimiter Attribute immediately follows the Source
- Attribute.
-
-5.6.4. Operating Attributes
-
- The Operating Attributes are a list of one or more key and non-key
- attributes related to the actual iSNS registration or query operation
- being performed.
-
- Operating Attributes include object key attributes and non-key
- attributes. Object key attributes uniquely identify iSNS objects.
- Key attributes MUST precede the non-key attributes of each object in
- the Operating Attributes. The tag value distinguishes the attribute
- as an object key attribute (i.e., tag=1, 16&17, 32, 64, and 96) or a
- non-key attribute. iSCSI Names used in the Operating Attributes MUST
- be normalized according to the stringprep template [STRINGPREP].
- Entity Identifiers (EIDs) used in the Operating Attributes MUST be
- normalized according to the nameprep template [NAMEPREP].
-
- The ordering of Operating Attributes in the message is important for
- determining the relationships among objects and their ownership of
- non-key attributes. iSNS protocol messages that violate these
- ordering rules SHALL be rejected with the Status Code of 2 (Message
- Format Error). See the message descriptions for proper operating
- attribute ordering requirements.
-
- Some objects are keyed by more than one object key attribute value.
- For example, the Portal object is keyed by attribute tags 16 and 17.
- When describing an object keyed by more than one key attribute, every
- object key attribute of that object MUST be listed sequentially by
- tag value in the message before non-key attributes of that object and
- key attributes of the next object. A group of key attributes of this
- kind is treated as a single logical key attribute when identifying an
- object.
-
- Non-key attributes that immediately follow key attributes MUST be
- attributes of the object referenced by the key attributes. All non-
- key attributes of an object MUST be listed before the object key
- attributes introducing the next object.
-
- Objects MUST be listed in inheritance order, according to their
- containment order. Storage Node and Portal objects and their
- respective attributes MUST follow the Network Entity object to which
- they have a relationship. Similarly, FC Device objects MUST follow
- the Storage Node object to which they have a relationship.
-
-
-
-
-
-Tseng, et al. Standards Track [Page 43]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- Vendor-specific objects defined by tag values in the range 1537-2048
- have the same requirements described above.
-
-5.6.4.1. Operating Attributes for Query and Get Next Requests
-
- In Query and Get Next request messages, TLV attributes with length
- value of 0 are used to indicate which Operating Attributes are to be
- returned in the corresponding response. Operating Attribute values
- that match the TLV attributes in the original message are returned in
- the response message.
-
-5.6.5. Registration and Query Request Message Types
-
- The following describes each query and message type.
-
-5.6.5.1. Device Attribute Registration Request (DevAttrReg)
-
- The DevAttrReg message type is 0x0001. The DevAttrReg message
- provides the means for iSNS clients to update existing objects or
- register new objects. The value of the replace bit in the FLAGs
- field determines whether the DevAttrReg message updates or replaces
- an existing registration.
-
- The Source Attribute identifies the Node initiating the registration
- request.
-
- The Message Key identifies the object the DevAttrReg message acts
- upon. It MUST contain the key attribute(s) identifying an object.
- This object MUST contain all attributes and related subordinate
- object attributes that will be included in the Operating Attributes
- of the DevAttrReg PDU Payload. The key attribute(s) identifying this
- object MUST also be included among the Operating Attributes.
-
- If the Message Key contains an EID and no pre-existing objects match
- the Message Key, then the DevAttrReg message SHALL create a new
- Entity with the specified EID and any new object(s) specified by the
- Operating Attributes. The replace bit SHALL be ignored.
-
- If the Message Key does not contain an EID, and no pre-existing
- objects match the Message Key, then the DevAttrReg message SHALL be
- rejected with a status code of 3 (Invalid Registration).
-
- If the Message Key is not present, then the DevAttrReg message
- implicitly registers a new Network Entity. In this case, the replace
- bit SHALL be ignored; a new Network Entity SHALL be created.
- Existing entities, their objects, and their relationships remain
- unchanged.
-
-
-
-
-Tseng, et al. Standards Track [Page 44]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- The replace bit determines the kind of operation conducted on the
- object identified in the DevAttrReg Message Key. The replace bit
- only applies to the DevAttrReg message; it is ignored for all other
- message types.
-
- If the replace bit is set, then the objects, attributes, and
- relationships specified in the Operating Attributes SHALL replace the
- object identified by the Message Key. The object and all of its
- subordinate objects SHALL be deregistered, and the appropriate SCNs
- SHALL be sent by the iSNS server for the deregistered objects. The
- objects listed in the Operating Attributes are then used to replace
- the just-deregistered objects. Note that additional SCNs SHALL be
- sent for the newly-registered objects, if appropriate. Existing
- objects and relationships that are not identified or that are
- subordinate to the object identified by the Message Key MUST NOT be
- affected or changed.
-
- If the replace bit is not set, then the message updates the
- attributes of the object identified by the Message Key and its
- subordinate objects. Existing object containment relationships MUST
- NOT be changed. For existing objects, key attributes MUST NOT be
- modified, but new subordinate objects MAY be added.
-
- The Operating Attributes represent objects, attributes, and
- relationships that are to be registered. Multiple related objects
- and attributes MAY be registered in a single DevAttrReg message. The
- ordering of the objects in this message indicates the structure of,
- and associations among, the objects to be registered. At least one
- object MUST be listed in the Operating Attributes. Additional
- objects (if any) MUST be subordinate to the first object listed. Key
- attributes MUST precede non-key attributes of each object. A given
- object may only appear a maximum of once in the Operating Attributes
- of a message. If the Node identified by the Source Attribute is not
- a Control Node, then the objects in the operating attributes MUST be
- members of the same Network Entity as the Source Node.
-
- For example, to establish relationships between a Network Entity
- object and its Portal and Storage Node objects, the Operating
- Attributes list the key and non-key attributes of the Network Entity
- object, followed by the key and non-key attributes of each Portal and
- Storage Node object to be linked to that Network Entity. Similarly,
- an FC Device object that follows a Storage Node object is considered
- subordinate to that Storage Node.
-
- New PG objects are registered when an associated Portal or iSCSI Node
- object is registered. An explicit PG object registration MAY follow
- a Portal or iSCSI Node object registration in a DevAttrReg message.
-
-
-
-
-Tseng, et al. Standards Track [Page 45]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- When a Portal is registered, the Portal attributes MAY immediately be
- followed by a PGT attribute. The PGT attribute SHALL be followed by
- the set of PG iSCSI Names representing nodes that will be associated
- to the Portal using the indicated PGT value. Additional sets of PGTs
- and PG iSCSI Names to be associated to the registered Portal MAY
- follow. Indicated PGT values are assigned to the PG object
- associated with the newly registered Portal and to the iSCSI Storage
- Node(s) referenced immediately following the PGT attribute in the
- operating attributes.
-
- When an iSCSI Storage Node is registered, the Storage Node attributes
- MAY immediately be followed by a PGT attribute. The PGT attribute
- SHALL be followed by the set of PG Portal IP-Address, PG TCP/UDP Port
- pairs representing Portal objects that will be associated with the
- Storage Node using the indicated PGT value. Additional sets of PGTs
- and PG Portal IP-Address PG TCP/UDP Port pairs to be associated with
- the registered Storage Node MAY follow. Indicated PGT values are
- assigned to the PG object associated with the newly registered iSCSI
- Storage Node and Portal object(s) referenced immediately following
- the PGT attribute in the operating attributes.
-
- If the PGT value is not included in the Storage Node or Portal object
- registration, and if a PGT value was not previously registered for
- the relationship, then the PGT for the corresponding PG object SHALL
- be registered with a value of 0x00000001. If the PGT attribute is
- included in the registration message as a 0-length TLV, then the PGT
- value for the corresponding PG object SHALL be registered as NULL. A
- 0-length TLV for the PGT in an update registration message overwrites
- the previous PGT value with NULL, indicating that there is no
- relationship between the Storage Node and Portal.
-
- A maximum of one Network Entity object can be created or updated with
- a single DevAttrReg message. Consequently, the Operating Attributes
- MUST NOT contain more than one Network Entity object. There is no
- limit to the number of Portal, Storage Node, and FC Device objects
- that can listed in the Operating Attributes, provided they are all
- subordinate to the listed Network Entity object.
-
- If the Message Key and Operating Attributes do not contain an EID
- attribute, or if the EID attribute has a length of 0, then a new
- Network Entity object SHALL be created and the iSNS server SHALL
- supply a unique EID value for it. The assigned EID value SHALL be
- included in the DevAttrReg Response message. If the Message Key and
- Operating Attributes contain an EID that does not match the EID of an
- existing Network Entity in the iSNS database, then a new Network
- Entity SHALL be created and assigned the value contained in that EID
- attribute. Finally, if the Message Key and Operating Attributes
- contain an EID that matches the EID of an existing object in the iSNS
-
-
-
-Tseng, et al. Standards Track [Page 46]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- database, then the objects, attributes, and relationships specified
- in the Operating Attributes SHALL be appended to the existing Network
- Entity identified by the EID.
-
- A registration message that creates a new Network Entity object MUST
- contain at least one Portal or one Storage Node. If the message does
- not, then it SHALL be considered invalid and result in a response
- with Status Code of 3 (Invalid Registration).
-
- If an iSNS Server does not support a registration feature, such as
- explicit PG object registration, then the server SHALL return a
- Status Code of 23 (Registration Feature Not Supported).
-
- Note that the iSNS server may modify or reject the registration of
- certain attributes, such as ESI Interval. In addition, the iSNS
- server may assign values for additional Operating Attributes that are
- not explicitly registered in the original DevAttrReg message, such as
- the EID and WWNN Token.
-
-5.6.5.2. Device Attribute Query Request (DevAttrQry)
-
- The DevAttrQry message type is 0x0002. The DevAttrQry message
- provides an iSNS client with the means to query the iSNS server for
- object attributes.
-
- The Source Attribute identifies the Node initiating the request. For
- non-Control Nodes initiating the DevAttrQry message, the query is
- scoped to the Discovery Domains of which the initiating Node is a
- member. The DevAttrQry message SHALL only return information on
- Storage Nodes and their related parent and subordinate objects, where
- the Storage Node has a common Discovery Domain with the Node
- identified in the Source Attribute.
-
- The Message Key may contain key or non-key attributes or no
- attributes at all. If multiple attributes are used as the Message
- Key, then they MUST all be from the same object type (e.g., IP
- address and TCP/UDP Port are attributes of the Portal object type).
- A Message Key with non-key attributes may match multiple instances of
- the specific object type. A Message Key with zero-length TLV(s) is
- scoped to every object of the type indicated by the zero-length
- TLV(s). An empty Message Key field indicates the query is scoped to
- the entire database accessible by the source Node.
-
- The DevAttrQry response message returns attributes of objects listed
- in the Operating Attributes that are related to the Message Key of
- the original DevAttrQry message. The Operating Attributes of the
- DevAttrQry message contain zero-length TLVs that specify the
- attributes that are to be returned in the DevAttrQryRsp message. A
-
-
-
-Tseng, et al. Standards Track [Page 47]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- Message Key containing zero-length TLVs indicates that the set of
- attributes specified in the Operating Attributes are to be returned
- for each object matching the type indicated by the Message Key.
-
- If the Message Key contains non-zero length TLVs, then Operating
- Attributes for the object matching the Message Key SHALL be returned
- in the DevAttrQryRsp message. Each attribute type (i.e., zero-length
- TLV) in the Operating Attributes indicates an attribute from the
- object matching the Message Key, or from other objects in the same
- Entity having a relationship to the object matching the Message Key,
- is to be returned in the response. The ordering of the object keys
- and associated attributes returned in the DevAttrQry response message
- SHALL be the same as in the original query message. If no objects
- match the Message Key, then the DevAttrQryRsp message SHALL NOT
- return any operating attributes. Such a message and its
- corresponding response SHALL NOT be considered an error.
-
- The Portal Group object determines whether a relationship exists
- between a given Storage Node and Portal object. If the PGT of the
- Portal Group is not NULL, then a relationship exists between the
- indicated Storage Node and Portal; if the PGT is NULL, then no
- relationship exists. Therefore, the value (NULL or not NULL) of the
- PGT attribute of each Portal Group object determines the structure
- and ordering of the DevAttrQry response to a query for Storage Nodes
- and Portals.
-
- For example, an iSNS database contains a Network Entity having two
- Portals and two Nodes. Each Storage Node has two Portal Groups, one
- with a NULL PGT value for one Portal and another with a non-NULL PGT
- value for the other Portal. The DevAttrQry message contains a
- Message Key entry matching one of the Nodes, and Operating Attributes
- with zero-length TLVs listing first the Node attributes, Portal
- attributes, and then the PG attributes. The response message SHALL
- therefore return first the matching Node object, then the requested
- attributes of the one Portal object that can be used to access the
- Storage Node (as indicated by the PGT), and finally the requested
- attributes of the PG object used to access that Storage Node. The
- order in which each object's attributes are listed is the same as the
- ordering of the object's attributes in the Operating Attributes of
- the original request message.
-
- If the Message Key Attribute contains zero-length TLV(s), then the
- query returns requested attributes for all objects matching the
- Message Key type (DD restrictions SHALL apply for non-Control Nodes).
- If multiple objects match the Message Key type, then the attributes
- for each object matching the Message Key MUST be listed before the
- attributes for the next matching object are listed in the query
-
-
-
-
-Tseng, et al. Standards Track [Page 48]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- response. In other words, the process described above must be
- iterated in the message response for each object that matches the
- Message Key type specified by the zero-length TLV(s).
-
- For example, an iSNS database contains only one Network Entity having
- two Portals and three Nodes. All PG objects in the Entity have a PGT
- value of 0x00000001. In the DevAttrQry message, the Message Key
- contains a zero-length TLV specifying a Node type, and Operating
- Attributes listing first the Node attributes, and then the Portal
- attributes. The response message will return, in the following
- order, the attributes for the first, next, and last Node objects,
- each followed by attributes for both Portals. If that same
- DevAttrQry message had instead contained a zero-length TLV specifying
- the Network Entity type, then the response message would have
- returned attributes for all three Node objects, followed by
- attributes for the two Portals.
-
- If there is no Message Key Attribute, then the query returns all
- attributes in the iSNS database (once again, DD restrictions SHALL
- apply for non-Control Nodes). All attributes matching the type
- specified by each zero-length TLV in the Operating Attributes SHALL
- be listed. All attributes of each type SHALL be listed before the
- attributes matching the next zero-length TLV are listed.
-
- For example, an iSNS database contains two Entities, each having two
- Nodes and two Portals. The DevAttrQry message contains no Message
- Key attribute, and Operating Attributes list first the Portal
- attributes, and then the Node attributes. The Operating Attributes
- of the response message will return attributes from each of the four
- Portals, followed by attributes from each of the four nodes.
-
- If a DevAttrQry message requests an attribute for which the iSNS
- server has no value, then the server SHALL NOT return the requested
- attribute in the query response. Such query and response messages
- SHALL NOT be considered errors.
-
- Registration and query messages for iSNS server-specific attributes
- (i.e., tags in the range 132 to 384) SHALL be formatted using the
- identifying key attribute of the Storage Node originating the query
- (i.e., iSCSI Name or FC Port Name WWPN) for both the Source Attribute
- and Message Key attribute. Operating Attributes SHALL include the
- TLV of the server-specific attribute being requested.
-
- DD membership can be discovered through the DevAttrQry message by
- including either DD member attributes (i.e., DD Member iSCSI Index,
- DD Member iSCSI Node, DD Member iFCP Node, DD Member Portal Index, DD
- Member Portal IP Addr, and DD Member Portal TCP/UDP) or the object
- key of the Storage Node or Portal (i.e., iSCSI Name, iSCSI Index,
-
-
-
-Tseng, et al. Standards Track [Page 49]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- Portal IP Addr, Portal TCP/UDP Port, and Portal Index) in the
- Operating Attributes. Using DD member attributes SHALL return both
- registered and unregistered member Storage Nodes and/or Portals of a
- DD. DevAttrQry messages using the Storage Node and/or Portal object
- key SHALL return only member Storage Nodes or Portals that are
- currently registered in the iSNS database.
-
- The DevAttrQry message SHALL support the following minimum set of
- Message Key Attributes:
-
- Valid Message Key Attributes for Queries
- ----------------------------------------
- Entity Identifier
- Entity Protocol
- Portal IP-Address & Portal TCP/UDP Port
- Portal Index
- iSCSI Node Type
- iSCSI Name
- iSCSI Index
- PG Index
- FC Port Name WWPN
- FC Port Type
- FC-4 Type
- Discovery Domain ID
- Discovery Domain Set ID
- Source Attribute (for server-specific attributes)
- Switch Name (FC Device WWNN--for Virtual_Fabric_ID queries)
-
-5.6.5.3. Device Get Next Request (DevGetNext)
-
- The DevGetNext message type is 0x0003. This message provides the
- iSNS client with the means to retrieve each and every instance of an
- object type exactly once.
-
- The Source Attribute identifies the Node initiating the DevGetNext
- request, and is used to scope the retrieval process to the Discovery
- Domains of which the initiating Node is a member.
-
- The Message Key Attribute may be an Entity Identifier (EID), iSCSI
- Name, iSCSI Index, Portal IP Address and TCP/UDP Port, Portal Index,
- PG Index, FC Node Name WWNN, or FC Port Name WWPN. If the TLV length
- of the Message Key Attribute(s) is zero, then the first object entry
- in the iSNS database matching the Message Key type SHALL be returned
- in the Message Key of the corresponding DevGetNextRsp message. If
- non-zero-length TLV attributes are contained in the Message Key, then
- the DevGetNext response message SHALL return the next object stored
- after the object identified by the Message Key in the original
- DevGetNext request message.
-
-
-
-Tseng, et al. Standards Track [Page 50]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- If the Message Key provided matches the last object instance in the
- iSNS database, then the Status Code of 9 (No Such Entry) SHALL be
- returned in the response.
-
- The Operating Attributes can be used to specify the scope of the
- DevGetNext request, and to specify the attributes of the next object,
- which are to be returned in the DevGetNext response message. All
- Operating Attributes MUST be attributes of the object type identified
- by the Message Key. For example, if the Message Key is an Entity_ID
- attribute, then the Operating Attributes MUST NOT contain attributes
- of Portals.
-
- Non-zero-length TLV attributes in the Operating Attributes are used
- to scope the DevGetNext message. Only the next object with attribute
- values that match the non-zero-length TLV attributes SHALL be
- returned in the DevGetNext response message.
-
- Zero-length TLV attributes MUST be listed after non-zero-length
- attributes in the Operating Attributes of the DevGetNext request
- message. Zero-length TLV attributes specify the attributes of the
- next object which are to be returned in the DevGetNext response
- message.
-
- Note that there are no specific requirements concerning the order in
- which object entries are retrieved from the iSNS database; the
- retrieval order of object entries using the DevGetNext message is
- implementation specific.
-
- The iSNS client is responsible for ensuring that information acquired
- through use of the DevGetNext message is accurate and up-to-date.
- There is no assurance that the iSNS database will not change between
- successive DevGetNext request messages. If the Message Key provided
- does not match an existing database entry, then attributes for the
- next object key following the provided Message Key SHALL be returned.
- For example, an object entry may have been deleted between successive
- DevGetNext messages. This may result in a DevGetNext request in
- which the Message Key does not match an existing object entry. In
- this case, attributes for the next object stored in the iSNS database
- are returned.
-
-5.6.5.4. Device Deregister Request (DevDereg)
-
- The DevDereg message type is 0x0004. This message is used to remove
- object entries from the iSNS database. One or more objects may be
- removed through a single DevDereg message. Note that deregistered
- Storage Node objects will retain membership in their Discovery
- Domain(s) until explicit deregistration of the membership(s) or
- Discovery Domain(s).
-
-
-
-Tseng, et al. Standards Track [Page 51]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- Upon receiving the DevDereg, the iSNS server removes all objects
- identified by the Operating Attribute(s), and all subordinate objects
- that are solely dependent on those identified objects. For example,
- removal of a Network Entity also results in removal of all associated
- Portal, Portal Group, Storage Node, and FC Device objects associated
- with that Network Entity. FC Device objects SHALL not be
- deregistered in this manner unless all Storage Nodes associated with
- them have been deregistered.
-
- The DevDereg request PDU Payload contains a Source Attribute and
- Operating Attribute(s); there are no Message Key Attributes. If the
- Node identified by the Source Attribute is not a Control Node, then
- it MUST be from the same Network Entity as the object(s) identified
- for removal by the Operating Attribute(s). Valid Operating
- Attributes are shown below:
-
- Valid Operating Attributes for DevDereg
- ---------------------------------------
- Entity Identifier
- Portal IP-Address & Portal TCP/UDP Port
- Portal Index
- iSCSI Name
- iSCSI Index
- FC Port Name WWPN
- FC Node Name WWNN
-
- The removal of the object may result in SCN messages to the
- appropriate iSNS clients.
-
- Attempted deregistration of non-existing entries SHALL not be
- considered an error.
-
- If all Nodes and Portals associated with a Network Entity are
- deregistered, then the Network Entity SHALL also be removed.
-
- If both the Portal and iSCSI Storage Node objects associated with a
- Portal Group object are removed, then that Portal Group object SHALL
- also be removed. The Portal Group object SHALL remain registered as
- long as either of its associated Portal or iSCSI Storage Node objects
- remain registered. If a deleted Storage Node or Portal object is
- subsequently re-registered, then a relationship between the re-
- registered object and an existing Portal or Storage Node object
- registration, indicated by the PG object, SHALL be restored.
-
-
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 52]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-5.6.5.5. SCN Register Request (SCNReg)
-
- The SCNReg message type is 0x0005. The State Change Notification
- Registration Request (SCNReg) message allows an iSNS client to
- register a Storage Node to receive State Change Notification (SCN)
- messages.
-
- The SCN notifies the Storage Node of changes to any Storage Nodes
- within any DD of which it is a member. If the Storage Node is a
- Control Node, it SHALL receive SCN notifications for changes in the
- entire network. Note that whereas SCNReg sets the SCN Bitmap field,
- the DevAttrReg message registers the UDP or TCP Port used by each
- Portal to receive SCN messages. If no SCN Port fields of any Portals
- of the Storage Node are registered to receive SCN messages, then the
- SCNReg message SHALL be rejected with Status Code 17 (SCN
- Registration Rejected).
-
- The SCNReg request PDU Payload contains a Source Attribute, a Message
- Key Attribute, and an Operating Attribute. Valid Message Key
- Attributes for a SCNReg are shown below:
-
- Valid Message Key Attributes for SCNReg
- ---------------------------------------
- iSCSI Name
- FC Port Name WWPN
-
- The node with the iSCSI Name or FC Port Name WWPN attribute that
- matches the Message Key in the SCNReg message is registered to
- receive SCNs using the specified SCN bitmap. A maximum of one Node
- SHALL be registered for each SCNReg message.
-
- The SCN Bitmap is the only operating attribute of this message, and
- it always overwrites the previous contents of this field in the iSNS
- database. The bitmap indicates the SCN event types for which the
- Node is registering.
-
- Note that the settings of this bitmap determine whether the SCN
- registration is for regular SCNs or management SCNs. Control Nodes
- MAY conduct registrations for management SCNs; iSNS clients that are
- not supporting Control Nodes MUST NOT conduct registrations for
- management SCNs. Control Nodes that register for management SCNs
- receive a copy of every SCN message generated by the iSNS server. It
- is recommended that management registrations be used only when needed
- in order to conserve iSNS server resources. In addition, a Control
- Node that conducts such registrations should be prepared to receive
- the anticipated volume of SCN message traffic.
-
-
-
-
-
-Tseng, et al. Standards Track [Page 53]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-5.6.5.6. SCN Deregister Request (SCNDereg)
-
- The SCNDereg message type is 0x0006. The SCNDereg message allows an
- iSNS client to stop receiving State Change Notification (SCN)
- messages.
-
- The SCNDereg request message PDU Payload contains a Source Attribute
- and Message Key Attribute(s). Valid Message Key Attributes for a
- SCNDereg are shown below:
-
- Valid Message Key Attributes for SCNDereg
- -----------------------------------------
- iSCSI Name
- FC Port Name WWPN
-
- The node with an iSCSI Name or FC Port Name WWPN attribute that
- matches the Message Key Attributes in the SCNDereg message is
- deregistered for SCNs. The SCN bitmap field of such Nodes are
- cleared. A maximum of one Node SHALL be deregistered for each
- SCNDereg message.
-
- There are no Operating Attributes in the SCNDereg message.
-
-5.6.5.7. SCN Event (SCNEvent)
-
- The SCNEvent message type is 0x0007. The SCNEvent is a message sent
- by an iSNS client to request generation of a State Change
- Notification (SCN) message by the iSNS server. The SCN, sent by the
- iSNS server, then notifies iFCP, iSCSI, and Control Nodes within the
- affected DD of the change indicated in the SCNEvent.
-
- Most SCNs are automatically generated by the iSNS server when Nodes
- are registered or deregistered from the directory database. SCNs are
- also generated when a network management application or Control Node
- makes changes to the DD membership in the iSNS server. However, an
- iSNS client can trigger an SCN by using SCNEvent.
-
- The SCNEvent message PDU Payload contains a Source Attribute, a
- Message Key Attribute, and an Operating Attribute. Valid Key
- Attributes for a SCNEvent are shown below:
-
- Valid Message Key Attributes for SCNEvent
- -----------------------------------------
- iSCSI Name
- FC Port Name WWPN
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 54]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- The Operating Attributes section SHALL contain the SCN Event Bitmap
- attribute. The bitmap indicates the event that caused the SCNEvent
- to be generated.
-
-5.6.5.8. State Change Notification (SCN)
-
- The SCN message type is 0x0008. The SCN is a message generated by
- the iSNS server, notifying a registered Storage Node of changes.
- There are two types of SCN registrations: regular registrations and
- management registrations. Regular SCNs notify iSNS clients of events
- within the discovery domain. Management SCNs notify Control Nodes
- that register for management SCNs of events occurring anywhere in the
- network.
-
- If no active TCP connection to the SCN recipient exists, then the SCN
- message SHALL be sent to one Portal of the registered Storage Node
- that has a registered TCP or UDP Port value in the SCN Port field.
- If more than one Portal of the Storage Node has a registered SCN Port
- value, then the SCN SHALL be delivered to any one of the indicated
- Portals, provided that the selected Portal is not the subject of the
- SCN.
-
- The types of events that can trigger an SCN message, and the amount
- of information contained in the SCN message, depend on the registered
- SCN Event Bitmap for the Storage Node. The iSCSI Node SCN Bitmap is
- described in Section 6.4.4. The iFCP SCN Bitmap is described in
- Section 6.6.12.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 55]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- The format of the SCN PDU Payload is shown below:
-
- +----------------------------------------+
- | Destination Attribute |
- +----------------------------------------+
- | Timestamp |
- +----------------------------------------+
- | Source SCN Bitmap 1 |
- +----------------------------------------+
- | Source Attribute [1] |
- +----------------------------------------+
- | Source Attribute [2](if present) |
- +----------------------------------------+
- | Source Attribute [3](if present) |
- +----------------------------------------+
- | Source Attribute [n](if present) |
- +----------------------------------------+
- | Source SCN Bitmap 2 (if present) |
- +----------------------------------------+
- | . . . |
- +----------------------------------------+
-
- All PDU Payload attributes are in TLV format.
-
- The Destination Attribute is the Node identifier that is receiving
- the SCN. The Destination Attribute can be an iSCSI Name or FC Port
- Name.
-
- The Timestamp field, using the Timestamp TLV format, described in
- Section 6.2.4, indicates the time the SCN was generated.
-
- The Source SCN Bitmap field indicates the type of SCN notification
- (i.e., regular or management SCN), and the type of event that caused
- the SCN to be generated; it does not necessarily correlate with the
- original SCN bitmap registered in the iSNS server.
-
- Following the timestamp, the SCN message SHALL list the SCN bitmap,
- followed by the key attribute (i.e., iSCSI Name or FC Port Name) of
- the Storage Node affected by the SCN event. If the SCN is a
- Management SCN, then the SCN message SHALL also list the DD_ID and/or
- DDS_ID of the Discovery Domains and Discovery Domain Sets (if any)
- that caused the change in state for that Storage Node. These
- additional attributes (i.e., DD_ID and/or DDS_ID) shall immediately
- follow the iSCSI Name or FC Port Name and precede the next SCN bitmap
- for the next notification message (if any). The SCN bitmap is used
- as a delineator for SCN messages providing multiple state change
- notifications.
-
-
-
-
-Tseng, et al. Standards Track [Page 56]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- For example, a regular SCN for notifying an iSNS client of a new
- Portal available for a particular iSCSI target would contain the SCN
- bitmap followed by the iSCSI Name of the target device as the source
- attribute. If the SCN were a management SCN, then the iSCSI Name
- would be followed by the DD_ID(s) of the shared Discovery Domains
- that allow the destination Storage Node to have visibility to the
- affected Storage Node. If a Discovery Domain Set (DDS) was enabled
- in order to provide this visibility, then the appropriate DDS_ID
- would be included as well.
-
- A management SCN is also generated to notify a Control Node of the
- creation, deletion, or modification of a Discovery Domain or
- Discovery Domain Set. In this case, the DD_ID and/or DDS_ID of the
- affected Discovery Domain and/or Discovery Domain Set would follow
- the SCN bitmap.
-
- For example, a management SCN to notify a Control Node of a new DD
- within a Discovery Domain Set would contain both the DD_ID and the
- DDS_ID of the affected Discovery Domain and Discovery Domain Set
- among the Source Attributes.
-
- See Sections 6.4.4 and 6.6.12 for additional information on the SCN
- Bitmap.
-
-5.6.5.9. DD Register (DDReg)
-
- The DDReg message type is 0x0009. This message is used to create a
- new Discovery Domain (DD), to update an existing DD Symbolic Name
- and/or DD Features attribute, and to add DD members.
-
- DDs are uniquely defined using DD_IDs. DD registration attributes
- are described in Section 6.11.
-
- The DDReg message PDU Payload contains the Source Attribute and
- optional Message Key and Operating Attributes.
-
- The Message Key, if used, contains the DD_ID of the Discovery Domain
- to be registered. If the Message Key contains a DD_ID of an existing
- DD entry in the iSNS database, then the DDReg message SHALL attempt
- to update the existing entry. If the DD_ID in the Message Key (if
- used) does not match an existing DD entry, then the iSNS server SHALL
- reject the DDReg message with a status code of 3 (Invalid
- Registration). If the DD_ID is included in both the Message Key and
- Operating Attributes, then the DD_ID value in the Message Key MUST be
- the same as the DD_ID value in the Operating Attributes.
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 57]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- A DDReg message with no Message Key SHALL result in the attempted
- creation of a new Discovery Domain (DD). If the DD_ID attribute
- (with non-zero length) is included among the Operating Attributes in
- the DDReg message, then the new Discovery Domain SHALL be assigned
- the value contained in that DD_ID attribute. Otherwise, if the DD_ID
- attribute is not contained among the Operating Attributes of the
- DDReg message, or if the DD_ID is an operating attribute with a TLV
- length of 0, then the iSNS server SHALL assign a DD_ID value. The
- assigned DD_ID value is then returned in the DDReg Response message.
- The Operating Attributes can also contain the DD Member iSCSI Node
- Index, DD Member iSCSI Name, DD Member FC Port Name, DD Member Portal
- IP Address, DD Member Portal TCP/UDP Port Number, or DD Member Portal
- Index of members to be added to the DD. It may also contain the
- DD_Symbolic_Name and/or DD_Features of the DD.
-
- This message SHALL add any DD members listed as Operating Attributes
- to the Discovery Domain specified by the DD_ID. If the DD_Features
- attribute is an Operating Attribute, then it SHALL be stored in the
- iSNS server as the feature list for the specified DD. If the
- DD_Symbolic_Name is an operating attribute and its value is unique
- (i.e., it does not match the registered DD_Symbolic_Name for another
- DD), then the value SHALL be stored in the iSNS database as the
- DD_Symbolic_Name for the specified Discovery Domain. If the value
- for the DD_Symbolic_Name is not unique, then the iSNS server SHALL
- reject the attempted DD registration with a status code of 3 (Invalid
- Registration).
-
- When creating a new DD, if the DD_Symbolic_Name is not included in
- the Operating Attributes, or if it is included with a zero-length
- TLV, then the iSNS server SHALL provide a unique DD_Symbolic_Name
- value for the created DD. The assigned DD_Symbolic_Name value SHALL
- be returned in the DDRegRsp message.
-
- When creating a new DD, if the DD_Features attribute is not included
- in the Operating Attributes, then the iSNS server SHALL assign the
- default value. The default value for DD_Features is 0.
-
- DD Member iSCSI Name, DD Member iFCP Node, DD Member Portal IP
- Address, and DD Member TCP/UDP Port Number attributes included in the
- Operating Attributes need not match currently existing iSNS database
- entries. This allows, for example, a Storage Node to be added to a
- DD even if the Storage Node is not currently registered in the iSNS
- database. A Storage Node or Portal can thereby be added to a DD at
- the time of the DDs creation, even if the Storage Node or Portal is
- not currently active in the storage network.
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 58]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- If the Operating Attributes contain a DD Member iSCSI Name value for
- a Storage Node that is currently not registered in the iSNS database,
- then the iSNS server MUST allocate an unused iSCSI Node Index for
- that Storage Node. The assigned iSCSI Node Index SHALL be returned
- in the DDRegRsp message as the DD Member iSCSI Node Index. The
- allocated iSCSI Node Index value SHALL be assigned to the Storage
- Node if and when it registers in the iSNS database.
-
- If the Operating Attributes contain a DD Member Portal IP Addr and DD
- Member Portal TCP/UDP value for a Portal that is not currently
- registered in the iSNS database, then the iSNS server MUST allocate
- an unused Portal Index value for that Portal. The assigned Portal
- Index value SHALL be returned in the DDRegRsp message as the DD
- Member Portal Index. The allocated Portal Index value SHALL be
- assigned to the Portal if and when it registers in the iSNS database.
-
- DD Member iSCSI Node Index and DD Member Portal Index attributes that
- are provided in the Operating Attributes MUST match a corresponding
- iSCSI Node Index or Portal Index of an existing Storage Node or
- Portal entry in the iSNS database. Furthermore, the DD Member iSCSI
- Node Index and DD Member Portal Index SHALL NOT be used to add
- Storage Nodes or Portals to a DD unless those Storage Nodes or
- Portals are actively registered in the iSNS database.
-
-5.6.5.10. DD Deregister (DDDereg)
-
- The DDDereg message type is 0x000A. This message allows an iSNS
- client to deregister an existing Discovery Domain (DD) and to remove
- members from an existing DD.
-
- DDs are uniquely identified using DD_IDs. DD registration attributes
- are described in Section 6.11.
-
- The DDDereg message PDU Payload contains a Source Attribute, Message
- Key Attribute, and optional Operating Attributes.
-
- The Message Key Attribute for a DDDereg message is the DD ID for the
- Discovery Domain being removed or having members removed. If the DD
- ID matches an existing DD and there are no Operating Attributes, then
- the DD SHALL be removed and a success Status Code returned. Any
- existing members of that DD SHALL remain in the iSNS database without
- membership in the just-removed DD.
-
- If the DD ID matches an existing DD and there are Operating
- Attributes matching DD members, then the DD members identified by the
- Operating Attributes SHALL be removed from the DD and a successful
- Status Code returned.
-
-
-
-
-Tseng, et al. Standards Track [Page 59]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- If a DD Member iSCSI Name identified in the Operating Attributes
- contains an iSCSI Name for a Storage Node that is not currently
- registered in the iSNS database or contained in another DD, then the
- association between that Storage Node and its pre-assigned iSCSI Node
- Index SHALL be removed. The pre-assigned iSCSI Node Index value no
- longer has an association to a specific iSCSI Name and can now be
- re-assigned.
-
- If a DD Member Portal IP Address and DD Member TCP/UDP Port
- identified in the Operating Attributes reference a Portal that is not
- currently registered in the iSNS database or contained in another DD,
- then the association between that Portal and its pre-assigned Portal
- Index SHALL be removed. The pre-assigned Portal Index value can now
- be reassigned.
-
- The attempted deregistration of non-existent DD entries SHALL not be
- considered an error.
-
-5.6.5.11. DDS Register (DDSReg)
-
- The DDSReg message type is 0x000B. This message allows an iSNS
- client to create a new Discovery Domain Set (DDS), to update an
- existing DDS Symbolic Name and/or DDS Status, or to add DDS members.
-
- DDSs are uniquely defined using DDS_IDs. DDS registration attributes
- are described in Section 6.11.1.
-
- The DDSReg message PDU Payload contains the Source Attribute and,
- optionally, Message Key and Operating Attributes.
-
- The Message Key, if used, contains the DDS_ID of the Discover Domain
- Set to be registered or modified. If the Message Key contains a
- DDS_ID of an existing DDS entry in the iSNS database, then the DDSReg
- message SHALL attempt to update the existing entry. If the DDS_ID in
- the Message Key (if used) does not match an existing DDS entry, then
- the iSNS server SHALL reject the DDSReg message with a status code of
- 3 (Invalid Registration). If the DDS_ID is included in both the
- Message Key and Operating Attributes, then the DDS_ID value in the
- Message Key MUST be the same as the DDS_ID value in the Operating
- Attributes.
-
- A DDSReg message with no Message Key SHALL result in the attempted
- creation of a new Discovery Domain Set (DDS). If the DDS_ID
- attribute (with non-zero length) is included among the Operating
- Attributes in the DDSReg message, then the new Discovery Domain Set
- SHALL be assigned the value contained in that DDS_ID attribute.
- Otherwise, if the DDS_ID attribute is not contained among the
- Operating Attributes of the DDSReg message, or if the DDS_ID is an
-
-
-
-Tseng, et al. Standards Track [Page 60]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- operating attribute with a TLV length of 0, then the iSNS server
- SHALL assign a DDS_ID value. The assigned DDS_ID value is then
- returned in the DDSReg Response message. The Operating Attributes
- can also contain the DDS_Symbolic_Name, the DDS Status, and the
- DD_IDs of Discovery Domains to be added to the DDS.
-
- When creating a new DDS, if the DDS Symbolic Name is included in the
- Operating Attributes and its value is unique (i.e., it does not match
- the registered DDS Symbolic Name for another DDS), then the value
- SHALL be stored in the iSNS database as the DDS Symbolic Name for
- that DDS. If the value for the DDS Symbolic Name is not unique, then
- the iSNS server SHALL reject the attempted DDS registration with a
- status code of 3 (Invalid Registration).
-
- When creating a new DDS, if the DDS Symbolic Name is not included in
- the Operating Attributes, or if it is included with a zero-length
- TLV, then the iSNS server SHALL provide a unique DDS Symbolic Name
- value for the created DDS. The assigned DDS Symbolic Name value
- SHALL be returned in the DDSRegRsp message.
-
- This message SHALL add any DD_IDs listed as Operating Attributes to
- the Discovery Domain Set specified by the DDS_ID Message Key
- Attribute. In addition, if the DDS_Symbolic_Name is an operating
- attribute and the value is unique, then it SHALL be stored in the
- iSNS database as the DDS_Symbolic_Name for the specified Discovery
- Domain Set.
-
- If a DD_ID listed in the Operating Attributes does not match an
- existing DD, then a new DD using the DD_ID SHALL be created. In this
- case for the new DD, the iSNS server SHALL assign a unique value for
- the DD Symbolic Name and SHALL set the DD Features attribute to the
- default value of 0. These assigned values SHALL be returned in the
- DDSRegRsp message.
-
-5.6.5.12. DDS Deregister (DDSDereg)
-
- The DDSDereg message type is 0x000C. This message allows an iSNS
- client to deregister an existing Discovery Domain Set (DDS) or to
- remove some DDs from an existing DDS.
-
- The DDSDereg message PDU Payload contains a Source Attribute, a
- Message Key Attribute, and optional Operating Attributes.
-
- The Message Key Attribute for a DDSDereg message is the DDS ID for
- the DDS being removed or having members removed. If the DDS ID
- matches an existing DDS and there are no Operating Attributes, then
-
-
-
-
-
-Tseng, et al. Standards Track [Page 61]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- the DDS SHALL be removed and a success Status Code returned. Any
- existing members of that DDS SHALL remain in the iSNS database
- without membership in the just-removed DDS.
-
- If the DDS ID matches an existing DDS, and there are Operating
- Attributes matching DDS members, then the DDS members SHALL be
- removed from the DDS and a success Status Code returned.
-
- The attempted deregistration of non-existent DDS entries SHALL not be
- considered an error.
-
-5.6.5.13. Entity Status Inquiry (ESI)
-
- The ESI message type is 0x000D. This message is sent by the iSNS
- server, and is used to verify that an iSNS client Portal is reachable
- and available. The ESI message is sent to the ESI UDP port provided
- during registration, or to the TCP connection used for ESI
- registration, depending on which communication type that is being
- used.
-
- The ESI message PDU Payload contains the following attributes in TLV
- format and in the order listed: the current iSNS timestamp, the EID,
- the Portal IP Address, and the Portal TCP/UDP Port. The format of
- this message is shown below:
-
- +----------------------------------------+
- | Timestamp |
- +----------------------------------------+
- | Entity_ID |
- +----------------------------------------+
- | Portal IP Address |
- +----------------------------------------+
- | Portal TCP/UDP Port |
- +----------------------------------------+
-
- The ESI response message PDU Payload contains a status code, followed
- by the Attributes from the original ESI message.
-
- If the Portal fails to respond to an administratively-determined
- number of consecutive ESI messages, then the iSNS server SHALL remove
- that Portal from the iSNS database. If there are no other remaining
- ESI-monitored Portals for the associated Network Entity, then the
- Network Entity SHALL also be removed. The appropriate State Change
- Notifications, if any, SHALL be triggered.
-
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 62]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-5.6.5.14. Name Service Heartbeat (Heartbeat)
-
- This message, if used, is only sent by the active iSNS server. It
- allows iSNS clients and backup servers listening to a broadcast or
- multicast address to discover the IP address of the primary and
- backup iSNS servers. It also allows concerned parties to monitor the
- health and status of the primary iSNS server.
-
- This message is NOT in TLV format. There is no response message to
- the Name Service Heartbeat.
-
- MSb LSb
- 0 31
- +------------------------------------------------+
- | Active Server IP-Address | 16 Bytes
- +------------------------------------------------+
- | iSNS TCP Port | iSNS UDP Port | 4 Bytes
- +------------------------------------------------+
- | Interval | 4 Bytes
- +------------------------------------------------+
- | Counter | 4 Bytes
- +------------------------------------------------+
- | RESERVED | Backup Servers | 4 Bytes
- +------------------------------------------------+
- | Primary Backup Server IP Address(if any) | 16 Bytes
- +------------------------------------------------+
- |Backup TCP Port(if any)|Backup UDP Port(if any) | 4 Bytes
- +------------------------------------------------+
- | 2nd Backup Server IP Address(if any) | 16 Bytes
- +------------------------------------------------+
- |Backup TCP Port(if any)|Backup UDP Port(if any) | 4 Bytes
- +------------------------------------------------+
- | . . . |
- +------------------------------------------------+
- | VENDOR SPECIFIC |
- +------------------------------------------------+
-
- The heartbeat PDU Payload contains the following:
-
- Active Server IP Address: the IP Address of the active iSNS server in
- IPv6 format. When this field contains an IPv4
- value, it is stored as an IPv4-mapped IPv6 address.
- That is, the most significant 10 bytes are set to
- 0x00, with the next two bytes set to 0xFFFF
- [RFC2373]. When this field contains an IPv6 value,
- the entire 16-byte field is used.
-
- Active TCP Port: the TCP Port of the server currently in use.
-
-
-
-Tseng, et al. Standards Track [Page 63]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- Active UDP Port: the UDP Port of the server currently in use,
- otherwise 0.
-
- Interval: the interval, in seconds, of the heartbeat.
-
- Counter: a count that begins at 0 when this server becomes
- active. The count increments by one for each
- heartbeat sent since this server became active.
-
- Backup Servers: the number of iSNS backup servers. The IP address,
- TCP Port, and UDP Port of each iSNS backup server
- follow this field. Note that if backup servers are
- used, then the active iSNS server SHOULD be among
- the list of backup servers.
-
- The content of the remainder of this message after the list of backup
- servers is vendor-specific. Vendors may use additional fields to
- coordinate between multiple iSNS servers, and/or to identify vendor-
- specific features.
-
-5.6.5.15. Request FC_DOMAIN_ID (RqstDomId)
-
- The RqstDomId message type is 0x0011. This message is used for iFCP
- Transparent Mode to allocate non-overlapping FC_DOMAIN_ID values
- between 1 and 239. The iSNS server becomes the address assignment
- authority for the entire iFCP fabric. To obtain multiple
- FC_DOMAIN_ID values, this request must be repeated to the iSNS server
- multiple times. iSNS clients that acquire FC_DOMAIN_ID values from
- an iSNS server MUST register for ESI monitoring from that iSNS
- server.
-
- The RqstDomId PDU Payload contains three TLV attributes in the
- following order: the requesting Switch Name (WWN) as the Source
- Attribute, the Virtual_Fabric_ID as the Message Key Attribute, and
- Preferred ID as the operating attribute. The Virtual_Fabric_ID is a
- string identifying the domain space for which the iSNS server SHALL
- allocate non-overlapping integer FC_DOMAIN_ID values between 1 and
- 239. The Preferred_ID is the nominal FC_DOMAIN_ID value requested by
- the iSNS client. If the Preferred_ID value is available and has not
- already been allocated for the Virtual_Fabric_ID specified in the
- message, the iSNS server SHALL return the requested Preferred_ID
- value as the Assigned_ID to the requesting client.
-
- The RqstDomId response contains a Status Code, and the TLV attribute
- Assigned ID, which contains the integer value in the space requested.
- If no further unallocated values are available from this space, the
- iSNS server SHALL respond with the Status Code 18 "FC_DOMAIN_ID Not
- Available".
-
-
-
-Tseng, et al. Standards Track [Page 64]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- Once a FC_DOMAIN_ID value has been allocated to an iSNS client by the
- iSNS server for a given Virtual_Fabric_ID, that FC_DOMAIN_ID value
- SHALL NOT be reused until it has been deallocated, or until ESI
- monitoring detects that the iSNS client no longer exists on the
- network and objects for that client are removed from the iSNS
- database.
-
- The iSNS server and client SHALL use TCP to transmit and receive
- RqstDomId, RqstDomIdRsp, RlseDomId, and RlseDomIdRsp messages.
-
-5.6.5.16. Release FC_DOMAIN_ID (RlseDomId)
-
- The RlseDomId message type is 0x0012. This message may be used by
- iFCP Transparent Mode to release integer identifier values used to
- assign 3-byte Fibre Channel PORT_ID values.
-
- The RlseDomId message contains three TLV attributes in the following
- order: the requesting EID as the Source Attribute, the
- Virtual_Fabric_ID as the Message Key Attribute, and Assigned_ID as
- the operating attribute. Upon receiving the RlseDomId message, the
- iSNS server SHALL deallocate the FC_DOMAIN_ID value contained in the
- Assigned_ID attribute for the Virtual_Fabric_ID attribute specified.
- Upon deallocation, that FC_DOMAIN_ID value can then be requested by
- and assigned to a different iSNS client.
-
- The iSNS server and client SHALL use TCP to transmit and receive
- RqstDomId, RqstDomIdRsp, RlseDomId, and RlseDomIdRsp messages.
-
-5.6.5.17. Get FC_DOMAIN_IDs (GetDomId)
-
- The GetDomId message type is 0x0013. This message is used to learn
- the currently-allocated FC_DOMAIN_ID values for a given
- Virtual_Fabric_ID.
-
- The GetDomId message PDU Payload contains a Source Attribute and
- Message Key Attribute.
-
- The Message Key Attribute for the GetDomId message is the
- Virtual_Fabric_ID. The response to this message returns all the
- FC_DOMAIN_ID values that have been allocated for the
- Virtual_Fabric_ID specified.
-
-
-
-
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 65]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-5.7. Messages
-
- The iSNSP response message PDU Payloads contain a Status Code,
- followed by a list of attributes, and have the following format:
-
- MSb LSb
- 0 31
- +----------------------------------------+
- | 4-byte STATUS CODE |
- +----------------------------------------+
- | Message Key Attribute[1] (if present) |
- +----------------------------------------+
- | Message Key Attribute[2] (if present) |
- +----------------------------------------+
- | . . . |
- +----------------------------------------+
- | - Delimiter Attribute - (if present) |
- +----------------------------------------+
- | Operating Attribute[1] (if present) |
- +----------------------------------------+
- | Operating Attribute[2] (if present) |
- +----------------------------------------+
- | Operating Attribute[3] (if present) |
- +----------------------------------------+
- | . . . |
- +----------------------------------------+
-
- The iSNSP Response messages SHALL be sent to the iSNS Client IP
- Address and the originating TCP/UDP Port that was used for the
- associated registration and query message.
-
-5.7.1. Status Code
-
- The first field in an iSNSP response message PDU Payload is the
- Status Code for the operation that was performed. The Status Code
- encoding is defined in Section 5.4.
-
-5.7.2. Message Key Attributes in Response
-
- Depending on the specific iSNSP request, the response message MAY
- contain Message Key Attributes. Message Key Attributes generally
- contain the interesting key attributes that are affected by the
- operation specified in the original iSNS registration or query
- message.
-
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 66]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-5.7.3. Delimiter Attribute in Response
-
- The Delimiter Attribute separates the key and Operating Attributes in
- a response message, if they exist. The Delimiter Attribute has a tag
- value of 0 and a length value of 0. The Delimiter Attribute is
- effectively 8 bytes long: a 4-byte tag containing 0x00000000, and a 4
- Byte length field containing 0x00000000.
-
-5.7.4. Operating Attributes in Response
-
- The Operating Attributes in a response are the results related to the
- iSNS registration or query operation being performed. Some response
- messages will not have Operating Attributes.
-
-5.7.5. Registration and Query Response Message Types
-
- The following sections describe each query and message type.
-
-5.7.5.1. Device Attribute Registration Response (DevAttrRegRsp)
-
- The DevAttrRegRsp message type is 0x8001. The DevAttrRegRsp message
- contains the results for the DevAttrReg message with the same
- TRANSACTION ID.
-
- The Message Key in the DevAttrRegRsp message SHALL return the Message
- Key in the original registration message. If the iSNS server
- assigned the Entity Identifier for a Network Entity, then the Message
- Key Attribute field SHALL contain the assigned Entity Identifier.
-
- The Operating Attributes of the DevAttrRegRsp message SHALL contain
- the affected object's key and non-key attributes that have been
- explicitly modified or created by the original DevAttrReg message.
- Among the Operating Attributes, each modified or added non-key
- attribute SHALL be listed after its key attribute(s) in the
- DevAttrRegRsp message. Implicitly registered attributes MUST NOT be
- returned in the DevAttrRegRsp message. Implicitly registered
- attributes are those that are assigned a fixed default value or
- secondary index value by the iSNS server.
-
- Implicitly registered PG objects (i.e., PG objects that are not
- explicitly included in the registration or replace message) MUST NOT
- have their key or non-key attributes returned in the DevAttrRegRsp
- message. However, explicitly registered PG objects (i.e., those with
- PGT values that are explicitly included in the registration or
- replace message) SHALL have their PGT values returned in the
- DevAttrRegRsp message.
-
-
-
-
-
-Tseng, et al. Standards Track [Page 67]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- For example, three Portals are registered in the original DevAttrReg
- request message. Due to lack of resources, the iSNS server needs to
- modify the registered ESI Interval value of one of those Portals. To
- accomplish this, the iSNS server returns the key attributes
- identifying the Portal, followed by the non-key modified ESI Interval
- attribute value, as Operating Attributes of the corresponding
- DevAttrRegRsp message.
-
- If the iSNS server rejects a registration due to invalid attribute
- values or types, then the indicated status code SHALL be 3 (Invalid
- Registration). If this occurs, then the iSNS server MAY include the
- list of invalid attributes in the Operating Attributes of the
- DevAttrRsp message.
-
- Some attributes values (e.g., ESI Interval, Registration Period) in
- the original registration message MAY be modified by the iSNS server.
- This can occur only for a limited set of attribute types, as
- indicated in the table in Section 6.1. When this occurs, the
- registration SHALL be considered a success (with status code 0), and
- the changed value(s) indicated in the Operating Attributes of the
- DevAttrRsp message.
-
-5.7.5.2. Device Attribute Query Response (DevAttrQryRsp)
-
- The DevAttrQryRsp message type is 0x8002. The DevAttrQryRsp message
- contains the results for the DevAttrQry message with the same
- TRANSACTION ID.
-
- The Message Key in the DevAttrQryRsp message SHALL return the Message
- Key in the original query message.
-
- If no Operating Attributes are included in the original query, then
- all Operating Attributes SHALL be returned in the response.
-
- For a successful query result, the DevAttrQryRsp Operating Attributes
- SHALL contain the results of the original DevAttrQry message.
-
-5.7.5.3. Device Get Next Response (DevGetNextRsp)
-
- The DevGetNextRsp message type is 0x8003. The DevGetNextRsp message
- contains the results for the DevGetNext message with the same
- TRANSACTION ID.
-
- The Message Key Attribute field returns the object keys for the next
- object after the Message Key Attribute in the original DevGetNext
- message.
-
-
-
-
-
-Tseng, et al. Standards Track [Page 68]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- The Operating Attribute field returns the Operating Attributes of the
- next object as requested in the original DevGetNext message. The
- values of the Operating Attributes are those associated with the
- object identified by the Message Key Attribute field of the
- DevGetNextRsp message.
-
-5.7.5.4. Deregister Device Response (DevDeregRsp)
-
- The DevDeregRsp message type is 0x8004. This message is the response
- to the DevDereg request message.
-
- This message response does not contain a Message Key, but MAY contain
- Operating Attributes.
-
- In the event of an error, this response message contains the
- appropriate status code as well as a list of objects from the
- original DevDereg message that were not successfully deregistered
- from the iSNS database. This list of objects is contained in the
- Operating Attributes of the DevDeregRsp message. Note that an
- attempted deregistration of a non-existent object does not constitute
- an error, and non-existent entries SHALL not be returned in the
- DevDeregRsp message.
-
-5.7.5.5. SCN Register Response (SCNRegRsp)
-
- The SCNRegRsp message type is 0x8005. This message is the response
- to the SCNReg request message.
-
- The SCNRegRsp message does not contain any Message Key or Operating
- Attributes.
-
-5.7.5.6. SCN Deregister Response (SCNDeregRsp)
-
- The SCNDeregRsp message type is 0x8006. This message is the response
- to the SCNDereg request message.
-
- The SCNDeregRsp message does not contain any Message Key or Operating
- Attributes.
-
-5.7.5.7. SCN Event Response (SCNEventRsp)
-
- The SCNEventRsp message type is 0x8007. This message is the response
- to the SCNEvent request message.
-
- The SCNEventRsp message does not contain any Message Key or Operating
- Attributes.
-
-
-
-
-
-Tseng, et al. Standards Track [Page 69]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-5.7.5.8. SCN Response (SCNRsp)
-
- The SCNRsp message type is 0x8008. This message is sent by an iSNS
- client, and provides confirmation that the SCN message was received
- and processed.
-
- The SCNRsp response contains the SCN Destination Attribute
- representing the Node identifier that received the SCN.
-
-5.7.5.9. DD Register Response (DDRegRsp)
-
- The DDRegRsp message type is 0x8009. This message is the response to
- the DDReg request message.
-
- The Message Key in the DDRegRsp message SHALL return the Message Key
- in the original query message. If the original DDReg message did not
- have a Message Key, then the DDRegRsp message SHALL not have a
- Message Key.
-
- If the DDReg operation is successful, the DD ID of the DD created or
- updated SHALL be returned as an operating attribute of the message.
-
- If the DD Symbolic Name attribute or DD Features attribute was
- assigned or updated during the DDReg operation, then any new values
- SHALL be returned as an operating attribute of the DDRegRsp message.
-
- If the iSNS server rejects a DDReg due to invalid attribute values or
- types, then the indicated status code SHALL be 3 (Invalid
- Registration). If this occurs, then the iSNS server MAY include the
- list of invalid attributes in the Operating Attributes of the
- DDRegRsp message.
-
-5.7.5.10. DD Deregister Response (DDDeregRsp)
-
- The DDDeregRsp message type is 0x800A. This message is the response
- to the DDDereg request message.
-
- The DDDeregRsp message does not contain any Message Key or Operating
- Attributes.
-
-
-
-
-
-
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 70]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-5.7.5.11. DDS Register Response (DDSRegRsp)
-
- The DDSRegRsp message type is 0x800B. This message is the response
- to the DDSReg request message.
-
- The Message Key in the DDSRegRsp message SHALL contain the Message
- Key of the original DDSReg message. If the original DDSReg message
- did not have a Message Key, then the DDSRegRsp message SHALL NOT have
- a Message Key.
-
- If the DDSReg operation is successful, the DDS ID of the DDS created
- or updated SHALL be returned as an operating attribute of the
- message.
-
- If the DDS Symbolic Name attribute or DDS Status attribute was
- assigned or updated during the DDSRegRsp operation, then any new
- values SHALL be returned as an operating attribute of the DDSRegRsp
- message.
-
- If the iSNS server rejects a DDSReg due to invalid attribute values
- or types, then the indicated status code SHALL be 3 (Invalid
- Registration). If this occurs, then the iSNS server MAY include the
- list of invalid attributes in the Operating Attributes of the
- DDSRegRsp message.
-
-5.7.5.12. DDS Deregister Response (DDSDeregRsp)
-
- The DDSDeregRsp message type is 0x800C. This message is the response
- to the DDSDereg request message.
-
- The DDSDeregRsp message does not contain any Message Key or Operating
- Attributes.
-
-5.7.5.13. Entity Status Inquiry Response (ESIRsp)
-
- The ESIRsp message type is 0x800D. This message is sent by an iSNS
- client and provides confirmation that the ESI message was received
- and processed.
-
- The ESIRsp response message PDU Payload contains the attributes from
- the original ESI message. These attributes represent the Portal that
- is responding to the ESI. The ESIRsp Attributes are in the order
- they were provided in the original ESI message.
-
- Upon receiving the ESIRsp from the iSNS client, the iSNS server SHALL
- update the timestamp attribute for that Network Entity and Portal.
-
-
-
-
-
-Tseng, et al. Standards Track [Page 71]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-5.7.5.14. Request FC_DOMAIN_ID Response (RqstDomIdRsp)
-
- The RqstDomIdRsp message type is 0x8011. This message provides the
- response for RqstDomId.
-
- The RqstDomId response contains a Status Code and the TLV attribute
- Assigned ID, which contains the integer value in the space requested.
- If no further unallocated values are available from this space, the
- iSNS server SHALL respond with the Status Code 19 "FC_DOMAIN_ID Not
- Available".
-
- Once a FC_DOMAIN_ID value is allocated by the iSNS server, it SHALL
- NOT be reused until it has been deallocated by the iSNS client to
- which the value was assigned, or until the ESI message detects that
- the iSNS client no longer exists on the network.
-
- The iSNS server and client SHALL use TCP to transmit and receive
- RqstDomId, RqstDomIdRsp, RlseDomId, and RlseDomIdRsp messages.
-
-5.7.5.15. Release FC_DOMAIN_ID Response (RlseDomIdRsp)
-
- The RlseDomIdRsp message type is 0x8012. This message provides the
- response for RlseDomId. The response contains an Error indicating
- whether the request was successful. If the Assigned_ID value in the
- original RlseDomId message is not allocated, then the iSNS server
- SHALL respond with this message using the Status Code 20
- "FC_DOMAIN_ID Not Allocated".
-
- The iSNS server and client SHALL use TCP to transmit and receive
- RqstDomId, RqstDomIdRsp, RlseDomId, and RlseDomIdRsp messages.
-
-5.7.5.16. Get FC_DOMAIN_IDs Response (GetDomIdRsp)
-
- The GetDomIdRsp message type is 0x8013. This message is used to
- determine which FC_DOMAIN_ID values have been allocated for the
- Virtual_Fabric_ID specified in the original GetDomId request message.
-
- The GetDomId response message PDU Payload contains a Status Code
- indicating whether the request was successful, and a list of the
- Assigned IDs from the space requested. The Assigned_ID attributes
- are listed in TLV format.
-
-5.8. Vendor-Specific Messages
-
- Vendor-specific iSNSP messages have a functional ID of between 0x0100
- and 0x01FF, whereas vendor-specific responses have a functional ID of
- between 0x8100 and 0x81FF. The first Message Key Attribute in a
-
-
-
-
-Tseng, et al. Standards Track [Page 72]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- vendor-specific message SHALL be the company OUI (tag=256)
- identifying the original creator of the proprietary iSNSP message.
- The contents of the remainder of the message are vendor-specific.
-
-6. iSNS Attributes
-
- Attributes can be stored in the iSNS server using iSNSP registration
- messages, and they can be retrieved using iSNSP query messages.
- Unless otherwise indicated, these attributes are supplied by iSNS
- clients using iSNSP registration messages.
-
-6.1. iSNS Attribute Summary
-
- The complete registry of iSNS attributes is maintained by IANA, and
- the following table summarizes the initial set of iSNS attributes
- available at the time of publication of this document.
-
- Attributes Length Tag Reg Key Query Key
- ---------- ------ --- ------- ---------
- Delimiter 0 0 N/A N/A
- Entity Identifier (EID) 4-256 1 1 1|2|16&17|32|64
- Entity Protocol 4 2 1 1|2|16&17|32|64
- Management IP Address 16 3 1 1|2|16&17|32|64
- Timestamp 8 4 -- 1|2|16&17|32|64
- Protocol Version Range 4 5 1 1|2|16&17|32|64
- Registration Period 4 6 1 1|2|16&17|32|64
- Entity Index 4 7 1 1|2|16&17|32|64
- Entity Next Index 4 8 -- 1|2|16&17|32|64
- Entity ISAKMP Phase-1 var 11 1 1|2|16&17|32|64
- Entity Certificate var 12 1 1|2|16&17|32|64
- Portal IP Address 16 16 1 1|16&17|32|64
- Portal TCP/UDP Port 4 17 1 1|16&17|32|64
- Portal Symbolic Name 4-256 18 16&17 1|16&17|32|64
- ESI Interval 4 19 16&17 1|16&17|32|64
- ESI Port 4 20 16&17 1|16&17|32|64
- Portal Index 4 22 16&17 1|16&17|32|64
- SCN Port 4 23 16&17 1|16&17|32|64
- Portal Next Index 4 24 -- 1|16&17|32|64
- Portal Security Bitmap 4 27 16&17 1|16&17|32|64
- Portal ISAKMP Phase-1 var 28 16&17 1|16&17|32|64
- Portal ISAKMP Phase-2 var 29 16&17 1|16&17|32|64
- Portal Certificate var 31 16&17 1|16&17|32|64
- iSCSI Name 4-224 32 1 1|16&17|32|33
- iSCSI Node Type 4 33 32 1|16&17|32
- iSCSI Alias 4-256 34 32 1|16&17|32
- iSCSI SCN Bitmap 4 35 32 1|16&17|32
- iSCSI Node Index 4 36 32 1|16&17|32
- WWNN Token 8 37 32 1|16&17|32
-
-
-
-Tseng, et al. Standards Track [Page 73]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- iSCSI Node Next Index 4 38 -- 1|16&17|32
- iSCSI AuthMethod var 42 32 1|16&17|32
- PG iSCSI Name 4-224 48 32|16&17 1|16&17|32|52
- PG Portal IP Addr 16 49 32|16&17 1|16&17|32|52
- PG Portal TCP/UDP Port 4 50 32|16&17 1|16&17|32|52
- PG Tag (PGT) 4 51 32|16&17 1|16&17|32|52
- PG Index 4 52 32|16&17 1|16&17|32|52
- PG Next Index 4 53 -- 1|16&17|32|52
- FC Port Name WWPN 8 64 1 1|16&17|64|66|96|128
- Port ID 4 65 64 1|16&17|64
- FC Port Type 4 66 64 1|16&17|64
- Symbolic Port Name 4-256 67 64 1|16&17|64
- Fabric Port Name 8 68 64 1|16&17|64
- Hard Address 4 69 64 1|16&17|64
- Port IP-Address 16 70 64 1|16&17|64
- Class of Service 4 71 64 1|16&17|64
- FC-4 Types 32 72 64 1|16&17|64
- FC-4 Descriptor 4-256 73 64 1|16&17|64
- FC-4 Features 128 74 64 1|16&17|64
- iFCP SCN bitmap 4 75 64 1|16&17|64
- Port Role 4 76 64 1|16&17|64
- Permanent Port Name 8 77 -- 1|16&17|64
- FC-4 Type Code 4 95 -- 1|16&17|64
- FC Node Name WWNN 8 96 64 1|16&17|64|96
- Symbolic Node Name 4-256 97 96 64|96
- Node IP-Address 16 98 96 64|96
- Node IPA 8 99 96 64|96
- Proxy iSCSI Name 4-256 101 96 64|96
- Switch Name 8 128 128 128
- Preferred ID 4 129 128 128
- Assigned ID 4 130 128 128
- Virtual_Fabric_ID 4-256 131 128 128
- iSNS Server Vendor OUI 4 256 -- SOURCE Attribute
- Vendor-Spec iSNS Srvr 257-384 -- SOURCE Attribute
- Vendor-Spec Entity 385-512 1 1|2|16&17|32|64
- Vendor-Spec Portal 513-640 16&17 1|16&17|32|64
- Vendor-Spec iSCSI Node 641-768 32 16&17|32
- Vendor-Spec FC Port Name 769-896 64 1|16&17|64
- Vendor-Spec FC Node Name 897-1024 96 64|96
- Vendor-Specific DDS 1025-1280 2049 2049
- Vendor-Specific DD 1281-1536 2065 2065
- Other Vendor-Specific 1537-2048
- DD_Set ID 4 2049 2049 1|32|64|2049|2065
- DD_Set Sym Name 4-256 2050 2049 2049
- DD_Set Status 4 2051 2049 2049
- DD_Set_Next_ID 4 2052 -- 2049
- DD_ID 4 2065 2049 1|32|64|2049|2065
- DD_Symbolic Name 4-256 2066 2065 2065
-
-
-
-Tseng, et al. Standards Track [Page 74]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- DD_Member iSCSI Index 4 2067 2065 2065
- DD_Member iSCSI Name 4-224 2068 2065 2065
- DD_Member FC Port Name 8 2069 2065 2065
- DD_Member Portal Index 4 2070 2065 2065
- DD_Member Portal IP Addr 16 2071 2065 2065
- DD_Member Portal TCP/UDP 4 2072 2065 2065
- DD_Features 4 2078 2065 2065
- DD_ID Next ID 4 2079 -- 2065
-
- The following are descriptions of the columns used in the above
- table:
-
- Length: indicates the attribute length in bytes used for the TLV
- format. Variable-length identifiers are NULL-terminated
- and 4-byte aligned (NULLs are included in the length).
-
- Tag: the IANA-assigned integer tag value used to identify the
- attribute. All undefined tag values are reserved.
-
- Reg Key: indicates the tag values for the object key in DevAttrReg
- messages for registering a new attribute value in the
- database. These tags represent attributes defined as
- object keys in Section 4.
-
- Query Key: indicates the possible tag values for the Message Key and
- object key that are used in the DevAttrQry messages for
- retrieving a stored value from the iSNS database.
-
- The following is a summary of iSNS attribute tag values available for
- future allocation by IANA at the time of publication:
-
- Tag Values Reg Key Query Key
- ---------- ------- ---------
- 9-10, 13-15 1 1|2|16&17|32|64
- 21, 25-26, 30 16&17 1|16&17|32|64
- 39-41, 44-47 32 1|16&17|32
- 54-63 32|16&17 1|16&17|32|52
- 78-82, 85-94 64 1|16&17|64
- 102-127 96 64|96
- 132-255 -- SOURCE Attribute
- 2053-2064 2049 2049
- 2073-2077 2065 2065
- 2080-65535 To be assigned To be assigned
-
- Registration and query keys for attributes with tags in the range
- 2080 to 65535 are to be documented in the RFC introducing the new
- iSNS attributes. IANA will maintain registration of these values as
- required by the new RFC.
-
-
-
-Tseng, et al. Standards Track [Page 75]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- New iSNS attributes with any of the above tag values MAY also be
- designated as "read-only" attributes. The new RFC introducing these
- attributes as "read-only" SHALL document them as such, and IANA will
- record their corresponding Registration Keys (Reg Keys) as "--".
-
-6.2. Entity Identifier-Keyed Attributes
-
- The following attributes are stored in the iSNS server using the
- Entity Identifier attribute as the key.
-
-6.2.1. Entity Identifier (EID)
-
- The Entity Identifier (EID) is variable-length UTF-8 encoded NULL-
- terminated text-based description for a Network Entity. This key
- attribute uniquely identifies each Network Entity registered in the
- iSNS server. The attribute length varies from 4 to 256 bytes
- (including the NULL termination), and is a unique value within the
- iSNS server.
-
- If the iSNS client does not provide an EID during registration, the
- iSNS server SHALL generate one that is unique within the iSNS
- database. If an EID is to be generated, then the EID attribute value
- in the registration message SHALL be empty (0 length). The generated
- EID SHALL be returned in the registration response.
-
- In environments where the iSNS server is integrated with a DNS
- infrastructure, the Entity Identifier may be used to store the Fully
- Qualified Domain Name (FQDN) of the iSCSI or iFCP device. FQDNs of
- greater than 255 bytes MUST NOT be used.
-
- If FQDNs are not used, the iSNS server can be used to generate EIDs.
- EIDs generated by the iSNS server MUST begin with the string "isns:".
- iSNS clients MUST NOT generate and register EIDs beginning with the
- string "isns:".
-
- This field MUST be normalized according to the nameprep template
- [NAMEPREP] before it is stored in the iSNS database.
-
-6.2.2. Entity Protocol
-
- The Entity Protocol is a required 4-byte integer attribute that
- indicates the block storage protocol used by the registered NETWORK
- ENTITY. Values used for this attribute are assigned and maintained
- by IANA. The initial set of protocols supported by iSNS is as
- follows:
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 76]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- Value Entity Protocol Type
- ----- --------------------
- 1 No Protocol
- 2 iSCSI
- 3 iFCP
- All others To be assigned by IANA
-
- 'No Protocol' is used to indicate that the Network Entity does not
- support an IP block storage protocol. A Control Node or monitoring
- Node would likely (but not necessarily) use this value.
-
- This attribute is required during initial registration of the Network
- Entity.
-
-6.2.3. Management IP Address
-
- This field contains the IP Address that may be used to manage the
- Network Entity and all Storage Nodes contained therein via the iSNS
- MIB [iSNSMIB]. Some implementations may also use this IP address to
- support vendor-specific proprietary management protocols. The
- Management IP Address is a 16-byte field that may contain an IPv4 or
- IPv6 address. When this field contains an IPv4 value, it is stored
- as an IPv4-mapped IPv6 address. That is, the most significant 10
- bytes are set to 0x00, with the next two bytes set to 0xFFFF
- [RFC2373]. When this field contains an IPv6 value, the entire 16-
- byte field is used. If this field is not set, then in-band
- management through the IP address of one of the Portals of the
- Network Entity is assumed.
-
-6.2.4. Entity Registration Timestamp
-
- This field indicates the most recent time when the Network Entity
- registration occurred or when an associated object attribute was
- updated or queried by the iSNS client registering the Network Entity.
- The time format is, in seconds, the update period since the standard
- base time of 00:00:00 GMT on January 1, 1970. This field cannot be
- explicitly registered. This timestamp TLV format is also used in the
- SCN and ESI messages.
-
-6.2.5. Protocol Version Range
-
- This field contains the minimum and maximum version of the block
- storage protocol supported by the Network Entity. The most
- significant two bytes contain the maximum version supported, and the
- least significant two bytes contain the minimum version supported.
- If a range is not registered, then the Network Entity is assumed to
-
-
-
-
-
-Tseng, et al. Standards Track [Page 77]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- support all versions of the protocol. The value 0xffff is a wildcard
- that indicates no minimum or maximum. If the Network Entity does not
- support a protocol, then this field SHALL be set to 0.
-
-6.2.6. Registration Period
-
- This 4-byte unsigned integer field indicates the maximum period, in
- seconds, that the registration SHALL be maintained by the server
- without receipt of an iSNS message from the iSNS client that
- registered the Network Entity. Entities that are not registered for
- ESI monitoring MUST have a non-zero Registration Period. If a
- Registration Period is not requested by the iSNS client and Entity
- Status Inquiry (ESI) messages are not enabled for that client, then
- the Registration Period SHALL be set to a non-zero value by the iSNS
- server. This implementation-specific value for the Registration
- Period SHALL be returned in the registration response to the iSNS
- client. The Registration Period may be set to zero, indicating its
- non-use, only if ESI messages are enabled for that Network Entity.
-
- The registration SHALL be removed from the iSNS database if an iSNS
- Protocol message is not received from the iSNS client before the
- registration period has expired. Receipt of any iSNS Protocol
- message from the iSNS client automatically refreshes the Entity
- Registration Period and Entity Registration Timestamp. To prevent a
- registration from expiring, the iSNS client should send an iSNS
- Protocol message to the iSNS server at intervals shorter than the
- registration period. Such a message can be as simple as a query for
- one of its own attributes, using its associated iSCSI Name or FC Port
- Name WWPN as the Source attribute.
-
- For an iSNS client that is supporting a Network Entity with multiple
- Storage Node objects, receipt of an iSNS message from any Storage
- Node of that Network Entity is sufficient to refresh the registration
- for all Storage Node objects of the Network Entity.
-
- If ESI support is requested as part of a Portal registration, the ESI
- Response message received from the iSNS client by the iSNS server
- SHALL refresh the registration.
-
-6.2.7. Entity Index
-
- The Entity Index is an unsigned non-zero integer value that uniquely
- identifies each Network Entity registered in the iSNS server. Upon
- initial registration of a Network Entity, the iSNS server assigns an
- unused value for the Entity Index. Each Network Entity in the iSNS
- database MUST be assigned a value for the Entity Index that is not
-
-
-
-
-
-Tseng, et al. Standards Track [Page 78]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- assigned to any other Network Entity. Furthermore, Entity Index
- values for recently deregistered Network Entities SHOULD NOT be
- reused in the short term.
-
- The Entity Index MAY be used to represent the Network Entity in
- situations when the Entity Identifier is too long or otherwise
- inappropriate. An example of this is when SNMP is used for
- management, as described in Section 2.10.
-
-6.2.8. Entity Next Index
-
- This is a virtual attribute containing a 4-byte integer value that
- indicates the next available (i.e., unused) Entity Index value. This
- attribute may only be queried; the iSNS server SHALL return an error
- code of 3 (Invalid Registration) to any client that attempts to
- register a value for this attribute. A Message Key is not required
- when exclusively querying for this attribute.
-
- The Entity Next Index MAY be used by an SNMP client to create an
- entry in the iSNS server. SNMP requirements are described in Section
- 2.10.
-
-6.2.9. Entity ISAKMP Phase-1 Proposals
-
- This field contains the IKE Phase-1 proposal, listing in decreasing
- order of preference the protection suites acceptable to protect all
- IKE Phase-2 messages sent and received by the Network Entity. This
- includes Phase-2 SAs from the iSNS client to the iSNS server as well
- as to peer iFCP and/or iSCSI devices. This attribute contains the SA
- payload, proposal payload(s), and transform payload(s) in the ISAKMP
- format defined in [RFC2408].
-
- This field should be used if the implementer wishes to define a
- single phase-1 SA security configuration used to protect all phase-2
- IKE traffic. If the implementer desires to have a different phase-1
- SA security configuration to protect each Portal interface, then the
- Portal Phase-1 Proposal (Section 6.3.10) should be used.
-
-6.2.10. Entity Certificate
-
- This attribute contains one or more X.509 certificates that are bound
- to the Network Entity. This certificate is uploaded and registered
- to the iSNS server by clients wishing to allow other clients to
- authenticate themselves and to access the services offered by that
- Network Entity. The format of the X.509 certificate is found in
- [RFC3280]. This certificate MUST contain a Subject Name with an
- empty sequence and MUST contain a SubjectAltName extension encoded
-
-
-
-
-Tseng, et al. Standards Track [Page 79]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- with the dNSName type. The Entity Identifier (Section 6.2.1) of the
- identified Entity MUST be stored in the SubjectAltName field of the
- certificate.
-
-6.3. Portal-Keyed Attributes
-
- The following Portal attributes are registered in the iSNS database
- using the combined Portal IP-Address and Portal TCP/UDP Port as the
- key. Each Portal is associated with one Entity Identifier object
- key.
-
-6.3.1. Portal IP Address
-
- This attribute is the IP address of the Portal through which a
- Storage Node can transmit and receive storage data. The Portal IP
- Address is a 16-byte field that may contain an IPv4 or IPv6 address.
- When this field contains an IPv4 address, it is stored as an IPv4-
- mapped IPv6 address. That is, the most significant 10 bytes are set
- to 0x00, with the next 2 bytes set to 0xFFFF [RFC2373]. When this
- field contains an IPv6 address, the entire 16-byte field is used.
- The Portal IP Address and the Portal TCP/UDP Port number (see 6.3.2
- below) are used as a key to identify a Portal uniquely. It is a
- required attribute for registration of a Portal.
-
-6.3.2. Portal TCP/UDP Port
-
- The TCP/UDP port of the Portal through which a Storage Node can
- transmit and receive storage data. Bits 16 to 31 represents the
- TCP/UDP port number. Bit 15 represents the port type. If bit 15 is
- set, then the port type is UDP. Otherwise it is TCP. Bits 0 to 14
- are reserved.
-
- If the field value is 0, then the port number is the implied
- canonical port number and type of the protocol indicated by the
- associated Entity Type.
-
- The Portal IP Address and the Portal TCP/UDP Port number are used as
- a key to identify a Portal uniquely. It is a required attribute for
- registration of a Portal.
-
-6.3.3. Portal Symbolic Name
-
- A variable-length UTF-8 encoded NULL-terminated text-based
- description of up to 256 bytes. The Portal Symbolic Name is a user-
- readable description of the Portal entry in the iSNS server.
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 80]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-6.3.4. Entity Status Inquiry Interval
-
- This field indicates the requested time, in seconds, between Entity
- Status Inquiry (ESI) messages sent from the iSNS server to this
- Network Entity. ESI messages can be used to verify that a Portal
- registration continues to be valid. To request monitoring by the
- iSNS server, an iSNS client registers a non-zero value for this
- Portal attribute using a DevAttrReg message. The client MUST
- register an ESI Port on at least one of its Portals to receive the
- ESI monitoring.
-
- If the iSNS server does not receive an expected response to an ESI
- message, it SHALL attempt an administratively configured number of
- re-transmissions of the ESI message. The ESI Interval period begins
- with the iSNS server's receipt of the last ESI Response. All re-
- transmissions MUST be sent before twice the ESI Interval period has
- passed. If no response is received from any of the ESI messages,
- then the Portal SHALL be deregistered. Note that only Portals that
- have registered a value in their ESI Port field can be deregistered
- in this way.
-
- If all Portals associated with a Network Entity that have registered
- for ESI messages are deregistered due to non-response, and if no
- registrations have been received from the client for at least two ESI
- Interval periods, then the Network Entity and all associated objects
- (including Storage Nodes) SHALL be deregistered.
-
- If the iSNS server is unable to support ESI messages or the ESI
- Interval requested, it SHALL either reject the ESI request by
- returning an "ESI Not Available" Status Code or modify the ESI
- Interval attribute by selecting its own suitable value and returning
- that value in the Operating Attributes of the registration response
- message.
-
- If at any time an iSNS client that is registered for ESI messages has
- not received an ESI message to any of its Portals as expected, then
- the client MAY attempt to query the iSNS server using a DevAttrQry
- message using its Entity_ID as the key. If the query result is the
- error "no such entry", then the client SHALL close all remaining TCP
- connections to the iSNS server and assume that it is no longer
- registered in the iSNS database. Such a client MAY attempt re-
- registration.
-
-
-
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 81]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-6.3.5. ESI Port
-
- This field contains the TCP or UDP port used for ESI monitoring by
- the iSNS server at the Portal IP Address. Bits 16 to 31 represent
- the port number. If bit 15 is set, then the port type is UDP.
- Otherwise, the port is TCP. Bits 0 to 14 are reserved.
-
- If the iSNS client registers a valid TCP or UDP port number in this
- field, then the client SHALL allow ESI messages to be received at the
- indicated TCP or UDP port. If a TCP port is registered and a pre-
- existing TCP connection from that TCP port to the iSNS server does
- not already exist, then the iSNS client SHALL accept new TCP
- connections from the iSNS server at the indicated TCP port.
-
- The iSNS server SHALL return an error if a Network Entity is
- registered for ESI monitoring and none of the Portals of that Network
- Entity has an entry for the ESI Port field. If multiple Portals have
- a registered ESI port, then the ESI message may be delivered to any
- one of the indicated Portals.
-
-6.3.6. Portal Index
-
- The Portal Index is a 4-byte non-zero integer value that uniquely
- identifies each Portal registered in the iSNS database. Upon initial
- registration of a Portal, the iSNS server assigns an unused value for
- the Portal Index of that Portal. Each Portal in the iSNS database
- MUST be assigned a value for the Portal Index that is not assigned to
- any other Portal. Furthermore, Portal Index values for recently
- deregistered Portals SHOULD NOT be reused in the short term.
-
- The Portal Index MAY be used to represent a registered Portal in
- situations where the Portal IP-Address and Portal TCP/UDP Port is
- unwieldy to use. An example of this is when SNMP is used for
- management, as described in Section 2.10.
-
-6.3.7. SCN Port
-
- This field contains the TCP or UDP port used by the iSNS client to
- receive SCN messages from the iSNS server. When a value is
- registered for this attribute, an SCN message may be received on the
- indicated port for any of the Storage Nodes supported by the Portal.
- Bits 16 to 31 contain the port number. If bit 15 is set, then the
- port type is UDP. Otherwise, the port type is TCP. Bits 0 to 14 are
- reserved.
-
- If the iSNS client registers a valid TCP or UDP port number in this
- field, then the client SHALL allow SCN messages to be received at the
- indicated TCP or UDP port. If a TCP port is registered and a pre-
-
-
-
-Tseng, et al. Standards Track [Page 82]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- existing TCP connection from that TCP port to the iSNS server does
- not already exist, then the iSNS client SHALL accept new TCP
- connections from the iSNS server at the indicated TCP port.
-
- The iSNS server SHALL return an error if an SCN registration message
- is received and none of the Portals of the Network Entity has an
- entry for the SCN Port. If multiple Portals have a registered SCN
- Port, then the SCN SHALL be delivered to any one of the indicated
- Portals of that Network Entity.
-
-6.3.8. Portal Next Index
-
- This is a virtual attribute containing a 4-byte integer value that
- indicates the next available (i.e., unused) Portal Index value. This
- attribute may only be queried; the iSNS server SHALL return an error
- code of 3 (Invalid Registration) to any client that attempts to
- register a value for this attribute. A Message Key is not required
- when exclusively querying for this attribute.
-
- The Portal Next Index MAY be used by an SNMP client to create an
- entry in the iSNS server. SNMP requirements are described in Section
- 2.10.
-
-6.3.9. Portal Security Bitmap
-
- This 4-byte field contains flags that indicate security attribute
- settings for the Portal. Bit 31 (Lsb) of this field must be 1
- (enabled) for this field to contain significant information. If Bit
- 31 is enabled, this signifies that the iSNS server can be used to
- store and distribute security policies and settings for iSNS clients
- (i.e., iSCSI devices). Bit 30 must be 1 for bits 25-29 to contain
- significant information. All other bits are reserved for non-
- IKE/IPSec security mechanisms to be specified in the future.
-
- Bit Position Flag Description
- ------------ ----------------
- 25 1 = Tunnel Mode Preferred; 0 = No Preference
- 26 1 = Transport Mode Preferred; 0 = No Preference
- 27 1 = Perfect Forward Secrecy (PFS) Enabled;
- 0 = PFS Disabled
- 28 1 = Aggressive Mode Enabled; 0 = Disabled
- 29 1 = Main Mode Enabled; 0 = MM Disabled
- 30 1 = IKE/IPSec Enabled; 0 = IKE/IPSec Disabled
- 31 (Lsb) 1 = Bitmap VALID; 0 = INVALID
- All others RESERVED
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 83]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-6.3.10. Portal ISAKMP Phase-1 Proposals
-
- This field contains the IKE Phase-1 proposal listing in decreasing
- order of preference of the protection suites acceptable to protect
- all IKE Phase-2 messages sent and received by the Portal. This
- includes Phase-2 SAs from the iSNS client to the iSNS server as well
- as to peer iFCP and/or iSCSI devices. This attribute contains the SA
- payload, proposal payload(s), and transform payload(s) in the ISAKMP
- format defined in [RFC2408].
-
- This field should be used if the implementer wishes to define phase-1
- SA security configuration on a per-Portal basis, as opposed to on a
- per-Network Entity basis. If the implementer desires to have a
- single phase-1 SA security configuration to protect all phase-2
- traffic regardless of the interface used, then the Entity Phase-1
- Proposal (Section 6.2.9) should be used.
-
-6.3.11. Portal ISAKMP Phase-2 Proposals
-
- This field contains the IKE Phase-2 proposal, in ISAKMP format
- [RFC2408], listing in decreasing order of preference the security
- proposals acceptable to protect traffic sent and received by the
- Portal. This field is used only if bits 31, 30, and 29 of the
-
- Security Bitmap (see 6.3.9) are enabled. This attribute contains the
- SA payload, proposal payload(s), and associated transform payload(s)
- in the ISAKMP format defined in [RFC2408].
-
-6.3.12. Portal Certificate
-
- This attribute contains one or more X.509 certificates that are a
- credential of the Portal. This certificate is used to identify and
- authenticate communications to the IP address and TCP/UDP Port
- supported by the Portal. The format of the X.509 certificate is
- specified in [RFC3280]. This certificate MUST contain a Subject Name
- with an empty sequence and MUST contain a SubjectAltName extension
- encoded with the iPAddress type. The Portal IP Address (Section
- 6.3.1) of the identified Portal SHALL be stored in the SubjectAltName
- field of the certificate.
-
-6.4. iSCSI Node-Keyed Attributes
-
- The following attributes are stored in the iSNS database using the
- iSCSI Name attribute as the key. Each set of Node-Keyed attributes
- is associated with one Entity Identifier object key.
-
- Although the iSCSI Name key is associated with one Entity Identifier,
- it is unique across the entire iSNS database.
-
-
-
-Tseng, et al. Standards Track [Page 84]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-6.4.1. iSCSI Name
-
- This is a variable-length UTF-8 encoded NULL-terminated text-based
- description of up to 224 bytes. This key attribute is required for
- iSCSI Storage Nodes and is provided by the iSNS client. The
- registered iSCSI Name MUST conform to the format described in [iSCSI]
- for iSCSI Names. The maximum size for an iSCSI Name is 223 bytes.
- Including the NULL character and 4-byte alignment (see Section
- 5.3.1), the maximum iSCSI Name field size is 224 bytes.
-
- If an iSCSI Name is registered without an EID key, then a Network
- Entity SHALL be created and an EID assigned. The assigned EID SHALL
- be returned in the registration response as an operating attribute.
-
- This field MUST be normalized according to the stringprep template
- [STRINGPREP] before it is stored in the iSNS database.
-
-6.4.2. iSCSI Node Type
-
- This required 32-bit field is a bitmap indicating the type of iSCSI
- Storage Node. The bit positions are defined below. A set bit (1)
- indicates that the Node has the corresponding characteristics.
-
- Bit Position Node Type
- ------------ ---------
- 29 Control
- 30 Initiator
- 31 (Lsb) Target
- All others RESERVED
-
- If the Target bit is set to 1, then the Node represents an iSCSI
- target. The Target bit MAY be set by iSNS clients using the iSNSP.
-
- If the Initiator bit is set to 1, then the Node represents an iSCSI
- initiator. The Initiator bit MAY be set by iSNS clients using the
- iSNSP.
-
- If the control bit is set to 1, then the Node represents a gateway, a
- management station, a backup iSNS server, or another device that is
- not an initiator or target, but that requires the ability to send and
- receive iSNSP messages, including state change notifications.
- Setting the control bit is an administrative task that MUST be
- performed on the iSNS server; iSNS clients SHALL NOT be allowed to
- change this bit using the iSNSP.
-
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 85]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- This field MAY be used by the iSNS server to distinguish among
- permissions by different iSCSI Node types for accessing various iSNS
- functions. More than one Node Type bit may be simultaneously
- enabled.
-
-6.4.3. iSCSI Node Alias
-
- This is a variable-length UTF-8 encoded NULL-terminated text-based
- description of up to 256 bytes. The Alias is a user-readable
- description of the Node entry in the iSNS database.
-
-6.4.4. iSCSI Node SCN Bitmap
-
- The iSCSI Node SCN Bitmap indicates events for which the registering
- iSNS client wishes to receive a notification message. The following
- table displays events that result in notifications, and the bit field
- in the SCN Bitmap that, when enabled, results in the corresponding
- notification.
-
- Note that this field is of dual use: it is used in the SCN
- registration process to define interested events that will trigger an
- SCN message, and it is also contained in each SCN message itself, to
- indicate the type of event that triggered the SCN message. A set bit
- (1) indicates the corresponding type of SCN.
-
- Bit Position Flag Description
- ------------ ----------------
- 24 INITIATOR AND SELF INFORMATION ONLY
- 25 TARGET AND SELF INFORMATION ONLY
- 26 MANAGEMENT REGISTRATION/SCN
- 27 OBJECT REMOVED
- 28 OBJECT ADDED
- 29 OBJECT UPDATED
- 30 DD/DDS MEMBER REMOVED (Mgmt Reg/SCN only)
- 31 (Lsb) DD/DDS MEMBER ADDED (Mgmt Reg/SCN only)
- All others RESERVED
-
- DD/DDS MEMBER REMOVED indicates that an existing member of a
- Discovery Domain and/or Discovery Domain Set has been removed.
-
- DD/DDS MEMBER ADDED indicates that a new member was added to an
- existing DD and/or DDS.
-
- OBJECT REMOVED, OBJECT ADDED, and OBJECT UPDATED indicate a Network
- Entity, Portal, Storage Node, FC Device, DD, and/or DDS object was
- removed from, added to, or updated in the Discovery Domain or in the
- iSNS database (Control Nodes only).
-
-
-
-
-Tseng, et al. Standards Track [Page 86]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- Regular SCNs provide information about objects that are updated in,
- added to or removed from Discovery Domains of which the Storage Node
- is a member. An SCN or SCN registration is considered a regular SCN
- or regular SCN registration if the MANAGEMENT REGISTRATION/SCN flag
- is cleared. All iSNS clients may register for regular SCNs.
-
- Management SCNs provide information about all changes to the network,
- regardless of discovery domain membership. Registration for
- management SCNs is indicated by setting bit 26 to 1. Only Control
- Nodes may register for management SCNs. Bits 30 and 31 may only be
- enabled if bit 26 is set to 1.
-
- TARGET AND SELF INFORMATION ONLY SCNs (bit 25) provides information
- only about changes to target devices, or if the iSCSI Storage Node
- itself has undergone a change. Similarly, INITIATOR AND SELF
- INFORMATION ONLY SCNs (bit 24) provides information only about
- changes to initiator Nodes, or to the target itself.
-
-6.4.5. iSCSI Node Index
-
- The iSCSI Node Index is a 4-byte non-zero integer value used as a key
- that uniquely identifies each iSCSI Storage Node registered in the
- iSNS database. Upon initial registration of the iSCSI Storage Node,
- the iSNS server assigns an unused value for the iSCSI Node Index.
- Each iSCSI Node MUST be assigned a value for the iSCSI Node Index
- that is not assigned to any other iSCSI Storage Node. Furthermore,
- iSCSI Node Index values for recently deregistered iSCSI Storage Nodes
- SHOULD NOT be reused in the short term.
-
- The iSCSI Node Index may be used as a key to represent a registered
- Node in situations where the iSCSI Name is too long to be used as a
- key. An example of this is when SNMP is used for management, as
- described in Section 2.10.
-
- The value assigned for the iSCSI Node Index SHALL persist as long as
- the iSCSI Storage Node is registered in the iSNS database or a member
- of a Discovery Domain. An iSCSI Node Index value that is assigned
- for a Storage Node SHALL NOT be used for any other Storage Node as
- long as the original node is registered in the iSNS database or a
- member of a Discovery Domain.
-
-6.4.6. WWNN Token
-
- This field contains a globally unique 64-bit integer value that can
- be used to represent the World Wide Node Name of the iSCSI device in
- a Fibre Channel fabric. This identifier is used during the device
- registration process and MUST conform to the requirements in [FC-FS].
-
-
-
-
-Tseng, et al. Standards Track [Page 87]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- The FC-iSCSI gateway uses the value found in this field to register
- the iSCSI device in the Fibre Channel name server. It is stored in
- the iSNS server to prevent conflict when "proxy" WWNN values are
- assigned to iSCSI initiators establishing storage sessions to devices
- in the FC fabric.
-
- If the iSNS client does not assign a value for WWNN Token, then the
- iSNS server SHALL provide a value for this field upon initial
- registration of the iSCSI Storage Node. The process by which the
- WWNN Token is assigned by the iSNS server MUST conform to the
- following requirements:
-
- 1. The assigned WWNN Token value MUST be unique among all WWN
- entries in the existing iSNS database, and among all devices that
- can potentially be registered in the iSNS database.
-
- 2. Once the value is assigned, the iSNS server MUST persistently
- save the mapping between the WWNN Token value and registered
- iSCSI Name. That is, successive re-registrations of the iSCSI
- Storage Node keyed by the same iSCSI Name maintain the original
- mapping to the associated WWNN Token value in the iSNS server.
- Similarly, the mapping SHALL be persistent across iSNS server
- reboots. Once assigned, the mapping can only be changed if a
- DevAttrReg message from an authorized iSNS client explicitly
- provides a different WWNN Token value.
-
- 3. Once a WWNN Token value has been assigned and mapped to an iSCSI
- name, that WWNN Token value SHALL NOT be reused or mapped to any
- other iSCSI name.
-
- 4. The assigned WWNN Token value MUST conform to the formatting
- requirements of [FC-FS] for World Wide Names (WWNs).
-
- An iSNS client, such as an FC-iSCSI gateway or the iSCSI initiator,
- MAY register its own WWNN Token value or overwrite the iSNS Server-
- supplied WWNN Token value, if it wishes to supply its own iSCSI-FC
- name mapping. This is accomplished using the DevAttrReg message with
- the WWNN Token (tag=37) as an operating attribute. Once overwritten,
- the new WWNN Token value MUST be stored and saved by the iSNS server,
- and all requirements specified above continue to apply. If an iSNS
- client attempts to register a value for this field that is not unique
- in the iSNS database or that is otherwise invalid, then the
- registration SHALL be rejected with an Status Code of 3 (Invalid
- Registration).
-
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 88]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- There MAY be matching records in the iSNS database for the Fibre
- Channel device specified by the WWNN Token. These records may
- contain device attributes for that FC device registered in the Fibre
- Channel fabric name server.
-
-6.4.7. iSCSI Node Next Index
-
- This is a virtual attribute containing a 4-byte integer value that
- indicates the next available (i.e., unused) iSCSI Node Index value.
- This attribute may only be queried; the iSNS server SHALL return an
- error code of 3 (Invalid Registration) to any client that attempts to
- register a value for this attribute. A Message Key is not required
- when exclusively querying for this attribute.
-
- The iSCSI Node Next Index MAY be used by an SNMP client to create an
- entry in the iSNS server. SNMP requirements are described in Section
- 2.10.
-
-6.4.8. iSCSI AuthMethod
-
- This attribute contains a NULL-terminated string of UTF-8 text
- listing the iSCSI authentication methods enabled for this iSCSI
- Storage Node, in order of preference. The text values used to
- identify iSCSI authentication methods are embedded in this string
- attribute and delineated by a comma. The text values are identical
- to those found in the main iSCSI document [iSCSI]; additional
- vendor-specific text values are also possible.
-
- Text Value Description Reference
- ---------- ----------- ---------
- KB5 Kerberos V5 [RFC1510]
- SPKM1 Simple Public Key GSS-API [RFC2025]
- SPKM2 Simple Public Key GSS-API [RFC2025]
- SRP Secure Remote Password [RFC2945]
- CHAP Challenge Handshake Protocol [RFC1994]
- none No iSCSI Authentication
-
-6.5. Portal Group (PG) Object-Keyed Attributes
-
- The following attributes are used to associate Portal and iSCSI
- Storage Node objects. PG objects are stored in the iSNS database
- using the PG iSCSI Name, the PG Portal IP Address, and the PG Portal
- TCP/UDP Port as keys. New PG objects are implicitly or explicitly
- created at the time that the corresponding Portal and/or iSCSI
- Storage Node objects are registered. Section 3.4 has a general
- discussion of PG usage. For further details on use of Portal Groups,
- see [iSCSI].
-
-
-
-
-Tseng, et al. Standards Track [Page 89]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-6.5.1. Portal Group iSCSI Name
-
- This is the iSCSI Name for the iSCSI Storage Node that is associated
- with the PG object. This name MAY represent an iSCSI Storage Node
- not currently registered in the server.
-
-6.5.2. PG Portal IP Addr
-
- This is the Portal IP Address attribute for the Portal that is
- associated with the PG object. This Portal IP Address MAY be that of
- a Portal that is not currently registered in the server.
-
-6.5.3. PG Portal TCP/UDP Port
-
- This is the Portal TCP/UDP Port attribute for the Portal that is
- associated with the PG object. This Portal TCP/UDP Port MAY be that
- of a Portal that is not currently registered in the server.
-
-6.5.4. Portal Group Tag (PGT)
-
- This field is used to group Portals in order to coordinate
- connections in a session across Portals to a specified iSCSI Node.
- The PGT is a value in the range of 0-65535, or NULL. A NULL PGT
- value is registered by using 0 for the length in the TLV during
- registration. The two least significant bytes of the value contain
- the PGT for the object. The two most significant bytes are reserved.
- If a PGT value is not explicitly registered for an iSCSI Storage Node
- and Portal pair, then the PGT value SHALL be implicitly registered as
- 0x00000001.
-
-6.5.5. Portal Group Index
-
- The PG Index is a 4-byte non-zero integer value used as a key that
- uniquely identifies each PG object registered in the iSNS database.
- Upon initial registration of a PG object, the iSNS server MUST assign
- an unused value for the PG Index. Furthermore, PG Index values for
- recently deregistered PG objects SHOULD NOT be reused in the short
- term.
-
- The PG Index MAY be used as the key to reference a registered PG in
- situations where a unique index for each PG object is required. It
- MAY also be used as the message key in an iSNS message to query or
- update a pre-existing PG object. An example of this is when SNMP is
- used for management, as described in Section 2.10. The value
- assigned for the PG Index SHALL persist as long as the server is
- active.
-
-
-
-
-
-Tseng, et al. Standards Track [Page 90]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-6.5.6. Portal Group Next Index
-
- The PG Next Index is a virtual attribute containing a 4-byte integer
- value that indicates the next available (i.e., unused) PG Index
- value. This attribute may only be queried; the iSNS server SHALL
- return an error code of 3 (Invalid Registration) to any client that
- attempts to register a value for this attribute. A Message Key is
- not required when exclusively querying for this attribute.
-
- The Portal Group Next Index MAY be used by an SNMP client to create
- an entry in the iSNS server. SNMP requirements are described in
- Section 2.10.
-
-6.6. FC Port Name-Keyed Attributes
-
- The following attributes are registered in the iSNS database using
- the FC Port World Wide Name (WWPN) attribute as the key. Each set of
- FC Port-Keyed attributes is associated with one Entity Identifier
- object key.
-
- Although the FC Port World Wide Name is associated with one Entity
- Identifier, it is also globally unique.
-
-6.6.1. FC Port Name (WWPN)
-
- This 64-bit identifier uniquely defines the FC Port, and it is the
- World Wide Port Name (WWPN) of the corresponding Fibre Channel
- device. This attribute is the key for the iFCP Storage Node. This
- globally unique identifier is used during the device registration
- process, and it uses a value conforming to IEEE EUI-64 [EUI-64].
-
-6.6.2. Port ID (FC_ID)
-
- The Port Identifier is a Fibre Channel address identifier assigned to
- an N_Port or NL_Port during fabric login. The format of the Port
- Identifier is defined in [FC-FS]. The least significant 3 bytes
- contain this address identifier. The most significant byte is
- RESERVED.
-
-
-
-
-
-
-
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 91]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-6.6.3. FC Port Type
-
- Indicates the type of FC port. Encoded values for this field are
- listed in the following table:
-
- Type Description
- ---- -----------
- 0x0000 Unidentified/Null Entry
- 0x0001 Fibre Channel N_Port
- 0x0002 Fibre Channel NL_Port
- 0x0003 Fibre Channel F/NL_Port
- 0x0004-0080 RESERVED
- 0x0081 Fibre Channel F_Port
- 0x0082 Fibre Channel FL_Port
- 0x0083 RESERVED
- 0x0084 Fibre Channel E_Port
- 0x0085-00FF RESERVED
- 0xFF11 RESERVED
- 0xFF12 iFCP Port
- 0xFF13-FFFF RESERVED
-
-6.6.4. Symbolic Port Name
-
- This is a variable-length UTF-8 encoded NULL-terminated text-based
- description of up to 256 bytes that is associated with the iSNS-
- registered FC Port Name in the network.
-
-6.6.5. Fabric Port Name (FWWN)
-
- This 64-bit identifier uniquely defines the fabric port. If the port
- of the FC Device is attached to a Fibre Channel fabric port with a
- registered Port Name, then that fabric Port Name SHALL be indicated
- in this field.
-
-6.6.6. Hard Address
-
- This field is the requested hard address 24-bit NL Port Identifier,
- included in the iSNSP for compatibility with Fibre Channel Arbitrated
- Loop devices and topologies. The least significant 3 bytes of this
- field contain the address. The most significant byte is RESERVED.
-
-6.6.7. Port IP Address
-
- The Fibre Channel IP address associated with the FC Port. When this
- field contains an IPv4 value, it is stored as an IPv4-mapped IPv6
- address. That is, the most significant 10 bytes are set to 0x00,
- with the next two bytes set to 0xFFFF [RFC2373]. When an IPv6 value
- is contained in this field, then the entire 16-byte field is used.
-
-
-
-Tseng, et al. Standards Track [Page 92]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-6.6.8. Class of Service (COS)
-
- This 32-bit bit-map field indicates the Fibre Channel Class of
- Service types that are supported by the registered port. In the
- following table, a set bit (1) indicates a Class of Service
- supported.
-
- Bit Position Description
- ------------ -----------
- 29 Fibre Channel Class 2 Supported
- 28 Fibre Channel Class 3 Supported
-
-6.6.9. FC-4 Types
-
- This 32-byte field indicates the FC-4 protocol types supported by the
- associated port. This field can be used to support Fibre Channel
- devices and is consistent with FC-GS-4.
-
-6.6.10. FC-4 Descriptor
-
- This is a variable-length UTF-8 encoded NULL-terminated text-based
- description of up to 256 bytes that is associated with the iSNS-
- registered device port in the network. This field can be used to
- support Fibre Channel devices and is consistent with FC-GS-4.
-
-6.6.11. FC-4 Features
-
- This is a 128-byte array, 4 bits per type, for the FC-4 protocol
- types supported by the associated port. This field can be used to
- support Fibre Channel devices and is consistent with FC-GS-4.
-
-6.6.12. iFCP SCN Bitmap
-
- This field indicates the events the iSNS client is interested in.
- These events can cause SCNs to be generated. SCNs provide
- information about objects that are updated in, added to or removed
- from Discovery Domains of which the source and destination are a
- member. Management SCNs provide information about all changes to the
- network. A set bit (1) indicates the type of SCN for the bitmap as
- follows:
-
-
-
-
-
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 93]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- Bit Position Flag Description
- ------------ ----------------
- 24 INITIATOR AND SELF INFORMATION ONLY
- 25 TARGET AND SELF INFORMATION ONLY
- 26 MANAGEMENT REGISTRATION/SCN
- 27 OBJECT REMOVED
- 28 OBJECT ADDED
- 29 OBJECT UPDATED
- 30 DD/DDS MEMBER REMOVED (Mgmt Reg/SCN only)
- 31 (Lsb) DD/DDS MEMBER ADDED (Mgmt Reg/SCN only)
- All others RESERVED
-
- Further information on the use of the bit positions specified above
- can be found in Section 6.4.4.
-
-6.6.13. Port Role
-
- This required 32-bit field is a bitmap indicating the type of iFCP
- Storage Node. The bit fields are defined below. A set bit indicates
- the Node has the corresponding characteristics.
-
- Bit Position Node Type
- ------------ ---------
- 29 Control
- 30 FCP Initiator
- 31 (Lsb) FCP Target
- All Others RESERVED
-
- If the 'Target' bit is set to 1, then the port represents an FC
- target. Setting of the 'Target' bit MAY be performed by iSNS clients
- using the iSNSP.
-
- If the 'Initiator' bit is set to 1, then the port represents an FC
- initiator. Setting of the 'Initiator' bit MAY be performed by iSNS
- clients using the iSNSP.
-
- If the 'Control' bit is set to 1, then the port represents a gateway,
- a management station, an iSNS backup server, or another device.
-
- This is usually a special device that is neither an initiator nor a
- target, which requires the ability to send and receive iSNSP
- messages, including state-change notifications. Setting the control
- bit is an administrative task that MUST be administratively
- configured on the iSNS server; iSNS clients SHALL NOT be allowed to
- change this bit using the iSNSP.
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 94]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- This field MAY be used by the iSNS server to distinguish among
- permissions by different iSNS clients. For example, an iSNS server
- implementation may be administratively configured to allow only
- targets to receive ESIs, or to permit only Control Nodes to add,
- modify, or delete discovery domains.
-
-6.6.14. Permanent Port Name (PPN)
-
- The Permanent Port Name can be used to support Fibre Channel devices
- and is consistent with the PPN description in FC-GS-4 [FC-GS-4]. The
- format of the PPN is identical to the FC Port Name WWPN attribute
- format.
-
-6.7. Node-Keyed Attributes
-
- The following attributes are registered in the iSNS database using
- the FC Node Name (WWNN) attribute as the key. Each set of FC Node-
- Keyed attributes represents a single device and can be associated
- with many FC Ports.
-
- The FC Node Name is unique across the entire iSNS database.
-
-6.7.1. FC Node Name (WWNN)
-
- The FC Node Name is a 64-bit identifier that is the World Wide Node
- Name (WWNN) of the corresponding Fibre Channel device. This
- attribute is the key for the FC Device. This globally unique
- identifier is used during the device registration process, and it
- uses a value conforming to IEEE EUI-64 [EUI-64].
-
-6.7.2. Symbolic Node Name
-
- This is a variable-length UTF-8 encoded NULL-terminated text-based
- description of up to 256 bytes that is associated with the iSNS-
- registered FC Device in the network.
-
-6.7.3. Node IP Address
-
- This IP address is associated with the device Node in the network.
- This field is included for compatibility with Fibre Channel. When
- this field contains an IPv4 value, it is stored as an IPv4-mapped
- IPv6 address. That is, the most significant 10 bytes are set to
- 0x00, with the next two bytes set to 0xFFFF [RFC2373]. When an IPv6
- value is contained in this field, the entire 16-byte field is used.
-
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 95]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-6.7.4. Node IPA
-
- This field is the 8-byte Fibre Channel Initial Process Associator
- (IPA) associated with the device Node in the network. The initial
- process associator is used for communication between Fibre Channel
- devices.
-
-6.7.5. Proxy iSCSI Name
-
- This is a variable-length UTF-8 encoded NULL-terminated text-based
- field that contains the iSCSI Name used to represent the FC Node in
- the IP network. It is used as a pointer to the matching iSCSI Name
- entry in the iSNS server. Its value is usually registered by an FC-
- iSCSI gateway connecting the IP network to the fabric containing the
- FC device.
-
- Note that if this field is used, there SHOULD be a matching entry in
- the iSNS database for the iSCSI device specified by the iSCSI name.
- The database entry should include the full range of iSCSI attributes
- needed for discovery and management of the "iSCSI proxy image" of the
- FC device.
-
-6.8. Other Attributes
-
- The following are not attributes of the previously-defined objects.
-
-6.8.1. FC-4 Type Code
-
- This is a 4-byte field used to provide a FC-4 type during a FC-4 Type
- query. The FC-4 types are consistent with the FC-4 Types as defined
- in FC-FS. Byte 0 contains the FC-4 type. All other bytes are
- reserved.
-
-6.8.2. iFCP Switch Name
-
- The iFCP Switch Name is a 64-bit World Wide Name (WWN) identifier
- that uniquely identifies a distinct iFCP gateway in the network.
- This globally unique identifier is used during the switch
- registration/FC_DOMAIN_ID assignment process. The iFCP Switch Name
- value used MUST conform to the requirements stated in [FC-FS] for
- World Wide Names. The iSNS server SHALL track the state of all
- FC_DOMAIN_ID values that have been allocated to each iFCP Switch
- Name. If a given iFCP Switch Name is deregistered from the iSNS
- database, then all FC_DOMAIN_ID values allocated to that iFCP Switch
- Name SHALL be returned to the unused pool of values.
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 96]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-6.8.3. iFCP Transparent Mode Commands
-
-6.8.3.1. Preferred ID
-
- This is a 4-byte unsigned integer field, and it is the requested
- value that the iSNS client wishes to use for the FC_DOMAIN_ID. The
- iSNS server SHALL grant the iSNS client the use of the requested
- value as the FC_DOMAIN_ID, if the requested value has not already
- been allocated. If the requested value is not available, the iSNS
- server SHALL return a different value that has not been allocated.
-
-6.8.3.2. Assigned ID
-
- This is a 4-byte unsigned integer field that is used by an iFCP
- gateway to reserve its own unique FC_DOMAIN_ID value from the range 1
- to 239. When a FC_DOMAIN_ID is no longer required, it SHALL be
- released by the iFCP gateway using the RlseDomId message. The iSNS
- server MUST use the Entity Status Inquiry message to determine
- whether an iFCP gateway is still present on the network.
-
-6.8.3.3. Virtual_Fabric_ID
-
- This is a variable-length UTF-8 encoded NULL-terminated text-based
- field of up to 256 bytes. The Virtual_Fabric_ID string is used as a
- key attribute to identify a range of non-overlapping FC_DOMAIN_ID
- values to be allocated using RqstDomId. Each Virtual_Fabric_ID
- string submitted by an iSNS client SHALL have its own range of non-
- overlapping FC_DOMAIN_ID values to be allocated to iSNS clients.
-
-
-6.9. iSNS Server-Specific Attributes
-
- Access to the following attributes may be administratively
- controlled. These attributes are specific to the iSNS server
- instance; the same value is returned for all iSNS clients accessing
- the iSNS server. Only query messages may be performed on these
- attributes. Attempted registrations of values for these attributes
- SHALL return a status code of 3 (Invalid Registration).
-
- A query for an iSNS Server-Specific attribute MUST contain the
- identifying key attribute (i.e., iSCSI Name or FC Port Name WWPN) of
- the Node originating the registration or query message as the Source
- and Message Key attributes. The Operating Attributes are the
- server-specific attributes being registered or queried.
-
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 97]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-6.9.1. iSNS Server Vendor OUI
-
- This attribute is the OUI (Organizationally Unique Identifier)
- [802-1990] identifying the specific vendor implementing the iSNS
- server. This attribute can only be queried; iSNS clients SHALL NOT be
- allowed to register a value for the iSNS Server Vendor OUI.
-
-6.10. Vendor-Specific Attributes
-
- iSNS server implementations MAY define vendor-specific attributes for
- private use. These attributes MAY be used to store optional data
- that is registered and/or queried by iSNS clients in order to gain
- optional capabilities. Note that any implementation of vendor-
- specific attributes in the iSNS server SHALL NOT impose any form of
- mandatory behavior on the part of the iSNS client.
-
- The tag values used for vendor-specific and user-specific use are
- defined in Section 6.1. To avoid misinterpreting proprietary
- attributes, the vendor's own OUI (Organizationally Unique Identifier)
- MUST be placed in the upper three bytes of the attribute value field
- itself.
-
- The OUI is defined in IEEE Std 802-1990 and is the same constant used
- to generate 48 bit Universal LAN MAC addresses. A vendor's own iSNS
- implementation will then be able to recognize the OUI in the
- attribute field and be able to execute vendor-specific handling of
- the attribute.
-
-6.10.1. Vendor-Specific Server Attributes
-
- Attributes with tags in the range 257 to 384 are vendor-specific or
- site-specific attributes of the iSNS server. Values for these
- attributes are administratively set by the specific vendor providing
- the iSNS server implementation. Query access to these attributes may
- be administratively controlled. These attributes are unique for each
- logical iSNS server instance. Query messages for these attributes
- SHALL use the key identifier (i.e., iSCSI Name or FC Port Name WWPN)
- for both the Source attribute and Message Key attribute. These
- attributes can only be queried; iSNS clients SHALL NOT be allowed to
- register a value for server attributes.
-
-6.10.2. Vendor-Specific Entity Attributes
-
- Attributes in the range 385 to 512 are vendor-specific or site-
- specific attributes used to describe the Network Entity object.
- These attributes are keyed by the Entity Identifier attribute
- (tag=1).
-
-
-
-
-Tseng, et al. Standards Track [Page 98]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-6.10.3. Vendor-Specific Portal Attributes
-
- Attributes in the range 513 to 640 are vendor-specific or site-
- specific attributes used to describe the Portal object. These
- attributes are keyed by the Portal IP-Address (tag=16) and Portal
- TCP/UDP Port (tag=17).
-
-6.10.4. Vendor-Specific iSCSI Node Attributes
-
- Attributes in the range 641 to 768 are vendor-specific or site-
- specific attributes used to describe the iSCSI Node object. These
- attributes are keyed by the iSCSI Name (tag=32).
-
-6.10.5. Vendor-Specific FC Port Name Attributes
-
- Attributes in the range 769 to 896 are vendor-specific or site-
- specific attributes used to describe the N_Port Port Name object.
- These attributes are keyed by the FC Port Name WWPN (tag=64).
-
-6.10.6. Vendor-Specific FC Node Name Attributes
-
- Attributes in the range 897 to 1024 are vendor-specific or site-
- specific attributes used to describe the FC Node Name object. These
- attributes are keyed by the FC Node Name WWNN (tag=96).
-
-6.10.7. Vendor-Specific Discovery Domain Attributes
-
- Attributes in the range 1025 to 1280 are vendor-specific or site-
- specific attributes used to describe the Discovery Domain object.
- These attributes are keyed by the DD_ID (tag=104).
-
-6.10.8. Vendor-Specific Discovery Domain Set Attributes
-
- Attributes in the range 1281 to 1536 are vendor-specific or site-
- specific attributes used to describe the Discovery Domain Set object.
- These attributes are keyed by the DD Set ID (tag=101)
-
-6.10.9. Other Vendor-Specific Attributes
-
- Attributes in the range 1537 to 2048 can be used for key and non-key
- attributes that describe new vendor-specific objects specific to the
- vendor's iSNS server implementation.
-
-
-
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 99]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-6.11. Discovery Domain Registration Attributes
-
-6.11.1. DD Set ID Keyed Attributes
-
-6.11.1.1. Discovery Domain Set ID (DDS ID)
-
- The DDS ID is an unsigned non-zero integer identifier used in the
- iSNS directory database as a key to indicate a Discovery Domain Set
- uniquely. A DDS is a collection of Discovery Domains that can be
- enabled or disabled by a management station. This value is used as a
- key for DDS attribute queries. When a Discovery Domain is
- registered, it is initially not in any DDS.
-
- If the iSNS client does not provide a DDS_ID in a DDS registration
- request message, the iSNS server SHALL generate a DDS_ID value that
- is unique within the iSNS database for that new DDS. The created DDS
- ID SHALL be returned in the response message. The DDS ID value of 0
- is reserved, and the DDS ID value of 1 is used for the default DDS
- (see Section 2.2.2).
-
-6.11.1.2. Discovery Domain Set Symbolic Name
-
- A variable-length UTF-8 encoded NULL-terminated text-based field of
- up to 256 bytes. This is a user-readable field used to assist a
- network administrator in tracking the DDS function. When a client
- registers a DDS symbolic name, the iSNS server SHALL verify it is
- unique. If the name is not unique, then the DDS registration SHALL
- be rejected with an "Invalid Registration" Status Code. The invalid
- attribute(s), in this case the DDS symbolic name, SHALL be included
- in the response.
-
-6.11.1.3. Discovery Domain Set Status
-
- The DDS_Status field is a 32-bit bitmap indicating the status of the
- DDS. Bit 0 of the bitmap indicates whether the DDS is Enabled (1) or
- Disabled (0). The default value for the DDS Enabled flag is Disabled
- (0).
-
- Bit Position DDS Status
- ------------ ---------
- 31 (Lsb) DDS Enabled (1) / DDS Disabled (0)
- All others RESERVED
-
-6.11.1.4. Discovery Domain Set Next ID
-
- This is a virtual attribute containing a 4-byte integer value that
- indicates the next available (i.e., unused) Discovery Domain Set
- Index value. This attribute may only be queried; the iSNS server
-
-
-
-Tseng, et al. Standards Track [Page 100]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- SHALL return an error code of 3 (Invalid Registration) to any client
- that attempts to register a value for this attribute. A Message Key
- is not required when exclusively querying for this attribute.
-
- The Discovery Domain Set Next Index MAY be used by an SNMP client to
- create an entry in the iSNS server. SNMP requirements are described
- in Section 2.10.
-
-6.11.2. DD ID Keyed Attributes
-
-6.11.2.1. Discovery Domain ID (DD ID)
-
- The DD ID is an unsigned non-zero integer identifier used in the iSNS
- directory database as a key to identify a Discovery Domain uniquely.
- This value is used as the key for any DD attribute query. If the
- iSNS client does not provide a DD_ID in a DD registration request
- message, the iSNS server SHALL generate a DD_ID value that is unique
- within the iSNS database for that new DD (i.e., the iSNS client will
- be registered in a new DD). The created DD ID SHALL be returned in
- the response message. The DD ID value of 0 is reserved, and the DD
- ID value of 1 is used for the default DD (see Section 2.2.2).
-
-6.11.2.2. Discovery Domain Symbolic Name
-
- A variable-length UTF-8 encoded NULL-terminated text-based field of
- up to 256 bytes. When a client registers a DD symbolic name, the
- iSNS server SHALL verify it is unique. If the name is not unique,
- then the DD registration SHALL be rejected with an "Invalid
- Registration" Status Code. The invalid attribute(s), in this case
- the DD symbolic name, SHALL be included in the response.
-
-6.11.2.3. Discovery Domain Member: iSCSI Node Index
-
- This is the iSCSI Node Index of a Storage Node that is a member of
- the DD. The DD may have a list of 0 to n members. The iSCSI Node
- Index is one alternative representation of membership in a Discovery
- Domain, the other alternative being the iSCSI Name. The Discovery
- Domain iSCSI Node Index is a 4-byte non-zero integer value.
-
- The iSCSI Node Index can be used to represent a DD member in
- situations where the iSCSI Name is too long to be used. An example
- of this is when SNMP is used for management, as described in Section
- 2.10.
-
- The iSCSI Node Index and the iSCSI Name stored as a member in a DD
- SHALL be consistent with the iSCSI Node Index and iSCSI Name
- attributes registered for the Storage Node object in the iSNS server.
-
-
-
-
-Tseng, et al. Standards Track [Page 101]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-6.11.2.4. Discovery Domain Member: iSCSI Name
-
- A variable-length UTF-8 encoded NULL-terminated text-based field of
- up to 224 bytes. It indicates membership for the specified iSCSI
- Storage Node in the Discovery Domain. Note that the referenced
- Storage Node does not need to be actively registered in the iSNS
- database before the iSNS client uses this attribute. There is no
- limit to the number of members that may be in a DD. Membership is
- represented by the iSCSI Name of the iSCSI Storage Node.
-
-6.11.2.5. Discovery Domain Member: FC Port Name
-
- This 64-bit identifier attribute indicates membership for an iFCP
- Storage Node (FC Port) in the Discovery Domain. Note that the
- referenced Storage Node does not need to be actively registered in
- the iSNS database before the iSNS client uses this attribute. There
- is no limit to the number of members that may be in a DD. Membership
- is represented by the FC Port Name (WWPN) of the iFCP Storage Node.
-
-6.11.2.6. Discovery Domain Member: Portal Index
-
- This attribute indicates membership in the Discovery Domain for a
- Portal. It is an alternative representation for Portal membership to
- the Portal IP Address and Portal TCP/UDP Port. The referenced Portal
- MUST be actively registered in the iSNS database before the iSNS
- client uses this attribute.
-
-6.11.2.7. Discovery Domain Member: Portal IP Address
-
- This attribute and the Portal TCP/UDP Port attribute indicate
- membership in the Discovery Domain for the specified Portal. Note
- that the referenced Portal does not need to be actively registered in
- the iSNS database before the iSNS client uses this attribute.
-
-6.11.2.8. Discovery Domain Member: Portal TCP/UDP Port
-
- This attribute and the Portal IP Address attribute indicate
- membership in the Discovery Domain for the specified Portal. Note
- that the referenced Portal does not need to be actively registered in
- the iSNS database before the iSNS client uses this attribute.
-
-6.11.2.9. Discovery Domain Features
-
- The Discovery Domain Features is a bitmap indicating the features of
- this DD. The bit positions are defined below. A bit set to 1
- indicates the DD has the corresponding characteristics.
-
-
-
-
-
-Tseng, et al. Standards Track [Page 102]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- Bit Position DD Feature
- ------------ ----------
- 31 (Lsb) Boot List Enabled (1)/Boot List Disabled (0)
- All others RESERVED
-
- Boot List: this feature indicates that the target(s) in this DD
- provides boot capabilities for the member initiators, as described in
- [iSCSI-boot].
-
-6.11.2.10. Discovery Domain Next ID
-
- This is a virtual attribute containing a 4-byte integer value that
- indicates the next available (i.e., unused) Discovery Domain Index
- value. This attribute may only be queried; the iSNS server SHALL
- return an error code of 3 (Invalid Registration) to any client that
- attempts to register a value for this attribute. A Message Key is
- not required when exclusively querying for this attribute.
-
-7. Security Considerations
-
-7.1. iSNS Security Threat Analysis
-
- When the iSNS protocol is deployed, the interaction between iSNS
- server and iSNS clients is subject to the following security threats:
-
- a) An attacker could alter iSNS protocol messages, such as to direct
- iSCSI and iFCP devices to establish connections with rogue peer
- devices, or to weaken/eliminate IPSec protection for iSCSI or
- iFCP traffic.
-
- b) An attacker could masquerade as the real iSNS server using false
- iSNS heartbeat messages. This could cause iSCSI and iFCP devices
- to use rogue iSNS servers.
-
- c) An attacker could gain knowledge about iSCSI and iFCP devices by
- snooping iSNS protocol messages. Such information could aid an
- attacker in mounting a direct attack on iSCSI and iFCP devices,
- such as a denial-of-service attack or outright physical theft.
-
- To address these threats, the following capabilities are needed:
-
- a) Unicast iSNS protocol messages may need to be authenticated. In
- addition, to protect against threat c), confidentiality support
- is desirable and is REQUIRED when certain functions of iSNS
- server are utilized.
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 103]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- b) Multicast iSNS protocol messages such as the iSNS heartbeat
- message may need to be authenticated. These messages need not be
- confidential since they do not leak critical information.
-
-7.2. iSNS Security Implementation and Usage Requirements
-
- If the iSNS server is used to distribute authorizations for
- communications between iFCP and iSCSI peer devices, IPsec ESP with
- null transform MUST be implemented, and non-null transform MAY be
- implemented. If a non-null transform is implemented, then the DES
- encryption algorithm SHOULD NOT be used.
-
- If the iSNS server is used to distribute security policy for iFCP and
- iSCSI devices, then authentication, data integrity, and
- confidentiality MUST be supported and used. Where confidentiality is
- desired or required, IPSec ESP with non-null transform SHOULD be
- used, and the DES encryption algorithm SHOULD NOT be used.
-
- If the iSNS server is used to provide the boot list for clients, as
- described in Section 6.11.2.9, then the iSCSI boot client SHOULD
- implement a secure iSNS connection.
-
- In order to protect against an attacker masquerading as an iSNS
- server, client devices MUST support the ability to authenticate
- broadcast or multicast messages such as the iSNS heartbeat. The iSNS
- authentication block (which is identical in format to the SLP
- authentication block) SHALL be used for this purpose. iSNS clients
- MUST implement the iSNS authentication block and MUST support BSD
- value 0x002. If the iSNS server supports broadcast or multicast iSNS
- messages (i.e., the heartbeat), then the server MUST implement the
- iSNS authentication block and MUST support BSD value 0x002. Note
- that the authentication block is used only for iSNS broadcast or
- multicast messages and MUST NOT be used in unicast iSNS messages.
-
- There is no requirement that the communicating identities in iSNS
- protocol messages be kept confidential. Specifically, the identity
- and location of the iSNS server is not considered confidential.
-
- For protecting unicast iSNS protocol messages, iSNS servers
- supporting security MUST implement ESP in tunnel mode and MAY
- implement transport mode.
-
- All iSNS implementations supporting security MUST support the replay
- protection mechanisms of IPsec.
-
- iSNS security implementations MUST support both IKE Main Mode and
- Aggressive Mode for authentication, negotiation of security
- associations, and key management, using the IPSec DOI [RFC2407].
-
-
-
-Tseng, et al. Standards Track [Page 104]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- Manual keying SHOULD NOT be used since it does not provide the
- necessary rekeying support. Conforming iSNS security implementations
- MUST support authentication using a pre-shared key, and MAY support
- certificate-based peer authentication using digital signatures. Peer
- authentication using the public key encryption methods outlined in
- IKEs Sections 5.2 and 5.3 [RFC2409] SHOULD NOT be supported.
-
- Conforming iSNS implementations MUST support both IKE Main Mode and
- Aggressive Mode. IKE Main Mode with pre-shared key authentication
- SHOULD NOT be used when either of the peers use dynamically assigned
- IP addresses. Although Main Mode with pre-shared key authentication
- offers good security in many cases, situations where dynamically
- assigned addresses are used force the use of a group pre-shared key,
- which is vulnerable to man-in-the-middle attack. IKE Identity
- Payload ID_KEY_ID MUST NOT be used.
-
- When digital signatures are used for authentication, either IKE Main
- Mode or IKE Aggressive Mode MAY be used. In all cases, access to
- locally stored secret information (pre-shared key or private key for
- digital signing) MUST be suitably restricted, since compromise of the
- secret information nullifies the security properties of the IKE/IPsec
- protocols.
-
- When digital signatures are used to achieve authentication, an IKE
- negotiator SHOULD use IKE Certificate Request Payload(s) to specify
- the certificate authority (or authorities) that are trusted in
- accordance with its local policy. IKE negotiators SHOULD check the
- pertinent Certificate Revocation List (CRL) before accepting a PKI
- certificate for use in IKE's authentication procedures.
-
- When the iSNS server is used without security, IP block storage
- protocol implementations MUST support a negative cache for
- authentication failures. This allows implementations to avoid
- continually contacting discovered endpoints that fail authentication
- within IPsec or at the application layer (in the case of iSCSI
- Login). The negative cache need not be maintained within the IPsec
- implementation, but rather within the IP block storage protocol
- implementation.
-
-7.3. Discovering Security Requirements of Peer Devices
-
- Once communication between iSNS clients and the iSNS server has been
- secured through use of IPSec, the iSNS client devices have the
- capability to discover the security settings that they need to use
- for their peer-to-peer communications using the iSCSI and/or iFCP
- protocols. This provides a potential scaling advantage over device-
- by-device configuration of individual security policies for each
- iSCSI and iFCP device.
-
-
-
-Tseng, et al. Standards Track [Page 105]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- The iSNS server stores security settings for each iSCSI and iFCP
- device interface. These security settings, which can be retrieved by
- authorized hosts, include use or non-use of IPSec, IKE, Main Mode,
- and Aggressive Mode. For example, IKE may not be enabled for a
- particular interface of a peer device. If a peer device can learn of
- this in advance by consulting the iSNS server, it will not need to
- waste time and resources attempting to initiate an IKE phase 1
- session with that peer device interface.
-
- If iSNS is used for this purpose, then the minimum information that
- should be learned from the iSNS server is the use or non-use of IKE
- and IPSec by each iFCP or iSCSI peer device interface. This
- information is encoded in the Security Bitmap field of each Portal of
- the peer device, and is applicable on a per-interface basis for the
- peer device. iSNS queries for acquiring security configuration data
- about peer devices MUST be protected by IPSec/ESP authentication.
-
-7.4. Configuring Security Policies of iFCP/iSCSI Devices
-
- Use of iSNS for distribution of security policies offers the
- potential to reduce the burden of manual device configuration, and to
- decrease the probability of communications failures due to
- incompatible security policies. If iSNS is used to distribute
- security policies, then IPSec authentication, data integrity, and
- confidentiality MUST be used to protect all iSNS protocol messages.
-
- The complete IKE/IPSec configuration of each iFCP and/or iSCSI device
- can be stored in the iSNS server, including policies that are used
- for IKE Phase 1 and Phase 2 negotiations between client devices. The
- IKE payload format includes a series of one or more proposals that
- the iSCSI or iFCP device will use when negotiating the appropriate
- IPsec policy to use to protect iSCSI or iFCP traffic.
-
- In addition, the iSCSI Authentication Methods used by each iSCSI
- device can also be stored in the iSNS server. The iSCSI AuthMethod
- field (tag=42) contains a null-terminated string embedded with the
- text values indicating iSCSI authentication methods to be used by
- that iSCSI device.
-
- Note that iSNS distribution of security policy is not necessary if
- the security settings can be determined by other means, such as
- manual configuration or IPsec security policy distribution. If a
- network entity has already obtained its security configuration via
- other mechanisms, then it MUST NOT request security policy via iSNS.
-
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 106]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-7.5. Resource Issues
-
- The iSNS protocol is lightweight and will not generate a significant
- amount of traffic. iSNS traffic is characterized by occasional
- registration, notification, and update messages that do not consume
- significant amounts of bandwidth. Even software-based IPSec
- implementations should not have a problem handling the traffic loads
- generated by the iSNS protocol.
-
- To fulfill iSNS security requirements, the only additional resources
- needed beyond what is already required for iSCSI and iFCP involve the
- iSNS server. Because iSCSI and iFCP end nodes are already required
- to implement IKE and IPSec, these existing requirements can also be
- used to fulfill IKE and IPSec requirements for iSNS clients.
-
-7.6. iSNS Interaction with IKE and IPSec
-
- When IPSec security is enabled, each iSNS client with at least one
- Storage Node that is registered in the iSNS database SHALL maintain
- at least one phase-1 security association with the iSNS server. All
- iSNS protocol messages between iSNS clients and the iSNS server SHALL
- be protected by a phase-2 security association.
-
- When a Network Entity is removed from the iSNS database, the iSNS
- server SHALL send a phase-1 delete message to the associated iSNS
- client IKE peer, and tear down all phase-1 and phase-2 SAs associated
- with that iSNS client.
-
-8. IANA Considerations
-
- The well-known TCP and UDP port number for iSNS is 3205.
-
- The standards action of this RFC creates two registries to be
- maintained by IANA in support of iSNSP and assigns initial values for
- both registries. The first registry is of Block Storage Protocols
- supported by iSNS. The second registry is a detailed registry of
- standard iSNS attributes that can be registered to and queried from
- the iSNS server. Note that this RFC uses the registry created for
- Block Structure Descriptor (BSD) in Section 15 of Service Location
- Protocol, Version 2 [RFC2608].
-
-8.1. Registry of Block Storage Protocols
-
- In order to maintain a registry of block storage protocols supported
- by iSNSP, IANA will assign a 32-bit unsigned integer number for each
- block storage protocol supported by iSNS. This number is stored in
- the iSNS database as the Entity Protocol. The initial set of values
- to be maintained by IANA for Entity Protocol is indicated in the
-
-
-
-Tseng, et al. Standards Track [Page 107]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- table in Section 6.2.2. Additional values for new block storage
- protocols to be supported by iSNS SHALL be assigned by the IPS WG
- Chairperson, or by a Designated Expert [RFC2434] appointed by the
- IETF Transport Area Director.
-
-8.2. Registry of Standard iSNS Attributes
-
- IANA is responsible for creating and maintaining the Registry of
- Standard iSNS Attributes. The initial list of iSNS attributes is
- described in Section 6. For each iSNS attribute this information
- MUST include, its tag value, the attribute length, and the tag values
- for the set of permissible registration and query keys that can be
- used for that attribute. The initial list of iSNS attributes to be
- maintained by IANA is indicated in Section 6.1.
-
- Additions of new standard attributes to the Registry of Standard iSNS
- Attributes SHALL require IETF Consensus [RFC2434]. The RFC required
- for this process SHALL specify use of tag values reserved for IANA
- allocation in Section 6.1. The RFC SHALL specify as a minimum, the
- new attribute tag value, attribute length, and the set of permissible
- registration and query keys that can be used for the new attribute.
- The RFC SHALL also include a discussion of the reasons for the new
- attribute(s) and how the new attribute(s) are to be used.
-
- As part of the process of obtaining IETF Consensus, the proposed RFC
- and its supporting documentation SHALL be made available to the IPS
- WG mailing list or, if the IPS WG is disbanded at the time, to a
- mailing list designated by the IETF Transport Area Director. The
- review and comment period SHALL last at least three months before the
- IPS WG Chair or a person designated by the IETF Transport Area
- Director decides either to reject the proposal or to forward the
- draft to the IESG for publication as an RFC. When the specification
- is published as an RFC, then IANA will register the new iSNS
- attribute(s) and make the registration available to the community.
-
-8.3. Block Structure Descriptor (BSD) Registry
-
- Note that IANA is already responsible for assigning and maintaining
- values used for the Block Structure Descriptor for the iSNS
- Authentication Block (see Section 5.5). Section 15 of [RFC2608]
- describes the process for allocation of new BSD values.
-
-
-
-
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 108]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-9. Normative References
-
- [iSCSI] Satran, J., Meth, K., Sapuntzakis, C., Chadalapaka, M.,
- and E. Zeidner, "Internet Small Computer Systems
- Interface (iSCSI)", RFC 3720, April 2004.
-
- [iFCP] Monia, C., Mullendore, R., Travostino, F., Jeong, W.,
- and M. Edwards, "iFCP - A Protocol for Internet Fibre
- Channel Storage Networking", RFC 4172, September 2005.
-
- [iSNSOption] Monia, C., Tseng, J., and K. Gibbons, The IPv4 Dynamic
- Host Configuration Protocol (DHCP) Option for the
- Internet Storage Name Service, RFC 4174, September 2005.
-
- [RFC2608] Guttman, E., Perkins, C., Veizades, J., and M. Day,
- "Service Location Protocol, Version 2 ", RFC 2608, June
- 1999.
-
- [iSCSI-SLP] Bakke, M., Hufferd, J., Voruganti, K., Krueger, M., and
- T. Sperry, "Finding Internet Small Computer Systems
- Interface (iSCSI) Targets and Name Servers by Using
- Service Location Protocol version 2 (SLP), RFC 4018,
- April 2005.
-
- [iSCSI-boot] Sarkar, P., Missimer, D., and C. Sapuntzakis,
- "Bootstrapping Clients using the Internet Samll Computer
- System Interface (iSCSI) Protocol", RFC 4173, September
- 2005.
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [STRINGPREP] Bakke, M., "String Profile for Internet Small Computer
- Systems Interface (iSCSI) Names", RFC 3722, April 2004.
-
- [NAMEPREP] Hoffman, P. Nameprep: A Stringprep Profile for
- Internationalized Domain Names, July 2002.
-
- [RFC2407] Piper, D., "The Internet IP Security Domain of
- Interpretation for ISAKMP", RFC 2407, November 1998.
-
- [RFC2408] Maughan, D., Schertler, M., Schneider, M., and J.
- Turner, "Internet Security Association and Key
- Management Protocol (ISAKMP)", RFC 2408, November 1998.
-
- [RFC2409] Harkins, D. and D. Carrel, "The Internet Key Exchange
- (IKE)", RFC 2409, November 1998.
-
-
-
-
-Tseng, et al. Standards Track [Page 109]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- [EUI-64] Guidelines for 64-bit Global Identifier (EUI-64)
- Registration Authority, May 2001, IEEE
-
- [RFC3279] Bassham, L., Polk, W., and R. Housley, "Algorithms and
- Identifiers for the Internet X.509 Public Key
- Infrastructure Certificate and Certificate Revocation
- List (CRL) Profile", RFC 3279, April 2002.
-
- [RFC3280] Housley, R., Polk, W., Ford, W., and D. Solo, "Internet
- X.509 Public Key Infrastructure Certificate and
- Certificate Revocation List (CRL) Profile", RFC 3280,
- April 2002.
-
- [802-1990] IEEE Standards for Local and Metropolitan Area Networks:
- Overview and Architecture, Technical Committee on
- Computer Communications of the IEEE Computer Society,
- May 31, 1990
-
- [FC-FS] Fibre Channel Framing and Signaling Interface, NCITS
- Working Draft Project 1331-D
-
-10. Informative References
-
- [iSNSMIB] Gibbons, K., et al., "Definitions of Managed Objects for
- iSNS (Internet Storage name Service)", Work in Progress,
- July 2003.
-
- [X.509] ITU-T Recommendation X.509 (1997 E): Information
- Technology - Open Systems Interconnection - The
- Directory: Authentication Framework, June 1997
-
- [FC-GS-4] Fibre Channel Generic Services-4 (work in progress),
- NCITS Working Draft Project 1505-D
-
- [RFC1510] Kohl, J. and C. Neuman, "The Kerberos Network
- Authentication Service (V5)", RFC 1510, September 1993.
-
- [RFC2025] Adams, C., "The Simple Public-Key GSS-API Mechanism
- (SPKM)", RFC 2025, October 1996.
-
- [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an
- IANA Considerations Section in RFCs", BCP 26, RFC 2434,
- October 1998.
-
- [RFC2945] Wu, T., "The SRP Authentication and Key Exchange
- System", RFC 2945, September 2000.
-
-
-
-
-
-Tseng, et al. Standards Track [Page 110]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- [RFC1994] Simpson, W., "PPP Challenge Handshake Authentication
- Protocol (CHAP)", RFC 1994, August 1996.
-
- [RFC2131] Droms, R., "Dynamic Host Configuration Protocol", RFC
- 2131, March 1997.
-
- [RFC3410] Case, J., Mundy, R., Partain, D., and B. Stewart,
- "Introduction and Applicability Statements for
- Internet-Standard Management Framework", RFC 3410,
- December 2002.
-
- [RFC3411] Harrington, D., Presuhn, R., and B. Wijnen, "An
- Architecture for Describing Simple Network Management
- Protocol (SNMP) Management Frameworks", STD 62, RFC
- 3411, December 2002.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 111]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-Appendix A: iSNS Examples
-
-A.1. iSCSI Initialization Example
-
- This example assumes an SLP Service Agent (SA) has been implemented
- on the iSNS host, and an SLP User Agent (UA) has been implemented on
- the iSNS initiator. See [RFC2608] for further details on SAs and
- UAs. This example also assumes that the target is configured to use
- the iSNS server, and have its access control policy subordinated to
- the iSNS server.
-
-A.1.1. Simple iSCSI Target Registration
-
- In this example, a simple target with a single iSCSI name registers
- with the iSNS server. The target is represented in the iSNS by an
- Entity containing one Storage Node, one Portal, and an implicitly
- registered Portal Group that provides a relationship between the
- Storage Node and Portal. The target has not been assigned a Fully
- Qualified Domain Name (FQDN) by the administrator. In this example,
- because a PG object is not explicitly registered, a Portal Group with
- a PGT of 1 is implicitly registered. In this example SLP is used to
- discover the location of the iSNS Server. An alternative is to use
- the iSNS DHCP option [iSNSOption] to discover the iSNS server.
-
- +--------------------------+------------------+-------------------+
- | iSCSI Target Device | iSNS Server |Management Station |
- +--------------------------+------------------+-------------------+
- |Discover iSNS--SLP------->| |/*mgmt station is |
- | |<--SLP--iSNS Here:| administratively |
- | | 192.0.2.100 | authorized to view|
- | | | all DDs. Device |
- | DevAttrReg--------->| | NAMEabcd was |
- |Src:(tag=32) "NAMEabcd" | | previously placed |
- |Key: <none present> | | into DDabcd along |
- |Oper Attrs: | | with devpdq and |
- |tag=1: NULL | | devrst. |
- |tag=2: "iSCSI" | | |
- |tag=16: 192.0.2.5 | | |
- |tag=17: 5001 | | |
- |tag=32: "NAMEabcd" | | |
- |tag=33: target | | |
- |tag=34: "disk 1" | | |
- | |<---DevAttrRegRsp | |
- | |SUCCESS | |
- | |Key:(tag=1) "isns:0001" |
- | |Oper Attrs: | |
- | |tag=1: "isns:0001"| |
- | |tag=2: "iSCSI" | |
-
-
-
-Tseng, et al. Standards Track [Page 112]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- | |tag=16: 192.0.2.5 | |
- | |tag=17: 5001 | |
- | |tag=32: "NAMEabcd"|/* previously |
- | |tag=33: target | placed in a DD */ |
- | |tag=34: "disk 1" | |
- | | | |
- | | SCN-------->| |
- | |(or SNMP notification) |
- | |dest:(tag=32):"MGMTname1" |
- | |time:(tag=4): <current time> |
- | |tag=35: "MGT-SCN, OBJ-ADD" |
- | |tag=32: "NAMEabcd"| |
- | | |<-------SCNRsp |
- | DevAttrQry--------->| | |
- |Src:(tag=32) "NAMEabcd" | | |
- |Key:(tag=33) "initiator" | | |
- |Oper Attrs: | | |
- |tag=16: NULL | | |
- |tag=17: NULL | | |
- |tag=32: NULL | | |
- |/*Query asks for all initr| | |
- |devices' IP address, port |<---DevAttrQryRsp | |
- |number, and Name*/ |SUCCESS | |
- | |tag=16:192.0.2.1 | |
- | |tag=17:50000 | |
- | |tag=32:"devpdq" | |
- | |tag=16:192.0.2.2 | |
- | |tag=17:50000 | |
- | |tag=32:"devrst" | |
- |/*************************| |<-----DevAttrQry |
- |Our target "NAMEabcd" | |src: "MGMTname1" |
- |discovers two initiators | key:(tag=32)"NAMEabcd"
- |in shared DDs. It will | |Op Attrs: |
- |accept iSCSI logins from | |tag=16: NULL |
- |these two identified | |tag=17: NULL |
- |initiators presented by | |tag=32: NULL |
- |iSNS | | |
- |*************************/| DevAttrQryRsp--->| |
- | |SUCCESS | |
- | |tag=16: 192.0.2.5 | |
- | |tag=17: 5001 | |
- | |tag=32: "NAMEabcd"| |
- +--------------------------+------------------+-------------------+
-
-
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 113]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-A.1.2. Target Registration and DD Configuration
-
- In this example, a more complex target, with two Storage Nodes and
- two Portals using ESI monitoring, registers with the iSNS. This
- target has been configured with a Fully Qualified Domain Name (FQDN)
- in the DNS servers, and the user wishes to use this identifier for
- the device. The target explicitly registers Portal Groups to
- describe how each Portal provides access to each Storage Node. One
- target Storage Node allows coordinated access through both Portals.
- The other Storage Node allows access, but not coordinated access,
- through both Portals.
-
- +--------------------------+------------------+-------------------+
- | iSCSI Target Device | iSNS Server |Management Station |
- +--------------------------+------------------+-------------------+
- |Discover iSNS--SLP--> | |/*mgmt station is |
- | |<--SLP--iSNS Here:| administratively |
- | | 192.0.2.100 | authorized to view|
- | DevAttrReg--> | | all DDs */ |
- |Src: | | |
- |tag=32: "NAMEabcd" | | |
- |Msg Key: | | |
- |tag=1: "jbod1.example.com"| | |
- |Oper Attrs: | | |
- |tag=1: "jbod1.example.com"| | |
- |tag=2: "iSCSI" | | |
- |tag=16: 192.0.2.4 | | |
- |tag=17: 5001 | | |
- |tag=19: 5 | | |
- |tag=20: 5002 | | |
- |tag=16: 192.0.2.5 | | |
- |tag=17: 5001 | | |
- |tag=19: 5 | | |
- |tag=20: 5002 | | |
- |tag=32: "NAMEabcd" | | |
- |tag=33: "Target" | | |
- |tag=34: "Storage Array 1" | | |
- |tag=51: 10 | | |
- |tag=49: 192.0.2.4 | | |
- |tag=50: 5001 | | |
- |tag=49: 192.0.2.5 | | |
- |tag=50: 5001 | | |
- |tag=32: "NAMEefgh" | | |
- |tag=33: "Target" | | |
- |tag=34: "Storage Array 2" |/*****************| |
- |tag=51: 20 |jbod1.example.com is |
- |tag=49: 192.0.2.4 |now registered in | |
- |tag=50: 5001 |iSNS, but is not | |
-
-
-
-Tseng, et al. Standards Track [Page 114]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- |tag=51: 30 |in any DD. Therefore, |
- |tag=49: 192.0.2.5 |no other devices | |
- |tag=50: 5001 |can "see" it. | |
- | |*****************/| |
- | |<--DevAttrRegRsp | |
- | |SUCCESS | |
- | |Msg Key: | |
- | |tag=1: "jbod1.example.com" |
- | |Oper Attrs: | |
- | |tag=1: "jbod1.example.com" |
- | |tag=2: "iSCSI" | |
- | |tag=16: 192.0.2.4 | |
- | |tag=17: 5001 | |
- | |tag=19: 5 | |
- | |tag=20: 5002 | |
- | |tag=16: 192.0.2.5 | |
- | |tag=17: 5001 | |
- | |tag=19: 5 | |
- | |tag=20: 5002 | |
- | |tag=32: "NAMEabcd"| |
- | |tag=33: "Target" | |
- | |tag=34: "Storage Array 1" |
- | |tag=48: "NAMEabcd"| |
- | |tag=49: 192.0.2.4 | |
- | |tag=50: 5001 | |
- | |tag=51: 10 | |
- | |tag=48: "NAMEabcd"| |
- | |tag=49: 192.0.2.5 | |
- | |tag=50: 5001 | |
- | |tag=51: 10 | |
- | |tag=32: "NAMEefgh"| |
- | |tag=33: "Target" | |
- | |tag=34: "Storage Array 2" |
- | |tag=43: X.509 cert| |
- | |tag=48: "NAMEefgh"| |
- | |tag=49: 192.0.2.4 | |
- | |tag=50: 5001 | |
- | |tag=51: 20 | |
- | |tag=48: "NAMEefgh"| |
- | |tag=49: 192.0.2.5 | |
- | |tag=50: 5001 | |
- | |tag=51: 30 | |
- | | | |
- | | SCN------> | |
- | | (or SNMP notification) |
- | |dest:(tag=32)"mgmt.example.com" |
- | |time:(tag=4): <current time> |
- | |tag=35: "MGT-SCN, OBJ-ADD" |
-
-
-
-Tseng, et al. Standards Track [Page 115]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- | |tag=32: "NAMEabcd"| |
- | |tag=35: "MGT-SCN, OBJ-ADD" |
- | |tag=32: "NAMEefgh"| |
- | | |<--SCNRsp |
- | | |SUCCESS |
- | | tag=32:"mgmt.example.com"|
- | | | |
- | | |<--DevAttrQry |
- | | |Src: |
- | | tag=32:"mgmt.example.com"
- | | |Msg Key: |
- | | |tag=32: "NAMEabcd" |
- | | |Oper Attrs: |
- | | |tag=16: <0-length> |
- | | |tag=17: <0-length> |
- | | |tag=32: <0-length> |
- | | | |
- | | DevAttrQryRsp--> | |
- | |SUCCESS | |
- | |Msg Key: | |
- | |tag=32: "NAMEabcd"| |
- | |Oper Attrs: | |
- | |tag=16: 192.0.2.4 | |
- | |tag=17: 5001 | |
- | |tag=32:"NAMEabcd" | |
- | |tag=16: 192.0.2.5 | |
- | |tag=17: 5001 | |
- | |tag=32:"NAMEabcd" | |
- | | |Src: |
- | | tag=32:"mgmt.example.com"
- | | |Msg Key: |
- | | |tag=32: "NAMEefgh" |
- | | |Oper Attrs: |
- | | |tag=16: <0-length> |
- | | |tag=17: <0-length> |
- | | |tag=32: <0-length> |
- | | | |
- | | DevAttrQryRsp--> | |
- | |SUCCESS | |
- | |Msg Key: | |
- | |tag=32: "NAMEefgh"| |
- | |Oper Attrs: | |
- | |tag=16: 192.0.2.4 | |
- | |tag=17: 5001 | |
- | |tag=32:"NAMEefgh" | |
- | |tag=16: 192.0.2.5 |/**Mgmt Station ***|
- | |tag=17: 5001 |displays device, |
- | |tag=32:"NAMEefgh" |the operator decides
-
-
-
-Tseng, et al. Standards Track [Page 116]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- | | |to place "NAMEabcd"|
- | | |into Domain "DDxyz"|
- |/*************************| |******************/|
- |Target is now registered | | |
- |in iSNS. It is then placed| |<--DDReg |
- |in a pre-existing DD with | |Src: |
- |DD_ID 123 by a management | tag=32:"mgmt.example.com"
- |station. | |Msg Key: |
- |*************************/| |tag=2065: 123 |
- | | |Oper Attrs: |
- | | |tag=2068: "NAMEabcd"
- | | DDRegRsp-----> | |
- | |SUCCESS | |
- | |Msg Key: | |
- | |tag=2065: 123 | |
- | |Oper Attrs: | |
- | |tag=2065: 123 | |
- +--------------------------+------------------+-------------------+
-
-A.1.3. Initiator Registration and Target Discovery
-
- The following example illustrates a new initiator registering with
- the iSNS, and discovering the target NAMEabcd from the example in
- A.1.2.
-
- +--------------------------+------------------+-------------------+
- | iSCSI Initiator | iSNS |Management Station |
- +--------------------------+------------------+-------------------+
- |Discover iSNS--SLP--> | |/*mgmt station is |
- | |<--SLP--iSNS Here:| administratively |
- | | 192.36.53.1 | authorized to view|
- |DevAttrReg--> | | all DDs ********/ |
- |Src: | | |
- |tag=32: "NAMEijkl" | | |
- |Msg Key: | | |
- |tag=1: "svr1.example.com" | | |
- |Oper Attrs: | | |
- |tag=1: "svr1.example.com" | | |
- |tag=2: "iSCSI" | | |
- |tag=16: 192.20.3.1 |/*****************| |
- |tag=17: 5001 |Device not in any | |
- |tag=19: 5 |DD, so it is | |
- |tag=20: 5002 |inaccessible by | |
- |tag=32: "NAMEijkl" |other devices | |
- |tag=33: "Initiator" |*****************/| |
- |tag=34: "Server1" | | |
- |tag=51: 11 | | |
- |tag=49: 192.20.3.1 | | |
-
-
-
-Tseng, et al. Standards Track [Page 117]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- |tag=50: 5001 | | |
- | |<--DevAttrRegRsp | |
- | |SUCCESS | |
- | |Msg Key: | |
- | |tag=1: "svr1.example.com" |
- | |Oper Attrs: | |
- | |tag=1: "svr1.example.com" |
- | |tag=2: "iSCSI" | |
- | |tag=16: 192.20.3.1| |
- | |tag=17: 5001 | |
- | |tag=19: 5 | |
- | |tag=20: 5002 | |
- | |tag=32: "NAMEijkl"| |
- | |tag=33: "Initiator" |
- | |tag=34: "Server1" | |
- | |tag=48: "NAMEijkl"| |
- | |tag=49: 192.20.3.1| |
- | |tag=50: 5001 | |
- | |tag=51: 11 | |
- | | | |
- | | SCN------> | |
- | | (or SNMP notification) |
- | |dest:(tag=32)"mgmt.example.com" |
- | |time:(tag=4): <current time> |
- | |tag=35: "MGT-SCN, OBJ-ADD" |
- | |tag=32: "NAMEijkl"| |
- | | | |
- | | |<------SCNRsp |
- | | |SUCCESS |
- | | tag=32:"mgmt.example.com"
- | | | |
- |SCNReg--> | | |
- |Src: | | |
- |tag=32: "NAMEijkl" | | |
- |Msg Key: | | |
- |tag=32: "NAMEijkl" | | |
- |Oper Attrs: | | |
- |tag=35: <TARG&SELF, OBJ-RMV/ADD/UPD> | |
- | |<--SCNRegRsp | |
- | |SUCCESS | |
- | | | |
- | | |<----DevAttrQry |
- | | |Src: |
- | | tag=32:"mgmt.example.com"
- | | |Msg Key: |
- | | |tag=32: "NAMEijkl" |
- | | |Oper Attrs: |
- | | |tag=16: <0-length> |
-
-
-
-Tseng, et al. Standards Track [Page 118]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- | | |tag=17: <0-length> |
- | | |tag=32: <0-length> |
- | | DevAttrQryRsp--->| |
- | |SUCCESS | |
- | |Msg Key: | |
- | |tag=32: "NAMEijkl"| |
- | |Oper Attrs: | |
- | |tag=16:192.20.3.1 | |
- | |tag=17: 5001 | |
- | |tag=32:"NAMEijkl" | |
- | | |/**Mgmt Station ***|
- | | |displays device, the
- | | |operator decides to|
- | | |place "NAMEijkl" into
- | | |pre-existing Disc |
- | | |Domain "DDxyz" with|
- | | |device NAMEabcd |
- | | |******************/|
- | | |<--DDReg |
- | | |Src: |
- | | tag=32:"mgmt.example.com"
- | | |Msg Key: |
- | | |tag=2065: 123 |
- | | |Oper Attrs: |
- | | |tag=2068: "NAMEijkl"
- | | | |
- | | DDRegRsp---->| |
- | |SUCCESS | |
- | |Msg Key: | |
- | |tag=2065: 123 | |
- | |Oper Attrs: | |
- | |tag=2065: 123 |/******************|
- | | |"NAMEijkl" has been|
- | | |moved to "DDxyz" |
- | | |******************/|
- | | SCN------>| |
- | |dest:(tag=32)"mgmt.example.com" |
- | |time:(tag=4): <current time> |
- | |tag=35: <MGT-SCN, DD/DDS-MBR-ADD> |
- | |tag=2065: 123 | |
- | |tag=2068: "NAMEijkl" |
- | | | |
- | | |<------SCNRsp |
- | | |SUCCESS |
- | | tag=32:"mgmt.example.com"
- | |<-----SCN | |
- | |dest:(tag=32)"NAMEijkl" |
- | |time:(tag=4): <current time> |
-
-
-
-Tseng, et al. Standards Track [Page 119]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- | |tag=35: <TARG&SELF, OBJ-ADD> |
- | |tag=32: "NAMEijkl"| |
- | SCNRsp------> | | |
- |SUCCESS | | |
- |tag=32:"NAMEijkl" | | |
- | | | |
- | |/*****************| |
- | |Note that NAMEabcd| |
- | |also receives an | |
- | |SCN that NAMEijkl | |
- | |is in the same DD | |
- | |*****************/| |
- | (to "NAMEabcd")|<-----SCN | |
- | |dest:(tag=32)"NAMEabcd" |
- | |time:(tag=4): <current time> |
- | |tag=35: <INIT&SELF, OBJ-ADD> |
- | |tag=32: "NAMEijkl"| |
- | SCNRsp------> | | |
- |SUCCESS | | |
- |tag=32:"NAMEabcd" | | |
- | | | |
- | DevAttrQry----------->| | |
- |Src: | | |
- |tag=32: "NAMEijkl" | | |
- |Msg Key: | | |
- |tag=33: "Target" | | |
- |Oper Attrs: | | |
- |tag=16: <0-length> | | |
- |tag=17: <0-length> | | |
- |tag=32: <0-length> | | |
- |tag=34: <0-length> | | |
- |tag=43: <0-length> | | |
- |tag=48: <0-length> | | |
- |tag=49: <0-length> | | |
- |tag=50: <0-length> | | |
- |tag=51: <0-length> | | |
- | |<--DevAttrQryRsp | |
- | |SUCCESS | |
- | |Msg Key: | |
- | |tag=33:"Target" | |
- | |Oper Attrs: | |
- | |tag=16: 192.0.2.4 | |
- | |tag=17: 5001 | |
- | |tag=32: "NAMEabcd"| |
- | |tag=34: "Storage Array 1" |
- | |tag=16: 192.0.2.5 | |
- | |tag=17: 5001 | |
- | |tag=32: "NAMEabcd"| |
-
-
-
-Tseng, et al. Standards Track [Page 120]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
- | |tag=34: "Storage Array 1" |
- | |tag=43: X.509 cert| |
- | |tag=48: "NAMEabcd"| |
- | |tag=49: 192.0.2.4 | |
- | |tag=50: 5001 | |
- | |tag=51: 10 | |
- | |tag=48: "NAMEabcd"| |
- | |tag=49: 192.0.2.5 | |
- | |tag=50: 5001 | |
- | |tag=51: 10 | |
- | | | |
- |/***The initiator has discovered | |
- |the target, and has everything | |
- |needed to complete iSCSI login | |
- |The same process occurs on the | |
- |target side; the SCN prompts the | |
- |target to download the list of | |
- |authorized initiators from the | |
- |iSNS (i.e., those initiators in the | |
- |same DD as the target.************/ | |
- +--------------------------+------------------+-------------------+
-
-Acknowledgements
-
- Numerous individuals contributed to the creation of this document
- through their careful review and submissions of comments and
- recommendations. We acknowledge the following persons for their
- technical contributions to this document: Mark Bakke (Cisco), John
- Hufferd (IBM), Julian Satran (IBM), Kaladhar Voruganti(IBM), Joe Czap
- (IBM), John Dowdy (IBM), Tom McSweeney (IBM), Jim Hafner (IBM), Chad
- Gregory (Intel), Yaron Klein (Sanrad), Larry Lamers (Adaptec), Jack
- Harwood (EMC), David Black (EMC), David Robinson (Sun), Alan Warwick
- (Microsoft), Bob Snead (Microsoft), Fa Yoeu (Intransa), Joe White
- (McDATA), Charles Monia (McDATA), Larry Hofer (McDATA), Ken Hirata
- (Vixel), Howard Hall (Pirus), Malikarjun Chadalapaka (HP), Marjorie
- Krueger (HP), Siva Vaddepuri (McDATA), and Vinai Singh (American
- Megatrends).
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 121]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-Authors' Addresses
-
- Josh Tseng
- Riverbed Technology
- 501 2nd Street, Suite 410
- San Francisco, CA 94107
-
- Phone: (650)274-2109
- EMail: joshtseng@yahoo.com
-
-
- Kevin Gibbons
- McDATA Corporation
- 4555 Great America Parkway
- Santa Clara, CA 95054-1208
-
- Phone: (408) 567-5765
- EMail: kevin.gibbons@mcdata.com
-
-
- Franco Travostino
- Nortel
- 600 Technology Park Drive
- Billerica, MA 01821 USA
-
- Phone: (978) 288-7708
- EMail: travos@nortel.com
-
-
- Curt du Laney
- Rincon Research Corporation
- 101 North Wilmot Road, Suite 101
- Tucson AZ 85711
-
- Phone: (520) 519-4409
- EMail: cdl@rincon.com
-
-
- Joe Souza
- Microsoft Corporation
- One Microsoft Way
- Redmond, WA 98052-6399
-
- Phone: (425) 706-3135
- EMail: joes@exmsft.com
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 122]
-
-RFC 4171 Internet Storage Name Service (iSNS) September 2005
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2005).
-
- This document is subject to the rights, licenses and restrictions
- contained in BCP 78, and except as set forth therein, the authors
- retain all their rights.
-
- This document and the information contained herein are provided on an
- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Intellectual Property
-
- The IETF takes no position regarding the validity or scope of any
- Intellectual Property Rights or other rights that might be claimed to
- pertain to the implementation or use of the technology described in
- this document or the extent to which any license under such rights
- might or might not be available; nor does it represent that it has
- made any independent effort to identify any such rights. Information
- on the procedures with respect to rights in RFC documents can be
- found in BCP 78 and BCP 79.
-
- Copies of IPR disclosures made to the IETF Secretariat and any
- assurances of licenses to be made available, or the result of an
- attempt made to obtain a general license or permission for the use of
- such proprietary rights by implementers or users of this
- specification can be obtained from the IETF on-line IPR repository at
- http://www.ietf.org/ipr.
-
- The IETF invites any interested party to bring to its attention any
- copyrights, patents or patent applications, or other proprietary
- rights that may cover technology that may be required to implement
- this standard. Please address the information to the IETF at ietf-
- ipr@ietf.org.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-Tseng, et al. Standards Track [Page 123]
-
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/utils/open-isns/Makefile.in open-iscsi-2.0-872-rc4-bnx2i.work/utils/open-isns/Makefile.in
--- open-iscsi-2.0-872-rc4-bnx2i/utils/open-isns/Makefile.in 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/utils/open-isns/Makefile.in 2012-03-05 23:02:46.000000000 -0600
@@ -32,7 +32,6 @@ LIBOBJS = server.o \
security.o \
authblock.o \
policy.o \
- pki.o \
register.o \
query.o \
getnext.o \
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/utils/open-isns/objects.h open-iscsi-2.0-872-rc4-bnx2i.work/utils/open-isns/objects.h
--- open-iscsi-2.0-872-rc4-bnx2i/utils/open-isns/objects.h 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/utils/open-isns/objects.h 2012-03-05 23:02:46.000000000 -0600
@@ -83,6 +83,7 @@ struct isns_object {
isns_attr_list_t ie_attrs;
isns_object_t * ie_container;
+ uint32_t ie_container_idx;
isns_object_template_t *ie_template;
isns_relation_t * ie_relation;
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/utils/open-isns/security.h open-iscsi-2.0-872-rc4-bnx2i.work/utils/open-isns/security.h
--- open-iscsi-2.0-872-rc4-bnx2i/utils/open-isns/security.h 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/utils/open-isns/security.h 2012-03-05 23:03:38.000000000 -0600
@@ -6,11 +6,16 @@
#ifndef ISNS_SECURITY_H
#define ISNS_SECURITY_H
-
-#include <openssl/evp.h>
#include "buffer.h"
#include "util.h"
+
+#ifdef WITH_SECURITY
+#include <openssl/evp.h>
+#else
+#define EVP_PKEY void
+#endif
+
/*
* Security context
*/
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/utils/open-isns/socket.c open-iscsi-2.0-872-rc4-bnx2i.work/utils/open-isns/socket.c
--- open-iscsi-2.0-872-rc4-bnx2i/utils/open-isns/socket.c 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/utils/open-isns/socket.c 2012-03-05 23:02:46.000000000 -0600
@@ -562,7 +562,7 @@ void
isns_net_stream_accept(isns_socket_t *sock)
{
isns_socket_t *child;
- size_t optlen;
+ socklen_t optlen;
int fd, passcred = 0;
fd = accept(sock->is_desc, NULL, NULL);
@@ -805,7 +805,7 @@ isns_net_stream_xmit(isns_socket_t *sock
void
isns_net_stream_hup(isns_socket_t *sock)
{
- sock->is_poll_mask &= ~POLLIN;
+ sock->is_poll_mask &= ~(POLLIN|POLLOUT);
/* POLLHUP while connecting means we failed */
if (sock->is_state == ISNS_SOCK_CONNECTING)
isns_net_stream_error(sock, ECONNREFUSED);
diff -Naurp open-iscsi-2.0-872-rc4-bnx2i/utils/open-isns/util.h open-iscsi-2.0-872-rc4-bnx2i.work/utils/open-isns/util.h
--- open-iscsi-2.0-872-rc4-bnx2i/utils/open-isns/util.h 2010-07-11 04:05:58.000000000 -0500
+++ open-iscsi-2.0-872-rc4-bnx2i.work/utils/open-isns/util.h 2012-03-05 23:03:38.000000000 -0600
@@ -9,6 +9,7 @@
#include <sys/types.h>
#include <stdint.h>
+#include <stdlib.h>
#include <stdio.h>
#include <stddef.h>
#include <string.h> // for strdup