Case looks straight-forward, but the tunable names for use on the CLI
are rather awkward. In other instances you have separated multi words
such as target-param with hyphens, whereas your tunables are all jammed
together.
I'd recommend tweaking the names somewhat to make them more
readable/user-friendly.
But +1 in any case.
- Garrett
John Forte wrote:
> 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
>
>
