Network Working Group Y. Li Internet-Draft Huawei Technologies Intended status: Standards Track June 20, 2007 Expires: December 22, 2007 Using Smidump to Convert MIB to XSD draft-li-mib-convert-00.txt Status of This Memo By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on December 22, 2007. Copyright Notice Copyright (C) The IETF Trust (2007). Abstract This memo depicts how the smidump tool converts a MIB to an XSD. Li Expires December 22, 2007 [Page 1] Internet-Draft Using Smidump to Convert MIB to XSD June 2007 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Mapping of the Module Definition . . . . . . . . . . . . . . . 3 3. Mapping of the IMPORTS/FROM Clause . . . . . . . . . . . . . . 4 4. Mapping of the MODULE-IDENTITY Macro . . . . . . . . . . . . . 4 4.1. Mapping of the DESCRIPTION Clause . . . . . . . . . . . . 4 5. Mapping of the Managed Objects . . . . . . . . . . . . . . . . 5 5.1. The Flattened Structure of Four Layers . . . . . . . . . . 5 5.2. Deriving of the Third-level Elements . . . . . . . . . . . 7 5.3. Mapping of the Leaf Objects . . . . . . . . . . . . . . . 10 6. Mapping of the Datatypes . . . . . . . . . . . . . . . . . . . 12 7. Security Considerations . . . . . . . . . . . . . . . . . . . 14 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 14 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 15 10.1. Normative References . . . . . . . . . . . . . . . . . . . 15 10.2. Informative References . . . . . . . . . . . . . . . . . . 15 Appendix A. The Smi.xsd File . . . . . . . . . . . . . . . . . . 16 Li Expires December 22, 2007 [Page 2] Internet-Draft Using Smidump to Convert MIB to XSD June 2007 1. Introduction Accessing MIBs using NETCONF [ACC-MIB] describes a simple mechanism for accessing the Management Information Base (MIB), using the existing NETCONF [RFC4741] RPC infrastructure. It uses XSDs [ref.XMLSchema] generated by smidump [ref.libsmi] as data model. This memo depicts how the smidump tool converts a MIB to an XSD, and what the XSD looks like. 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 [RFC2119]. 2. Mapping of the Module Definition The DEFINITIONS ::= BEGIN/END statement is used to start a MIB module definition in the following format: DEFINITIONS ::= BEGIN ... END where is the name of the MIB module, for example, IF- MIB. The DEFINITIONS statement is mapped to XSD as follows: ... Li Expires December 22, 2007 [Page 3] Internet-Draft Using Smidump to Convert MIB to XSD June 2007 3. Mapping of the IMPORTS/FROM Clause The IMPORTS/FROM statement is used to reference external objects from other MIB modules in the following format: IMPORTS [, ... [, ] ] FROM [ ... [, ... [, ] ] FROM ]; Each IMPORTS clause is mapped to two portions: o A declaration of namespace attribute of the element: xmlns:= "http://www.ibr.cs.tu-bs.de/projects/libsmi/xsd/" o A element that imports the foregoing namespace: 4. Mapping of the MODULE-IDENTITY Macro Except for the DESCRIPTION clause of the MODULE-IDENTITY macro, the information contained in the MODULE-IDENTITY macro is discarded. 4.1. Mapping of the DESCRIPTION Clause The DESCRIPTION clause contains a high-level textual description about the contents of this MIB module in the following format: DESCRIPTION "..." The DESCRIPTION clause is mapped to the element in the element, the XSD is as follows: ... Li Expires December 22, 2007 [Page 4] Internet-Draft Using Smidump to Convert MIB to XSD June 2007 5. Mapping of the Managed Objects 5.1. The Flattened Structure of Four Layers The smidump tool does not remain the hierarchy of the MIB tree. A "flattened" structure of the XML instance documents was invented. This flattened structure is divided into four layers, the top two levels are independent of specific MIBs, while the bottom two levels represent the concrete MIB objects. The following figure illustrates the the flattened structure of four layers. | +-- | +--A container of scalar elements (one or more) | | | +--scalar objects | +--An instance of table entry (one or more) | +--columnar objects 1. The element is the root element of an XML instance document. It may contain an arbitrary number of elements. 2. The element is located at the second level. It represents an agent context. It has six attributes: ipaddr: Indicates the IP address of the agent context. The tuple of ipaddr and port and community attribute identifies a context. It must be present. hostname: Indicates the hostname of the agent context. It need not be present. port: Indicates the TCP/UDP port of the agent context. It must be present. community: Indicates the community string of SNMPv1 and SNMPv2c. It must be present. caching: This attribute is used for the implementation of an SNMP-to-XML gateway. It may indicate the expiry time of the cached data that was retrieved from an SNMP agent and that is requested by an XML client. It depends on specific implementation, thus it can be ignored. This attribute need not be present. Li Expires December 22, 2007 [Page 5] Internet-Draft Using Smidump to Convert MIB to XSD June 2007 time: This is a time stamp, which specifies when the context has been created. This allows, for instance, to store data from multiple agents or a series of snapshots of a agent in a single document. It must be present. 3. The third-level elements depend on specific MIBs. They can either represent containers of scalar elements that appear at most once, or instances of objects that are derived from table entries and thus can appear multiple times. Note that the list of these elements is not limited to a single MIB module. While scalar container elements do not have any attributes, the table entry elements include one ore more index attributes to uniquely identify the instances. These attributes are derived from the table entry's INDEX clause. 4. The fourth-level elements represent all leaf nodes of MIBs, i.e. scalar objects or columnar objects. There is no deeper level of element containment. For the top two level, the XSD represents as follows: ... Li Expires December 22, 2007 [Page 6] Internet-Draft Using Smidump to Convert MIB to XSD June 2007 5.2. Deriving of the Third-level Elements There are two kinds of elements in the third level of the flattened structure. 1. The container element, which contains scalar elements and appears at most once. This kind of element is derived from an OBJECT IDENTIFIER assignment. The assignment usually appears in the following manner: OBJECT IDENTIFIER ::= { } The assignment is mapped to two portions. One is a complex type definition, which contains all scalar elements underneath the OID subtree; the other is an element declaration, which is named as and associates with the foregoing complex type. The XSD represents as follows: unknown ... unknown ... 2. The entry instance element, which contains columnar elements and can appear multiple times. This kind of element is derived from the OBJECT-TYPE macro that defines a table entry. The definition usually appears in the following manner: Li Expires December 22, 2007 [Page 7] Internet-Draft Using Smidump to Convert MIB to XSD June 2007 OBJECT-TYPE SYNTAX ... MAX-ACCESS not-accessible STATUS "current"|"deprecated"|"obsolete" DESCRIPTION "..." INDEX { , ... } ::= { 1 } Li Expires December 22, 2007 [Page 8] Internet-Draft Using Smidump to Convert MIB to XSD June 2007 The OBJECT-TYPE macro is mapped to a complex type definition and an element declaration. The macro-descriptor in OBJECT-TYPE MACRO is mapped as the name of the element. The SYNTAX clause is mapped as the 'type' attribute of the element declaration. The MAX-ACCESS and STATUS clauses are mapped as the and in the of the element declaration respectively. The OBJECT-TYPE Value is calculated and mapped as the value of the in the of the element declaration. The DESCRIPTION clause is mapped as of the element declaration. Each object in the INDEX clause is mapped as an attribute declaration of the complex type. The XSD represents as follows: Li Expires December 22, 2007 [Page 9] Internet-Draft Using Smidump to Convert MIB to XSD June 2007 not-accessible ... ... ... ... ... ... ... ... ... If the table entry can be created, a element will be present in the of the element declaration. 5.3. Mapping of the Leaf Objects Both scalar and columnar objects are defined by the OBJECT-TYPE macro, thus their mappings are the same. The definition of leaf object usually appears in the following manner: Li Expires December 22, 2007 [Page 10] Internet-Draft Using Smidump to Convert MIB to XSD June 2007 OBJECT-TYPE SYNTAX ... [UNITS ...] MAX-ACCESS "not-accessible"|"read-only" |"read-write"|"read-create" STATUS "current"|"deprecated"|"obsolete" DESCRIPTION "..." [REFERENCE "..."] [DEFVAL ...] ::= { } Where the UNITS, REFERENCE and DEFVAL clauses are optional. Each OBJECT-TYPE macro is mapped to an element declaration. The macro-descriptor in OBJECT-TYPE macro is mapped as the element name. The SYNTAX clause is mapped as the 'type' attribute of the element declaration or an anonymous simple type definition. The REFERENCE clause is discarded. Other clauses are mapped as elements in the of the element declaration. The mapping relationship between clauses and elements is illustrated as the following table: Clause Element ========================================= MAX-ACCESS UNITS STATUS DESCRIPTION DEFVAL The XSD represents as follows: ... ... ... ... ... Li Expires December 22, 2007 [Page 11] Internet-Draft Using Smidump to Convert MIB to XSD June 2007 6. Mapping of the Datatypes Smidump provides an XSD file named smi.xsd, which selects some primitive types from SMI and maps them to the XSD bulid-in datatypes or its derived datatypes. Other types, even the types defined in the SMIv2, are derived from these primitive types, such as Counter32, TimeTicks. The mapping is showed as bellow. See the XML schema in Appendix A for more detail. SMI primitive type XSD Datatype =============================================================== Integer32 int OctetString hexBinary (with restriction of length) ObjectIdentifier string (with restriction of length and pattern) Unsigned32 unsignedInt Unsigned64 unsignedLong There are many textual conventions in MIBs. A textual convention is a sub-type of a base type with restriction on size, range or enumerations, furthermore, it conveys a more precise semantics. It is used by the SYNTAX clause of the OBJECT-TYPE macro, in the same way as a base type is used. The TEXTUAL-CONVENTION macro is used to define a textual convention. The usage is showed as below: ::= TEXTUAL-CONVENTION [DISPLAY-HINT "..."] STATUS "current"|"deprecated"|"obsolete" DESCRIPTION "..." [REFERENCE "..."] SYNTAX [] Where the DISPLAY-HINT and REFERENCE clauses are optional. A textual convention is mapped as a simple type definition with corresponding base type and restriction. The STATUS and REFERENCE clauses are discarded. The descriptor in TEXTUAL-CONVENTION macro is mapped as the simple type name. The DESCRIPTION clause is mapped as the ; the DISPLAY-HINT clause is mapped as the ; the SYNTAX clause is mapped as the . The mapping is showed as bellow: Li Expires December 22, 2007 [Page 12] Internet-Draft Using Smidump to Convert MIB to XSD June 2007 ... ... ... Besides the TEXTUAL-CONVENTION macro can define a refinement of a base type, the SYNTAX clause of the OBJECT-TYPE macro can define a local refinement of a base type also. In this case, the refinement is mapped as an anonymous simple type definition, and the element declaration does not use the 'type' attribute to indicate the datatype of the element. Smidump usually maps SMI base type and its refinement to corresponding XSD datatypes and restrictions. But there is a few exceptions: Enumerated INTEGER: Smidump maps an enumerated INTEGER as a NMTOKEN datatype with restriction on enumeration. The label for the number becomes the enumerated value. The number is mapped as the value of the element, which is contained in the for the enumerated value. The XSD represents as follows: 1 2 ... Li Expires December 22, 2007 [Page 13] Internet-Draft Using Smidump to Convert MIB to XSD June 2007 The BITS construct: Smidump maps a BITS construct as a list with restriction on maximum length, the maximum length of the list is determined by the number of bit. Each list item is an enumerated NMTOKEN. The XSD represents as follows: 0 ... n-1 7. Security Considerations TBD. 8. IANA Considerations TBD. 9. Acknowledgements This document is based on the libsmi implementation and the corresponding papers. Therefore the author would like to acknowledge Li Expires December 22, 2007 [Page 14] Internet-Draft Using Smidump to Convert MIB to XSD June 2007 the developers of the libsmi toolkit. In particular, Thanks to Frank Strauss, Torsten Klie and Juergen Schoenwaelder. 10. References 10.1. Normative References [RFC2119] Bradner, s., "Key words for RFCs to Indicate Requirements Levels", RFC 2119, March 1997. [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, December 2006. [ref.XMLSchema] World Wide Web Consortium, "XML Schema Part 2: Datatypes Second Edition", W3C XML Schema, October 2004, . 10.2. Informative References [ACC-MIB] Li, Y. and D. Harrington, "Accessing MIBs using NETCONF", ID draft-li-ngo-access-mib-00, January 2007. [ref.libsmi] Strauss, F. and T. Klie, "Integrating SNMP Agents with XML-based Management Systems", July 2004, . Li Expires December 22, 2007 [Page 15] Internet-Draft Using Smidump to Convert MIB to XSD June 2007 Appendix A. The Smi.xsd File Li Expires December 22, 2007 [Page 16] Internet-Draft Using Smidump to Convert MIB to XSD June 2007 Author's Address Yan Li Huawei Technologies No.3 Xinxi Road, Shangdi Information Industry Base Beijing, HaiDian District 100085 P.R.China Phone: +86 10 8288 2008 EMail: liyan_77@huawei.com Li Expires December 22, 2007 [Page 17] Internet-Draft Using Smidump to Convert MIB to XSD June 2007 Full Copyright Statement Copyright (C) The IETF Trust (2007). 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, THE IETF TRUST 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 provided by the IETF Administrative Support Activity (IASA). Li Expires December 22, 2007 [Page 18]