I am sponsoring this fasttrack for Zhang Yi. Requested binding is Patch/Micro.
Timeout is 07/01/2009.
Template Version: @(#)sac_nextcase 1.68 02/23/09 SMI
This information is Copyright 2009 Sun Microsystems
1. Introduction
1.1. Project/Component Working Name:
iSCSI initiator tunables
1.2. Name of Document Author/Supplier:
Author: Zhang Yi
1.3 Date of This Document:
24 June, 2009
2. Project Summary
2.1. Project Description
This project proposes a new management interface to configure several
parameters specific for iSCSI initiator to access a given iSCSI target.
Together with the IMA specification[1] API, management interfaces
are exported in library libima[2] to manage tunable parameters. And
those tunable parameters can be dynamically applied to the iSCSI
initiator driver via iscsiadm or other utilities using the exported
library interface from this project.
4. Technical Description
4.1. Details:
Currently most parameters related to the connection behavior between
the iSCSI initiator and the iSCSI target are hardcoded. It makes iSCSI
initiator in Solaris inflexible to handle various scenarios. For
example, the fixed iSCSI initiator connection retry timer (3 min) is
not suitable in the follow scenarios:
a. Mirrored ZFS over different iSCSI devices. If one of the mirrored
iSCSI devices goes offline, on initiator side whole ZFS pool may
hang for 3 minutes in IO timeout before ZFS degrade the iSCSI
device. Here a shorter timeout value is desirable for this case.
b. iSCSI quorum device on Sun Cluster. If iSCSI quorum device spend
more than 3 minutes to reboot, Cluster node could never online
this iSCSI quorum device after 3 minutes connection retry timeout.
Here a longer timeout value is needed.
This project will add a new option named "-T" for 'iscsiadm' utility
to set these tunable parameters for iSCSI initiator node or a
specified iSCSI target. And tunable parameters will be applied to
iSCSI initiator driver in real time without reboot.
A programmatic interface is also offered through SUN_IMA library.
The modification of 'iscsiadm' will be based on this interface.
*) CLI interface for 'iscsiadm' utility
Apply tunable parameters to a specific target by using:
"iscsiadm modify target-param -T <tunable-prop>=<value> \
<target-name..>".
Apply tunable parameters to initiator node by using:
"iscsiadm modify initiator-node -T <tunable-prop>=<value>".
List specific tunable parameters applied to given target by using:
"iscsiadm list target-param -v [<target-name..>]".
List tunable parameters to initiator node by using:
"iscsiadm list initiator-node".
Example:
Change maximum connection retry time to 30 seconds for iSCSI target
iqn.1986-03.com.sun:2501.600a0b800049c94 will use follow command:
#iscsiadm modify target-param -T connloginmax=30 \
iqn.1986-03.com.sun:2501.600a0b800049c94
Currently supported <tunable-prop> parameters are listed below
with corresponding descriptions.
Tunable Parameter Short Description
-------------------- -------------------
recvloginrsptimeout Session Login Response Time
connloginmax Maximum Connection Retry Time
pollinglogindelay Login Retry Time Interval
The recvloginrsptimeout is to specify how long iSCSI initiator
will wait for the response of iSCSI session login request from
the given iSCSI target. Valid value is from 0 to 60*60, default
to 60 seconds.
The connloginmax is used to determine maximum iSCSI initiator
connection retry time when iSCSI initiator to target IO timeout
or connection failure. Valid value is from 0 to 60*60, default to
180 seconds.
The pollinglogindelay is used to decide time interval between
each iSCSI session login retry when iSCSI initiator to target IO
timeout or connection failure. Valid value is from 0 to 60*60,
default to 60 seconds.
More tunable parameters can be added using the same mechanism
introduced by this project in case there are new requirements
from customer.
*) Programmatic interface for tunable parameters
Programmatic interface API name with new data structure are
defined in the exported new public header file <libsun_ima.h>,
typedef enum {
ISCSI_RX_TIMEOUT_VALUE = 1,
ISCSI_CONN_DEFAULT_LOGIN_MAX = 2,
ISCSI_LOGIN_POLLING_DELAY = 3
} ISCSI_TUNABLE_OBJECT_TYPE;
typedef struct _ISCSI_TUNABLE_PARAM {
ISCSI_TUNABLE_OBJECT_TYPE tunable_objectType,
struct {
IMA_UINT32 len;
IMA_CHAR *chars;
} tunable_objectValue;
} ISCSI_TUNABLE_PARAM;
IMA_API IMA_STATUS
SUN_IMA_GetTunableProperties(IMA_OID oid, ISCSI_TUNABLE_PARAM *param);
is used to get specified tunable parameter.
IMA_API IMA_STATUS
SUN_IMA_SetTunableProperties(IMA_OID oid, ISCSI_TUNABLE_PARAM *param);
is used to set specified tunable parameter.
4.5 Interfaces:
Patch/Micro release binding.
Exported Interface | Stability | Description
--------------------------------|-----------|------------------------------
SUN_IMA_GetTunableProperties | Committed | Interface to get iSCSI
| | tunable parameters
SUN_IMA_SetTunableProperties | Committed | interface to set iSCSI
| | tunable parameters
struct ISCSI_TUNABLE_PARAM | Committed | <libsun_ima.h>
usr/sbin/iscsiadm | Committed | iSCSI initiator CLI
| | PSARC/2003/126
-T | Committed | option apply to iscsiadm
| | subcommand "modify" and object
| | of both "target-param" and
| | "initiator-node"
5. Reference Documents:
[1] SNIA iSCSI Management API -
http://www.snia.org/tech_activities/standards/
curr_standards/ima/iSCSIManagementAPI_v1.1.pdf
[2] iSCSI Management API http://sac.sfbay/SHARC/2005/066/
6. Resources and Schedule
6.4. Steering Committee requested information
6.4.1. Consolidation C-team Name:
ON
6.5. ARC review type: FastTrack
6.6. ARC Exposure: open
