ANSI INCITS 411-2007 for Information Technology - iSCSI Management API.pdf

1、American National StandardDeveloped byfor Information Technology iSCSI Management APIANSI INCITS 411-2007ANSIINCITS411-2007ANSIINCITS 411-2007American National Standardfor Information Technology iSCSI Management APISecretariatInformation Technology Industry CouncilApproved August 17, 2007American Na

2、tional Standards Institute, Inc.Approval of an American National Standard requires review by ANSI that therequirements for due process, consensus, and other criteria for approval havebeen met by the standards developer.Consensus is established when, in the judgement of the ANSI Board ofStandards Rev

3、iew, substantial agreement has been reached by directly andmaterially affected interests. Substantial agreement means much more thana simple majority, but not necessarily unanimity. Consensus requires that allviews and objections be considered, and that a concerted effort be madetowards their resolu

4、tion.The use of American National Standards is completely voluntary; theirexistence does not in any respect preclude anyone, whether he has approvedthe standards or not, from manufacturing, marketing, purchasing, or usingproducts, processes, or procedures not conforming to the standards.The American

5、 National Standards Institute does not develop standards andwill in no circumstances give an interpretation of any American NationalStandard. Moreover, no person shall have the right or authority to issue aninterpretation of an American National Standard in the name of the AmericanNational Standards

6、 Institute. Requests for interpretations should beaddressed to the secretariat or sponsor whose name appears on the titlepage of this standard.CAUTION NOTICE: This American National Standard may be revised orwithdrawn at any time. The procedures of the American National StandardsInstitute require th

7、at action be taken periodically to reaffirm, revise, orwithdraw this standard. Purchasers of American National Standards mayreceive current information on all standards by calling or writing the AmericanNational Standards Institute.American National StandardPublished byAmerican National Standards In

8、stitute, Inc.25 West 43rd Street, New York, NY 10036Copyright 2006 by Information Technology Industry Council (ITI)All rights reserved.No part of this publication may be reproduced in anyform, in an electronic retrieval system or otherwise,without prior written permission of ITI, 1250 Eye Street NW,

9、 Washington, DC 20005. Printed in the United States of AmericaCAUTION: The developers of this standard have requested that holders of patents that may berequired for the implementation of the standard disclose such patents to the publisher. However,neither the developers nor the publisher have under

10、taken a patent search in order to identifywhich, if any, patents may apply to this standard. As of the date of publication of this standardand following calls for the identification of patents that may be required for the implementation ofthe standard, no such claims have been made. No further paten

11、t search is conducted by the de-veloper or publisher in respect to any standard it processes. No representation is made or impliedthat licenses are not required to avoid infringement in the use of this standard.iContentsPageForeword .viIntroduction .ix1 Scope. 12 References. 23 Document Conventions

12、33.1 API Description Format 34 Background Technical Information 44.1 Terms. 44.2 Concepts 75 Constants and Types. 155.1 IMA_WCHAR. 155.2 IMA_BYTE . 155.3 IMA_BOOL. 155.4 IMA_XBOOL 155.5 IMA_UINT 155.6 IMA_UINT16 155.7 IMA_UINT32 155.8 IMA_UINT64 155.9 IMA_DATETIME 165.10 IMA_OBJECT_VISIBILITY_FN 175

13、.11 IMA_OBJECT_PROPERTY_FN 185.12 IMA_OBJECT_TYPE. 195.13 IMA_STATUS 215.14 IMA_OID 255.15 IMA_OID_LIST. 265.16 IMA_NODE_NAME 275.17 IMA_NODE_ALIAS 285.18 IMA_IP_ADDRESS 295.19 IMA_HOST_NAME 305.20 IMA_HOST_ID. 315.21 IMA_TARGET_ADDRESS. 325.22 IMA_ADDRESS_KEY 335.23 IMA_ADDRESS_KEYS 345.24 IMA_STAT

14、IC_DISCOVERY_TARGET 35iiPage5.25 IMA_DISCOVERY_ADDRESS_PROPERTIES. 365.26 IMA_STATIC_DISCOVERY_TARGET_PROPERTIES. 375.27 IMA_IP_PROPERTIES 385.28 IMA_LIBRARY_PROPERTIES 415.29 IMA_PLUGIN_PROPERTIES 425.30 IMA_NODE_PROPERTIES. 435.31 IMA_LHBA_PROPERTIES 455.32 Upper Level Protocol (ULP) Flags . 475.3

15、3 IMA_PHBA_PROPERTIES . 485.34 IMA_DISCOVERY_PROPERTIES 515.35 IMA_PHBA_DOWNLOAD_IMAGE_TYPE 535.36 IMA_PHBA_DOWNLOAD_IMAGE_PROPERTIES. 545.37 IMA_ISNS_DISCOVERY_METHOD . 555.38 IMA_PHBA_DOWNLOAD_PROPERTIES 565.39 IMA_IPSEC_PROPERTIES 575.40 IMA_MIN_MAX_VALUE 585.41 IMA_BOOL_VALUE. 605.42 IMA_MAC_ADD

16、RESS . 615.43 IMA_LNP_PROPERTIES 625.44 IMA_PNP_PROPERTIES 635.45 IMA_PNP_STATISTICS 655.46 IMA_NETWORK_PORTAL_PROPERTIES 665.47 IMA_PHBA_STATUS 675.48 IMA_ NETWORK_PORT_STATUS. 685.49 IMA_TARGET_DISCOVERY_METHOD . 705.50 IMA_TARGET_PROPERTIES. 715.51 IMA_TARGET_ERROR_STATISTICS 735.52 IMA_LU_PROPER

17、TIES. 755.53 IMA_DEVICE_STATISTICS 775.54 IMA_STATISTICS_PROPERTIES 785.55 IMA_AUTHMETHOD . 795.56 IMA_CHAP_INITIATOR_AUTHPARMS 805.57 IMA_SRP_INITIATOR_AUTHPARMS. 825.58 IMA_KRB5_INITIATOR_AUTHPARMS. 835.59 IMA_SPKM_INITIATOR_AUTHPARMS 84iiiPage5.60 IMA_INITIATOR_AUTHPARMS 856 APIs 866.1 APIs by Ca

18、tegory . 876.1.1 Library and Plugin APIs 876.1.2 Node APIs 876.1.3 Logical HBA APIs. 876.1.4 Physical HBA APIs. 896.1.5 Network Portal APIs . 896.1.6 Logical Network Port (LNP) APIs . 896.1.7 Physical Network Port (PNP) APIs. 906.1.8 Target APIs 906.1.9 Logical Unit (LU) APIs 916.1.10 Miscellaneous

19、APIs 916.2 APIs by Name 936.2.1 IMA_AddDiscoveryAddress . 956.2.2 IMA_AddStaticDiscoveryTarget . 976.2.3 IMA_DeregisterForObjectPropertyChanges 996.2.4 IMA_DeregisterForObjectVisibilityChanges . 1006.2.5 IMA_ExposeLu. 1016.2.6 IMA_FreeMemory 1036.2.7 IMA_GenerateNodeName 1046.2.8 IMA_GetAddressKeys

20、1056.2.9 IMA_GetAssociatedPluginOid 1066.2.10 IMA_GetDataPduInOrderProperties 1076.2.11 IMA_GetDataSequenceInOrderProperties. 1086.2.12 IMA_GetDefaultTime2RetainProperties. 1096.2.13 IMA_GetDefaultTime2WaitProperties 1106.2.14 IMA_GetDeviceStatistics 1116.2.15 IMA_GetDiscoveryAddressOidList. 1136.2.

21、16 IMA_GetDiscoveryAddressProperties 1156.2.17 IMA_GetDiscoveryProperties. 1166.2.18 IMA_GetErrorRecoveryLevelProperties. 1186.2.19 IMA_GetFirstBurstLengthProperties 1196.2.20 IMA_GetImmediateDataProperties 1206.2.21 IMA_GetInitialR2TProperties . 1216.2.22 IMA_GetInitiatorAuthParms . 1226.2.23 IMA_G

22、etInUseInitiatorAuthMethods. 1246.2.24 IMA_GetIpProperties 1266.2.25 IMA_GetIpsecProperties 1276.2.26 IMA_GetLhbaOidList 1286.2.27 IMA_GetLhbaProperties. 1296.2.28 IMA_GetLibraryProperties 1306.2.29 IMA_GetLnpOidList 1316.2.30 IMA_GetLnpProperties. 1326.2.31 IMA_GetLuOid . 1336.2.32 IMA_GetLuOidList

23、 1356.2.33 IMA_GetLuProperties. 1376.2.34 IMA_GetMaxBurstLengthProperties 1386.2.35 IMA_GetMaxConnectionsProperties 1396.2.36 IMA_GetMaxOutstandingR2TProperties 140ivPage6.2.37 IMA_GetMaxRecvDataSegmentLengthProperties 1416.2.38 IMA_GetNetworkPortalOidList. 1426.2.39 IMA_GetNetworkPortalProperties 1

24、436.2.40 IMA_GetNetworkPortStatus. 1446.2.41 IMA_GetNodeProperties 1456.2.42 IMA_GetNonSharedNodeOidList. 1466.2.43 IMA_GetObjectType 1476.2.44 IMA_GetPhbaDownloadProperties 1486.2.45 IMA_GetPhbaOidList . 1496.2.46 IMA_GetPhbaProperties 1506.2.47 IMA_GetPhbaStatus 1516.2.48 IMA_GetPluginOidList . 15

25、26.2.49 IMA_GetPluginProperties 1536.2.50 IMA_GetPnpOidList . 1546.2.51 IMA_GetPnpProperties 1556.2.52 IMA_GetPnpStatistics 1566.2.53 IMA_GetSharedNodeOid. 1586.2.54 IMA_GetStaticDiscoveryTargetOidList 1596.2.55 IMA_GetStaticDiscoveryTargetProperties . 1616.2.56 IMA_GetStatisticsProperties 1626.2.57

26、 IMA_GetSupportedAuthMethods. 1636.2.58 IMA_GetTargetErrorStatistics 1656.2.59 IMA_GetTargetOidList . 1676.2.60 IMA_GetTargetProperties 1696.2.61 IMA_IsPhbaDownloadFile . 1706.2.62 IMA_LuInquiry 1716.2.63 IMA_LuReadCapacity 1746.2.64 IMA_LuReportLuns 1766.2.65 IMA_PhbaDownload 1796.2.66 IMA_PluginIO

27、Ctl 1816.2.67 IMA_RegisterForObjectPropertyChanges . 1836.2.68 IMA_RegisterForObjectVisibilityChanges 1846.2.69 IMA_RemoveDiscoveryAddress 1856.2.70 IMA_RemoveStaleData . 1866.2.71 IMA_RemoveStaticDiscoveryTarget 1876.2.72 IMA_SetDataPduInOrder. 1886.2.73 IMA_SetDataSequenceInOrder . 1906.2.74 IMA_S

28、etDefaultGateway . 1926.2.75 IMA_SetDefaultTime2Retain . 1936.2.76 IMA_SetDefaultTime2Wait 1956.2.77 IMA_SetDnsServerAddress. 1976.2.78 IMA_SetErrorRecoveryLevel . 1996.2.79 IMA_SetFirstBurstLength. 2016.2.80 IMA_SetImmediateData. 2036.2.81 IMA_SetInitialR2T 2056.2.82 IMA_SetInitiatorAuthMethods 206

29、6.2.83 IMA_SetInitiatorAuthParms . 2086.2.84 IMA_SetIpConfigMethod 2106.2.85 IMA_SetIsnsDiscovery. 2126.2.86 IMA_SetMaxBurstLength. 2146.2.87 IMA_SetMaxConnections 2166.2.88 IMA_SetMaxRecvDataSegmentLength . 218vPage6.2.89 IMA_SetMaxOutstandingR2T 2206.2.90 IMA_SetNetworkPortalIpAddress. 2226.2.91 I

30、MA_SetNodeAlias. 2246.2.92 IMA_SetNodeName . 2266.2.93 IMA_SetSendTargetsDiscovery . 2286.2.94 IMA_SetSlpDiscovery 2306.2.95 IMA_SetStaticDiscovery. 2326.2.96 IMA_SetStatisticsCollection . 2346.2.97 IMA_SetSubnetMask . 2366.2.98 IMA_UnexposeLu. 2377 Implementation Compliance. 2398 Notes 2408.1 Clien

31、t Usage Notes 2408.2 Library Implementation Notes 2418.3 Plugin Implementation Notes . 241AnnexesA Device Names 244A.1 osDeviceName Field of the IMA_LHBA_PROPERTIES Structure 244A.2 osDeviceName Field of the IMA_LU_PROPERTIES Structure . 244B Coding Examples. 245B.1 Example of Getting Library Proper

32、ties . 246B.2 Example of Getting Plugin Properties 247B.3 Example of Getting an Associated Plugin ID . 248B.4 Example of Getting Node Properties 249B.5 Example of Setting a Node Name 250B.6 Example of Getting LHBA Properties. 251B.7 Example of Getting PHBA Properties 252B.8 Example of Getting PHBA D

33、iscovery Properties 253B.9 Example of Getting/Setting LHBA Max Burst Length. 254B.10 Example of Getting all LUs of all Targets Visible to a System . 255viForeword (This foreword is not part of American National Standard ANSI INCITS 411-2007.)This standard documents an API that allows a management ap

34、plication to discoverand manage the iSCSI resources on a system. The API uses an architecture that al-lows multiple iSCSI HBAs, sometimes referred to as hardware initiators, and/or multi-ple iSCSI software initiators installed on a system to provide a common interface toclients of the library. This

35、API can be used by host-based management applications.A client of the API should be able to move between platforms by simply recompiling.This standard includes two informative annexes, which are not considered part of thestandardRequests for interpretation, suggestions for improvement and addenda, o

36、r defect re-ports are welcome. They should be sent to the INCITS Secretariat, National Commit-tee for Information Technology Standards, Information Technology Institute, 1250Eye Street, NW, Suite 200, Washington, DC 20005-3922. This standard was processed and approved for submittal to ANSI by the In

37、terNation-al Committee for Information Technology Standards (INCITS). Committee approvalof the standard does not necessarily imply that all committee members voted for itsapproval. At the time it approved this standard, INCITS had the following members:Karen Higginbottom, ChairJennifer Garner, Secre

38、taryOrganization Represented Name of RepresentativeAIM Global Dan MullenCharles Biss (Alt.)Apple Computer, Inc. David MichaelElectronic Industries Alliance Edward Mikoski, Jr.David Thompson (Alt.)EMC Corporation Gary RobinsonFarance, Inc Frank FaranceTimothy Schoechle (Alt.)GS1 US Frank SharkeyJames

39、 Chronowski (Alt.)Mary Wilson (Alt.)Hewlett-Packard Company. Karen HigginbottomSteve Mills (Alt.)Scott Jameson (Alt.)IBM Corporation . Ronald F. SillettiPeter Schirling (Alt.)IEEE . Judith GormanTerry DeCourcelle (Alt.)Bill Ash (Alt.)Jodi Haasz (Alt.)Bob Labelle (Alt.)Intel. Philip WennblomDave Thew

40、lis (Alt.)Jesse Walker (Alt.)Grace Wei (Alt.)Lexmark International . Don WrightDwight Lewis (Alt.)Paul Menard (Alt.)Microsoft Corporation . Jim HughesDon Stanwyck (Alt.)Isabelle Valet-Harper (Alt.)National Institute of Standards some implementations will have the ability to combine connections in a

41、5 ANSI INCITS 411-2007 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 ne

42、ed 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 Tag1This 16-bit quantity identifies the Porta

43、l 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. Primary Discovery Method A discovery method that does not depend upon any other discovery method to discover targets. iSNS target discovery, SLP target

44、discovery, and static target discovery are all primary discovery methods. Secondary Discovery Method A discovery method that depends upon other discovery methods to discover targets. SendTargets target discovery is a secondary discovery method because it cannot discover any targets without using som

45、e other discovery method. Stale Data Stale data is configuration data that refers to targets or logical units that are no longer present or that are no longer visible to the system. For example, setting iSCSI login parameters associated with a target using the IMA_SetFirstBurstLength API and then re

46、moving the target from the network will create stale data because the configuration data thats been set for the target is retained after the target is removed from the network. Similarly, calling the IMA_ExposeLu API for a logical unit and then removing the logical units target from the network will

47、 create stale data because configuration data indicating that the logical unit is exposed is retained after the target is removed from the network. Unicode Unicode is a system of uniquely identifying (numbering) characters such that nearly any character in any language is identified. UTF-82Unicode T

48、ransformation Format, 8-bit encoding form. UTF-8 is the Unicode Transformation Format that serializes a Unicode scalar value as a sequence of one to four bytes. 1 Definition taken from IETF RFC 3720. 2 Definition taken from the glossary of the Unicode Consortium web site. See http:/www.unicode.org/g

49、lossary/index.html. 6 ANSI INCITS 411-2007 4.2 Concepts Library and Plugins The iSCSI Management API shall be implemented in one of two ways: A library. A library in combination with plugins. If an implementation uses a library without plugins then either the plugin functionality is built into the library itself or the library is able to interface with vendor specific modules using a pre-existing interface. These vendor specific modules would provide functionality equivalent to plugins. The library provides an interface that applications use to perform iSCSI management. Among othe