💾 Archived View for gemini.bortzmeyer.org › rfc-mirror › rfc2561.txt captured on 2022-06-04 at 03:22:51.
⬅️ Previous capture (2021-11-30)
-=-=-=-=-=-=-
Network Working Group K. White Request for Comments: 2561 IBM Corp. Category: Standards Track R. Moore IBM Corp. April 1999 Base Definitions of Managed Objects for TN3270E Using SMIv2 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 This memo defines a Management Information Base (MIB) for configuring and managing TN3270E servers. TN3270E, defined by RFC 2355 [19], refers to the enhancements made to the Telnet 3270 (TN3270) terminal emulation practices. Refer to RFC 1041 [18], STD 8, RFC 854 [16], and STD 31, RFC 860 [17] for a sample of what is meant by TN3270 practices. The MIB defined by this memo provides generic support for both host and gateway TN3270E server implementations. A TN3270E server connects a Telnet client performing 3270 emulation to a target SNA host over both a client-side network (client to TN3270E server) and an SNA Network (TN3270E server to target SNA host). The client-side network is typically TCP/IP, but it need not be. A host TN3270E server refers to an implementation where the TN3270E server is collocated with the Systems Network Architecture (SNA) System Services Control Point (SSCP) for the dependent Secondary Logical Units (SLUs) that the server makes available to its clients for connecting into a SNA network. A gateway TN3270E server resides on an SNA node other than an SSCP, either an SNA type 2.0 node, a boundary-function-attached type 2.1 node, or an APPN node acting in the role of a Dependent LU Requester (DLUR). Host and gateway TN3270E server implementations typically differ greatly as to their internal implementation and system definition (SYSDEF) methods. White & Moore Standards Track [Page 1] RFC 2561 TN3270E Using SMIv2 MIB April 1999 It is the intent that the MIB defined herein be extended by subsequent memos. For example, one such extension enables collection of TN3270E response time data. Table of Contents 1.0 Introduction . . . . . . . . . . . . . . . . . . . . . . . 2 2.0 The SNMP Network Management Framework . . . . . . . . . . 3 3.0 Structure of the MIB . . . . . . . . . . . . . . . . . . . 4 3.1 TN3270E Server Control . . . . . . . . . . . . . . . . . . 5 3.1.1 tn3270eSrvrConfTable . . . . . . . . . . . . . . . . . 5 3.1.2 tn3270eSrvrPortTable . . . . . . . . . . . . . . . . . 6 3.1.3 tn3270eSrvrStatsTable . . . . . . . . . . . . . . . . 7 3.2 TN3270E Server Resource Configuration . . . . . . . . . . 7 3.3 Resource Name / Client Address Mappings . . . . . . . . . 8 3.3.1 tn3270eSnaMapTable . . . . . . . . . . . . . . . . . . 8 3.3.2 tn3270eResMapTable . . . . . . . . . . . . . . . . . . 9 3.3.3 tn3270eTcpConnTable . . . . . . . . . . . . . . . . . 9 3.4 Advisory Spin Lock Usage . . . . . . . . . . . . . . . . . 9 3.5 Row Persistence . . . . . . . . . . . . . . . . . . . . . 10 3.6 IANA Considerations . . . . . . . . . . . . . . . . . . . 10 4.0 Definitions . . . . . . . . . . . . . . . . . . . . . . . 11 5.0 Security Considerations . . . . . . . . . . . . . . . . . 51 6.0 Intellectual Property . . . . . . . . . . . . . . . . . . 52 7.0 Acknowledgments . . . . . . . . . . . . . . . . . . . . . 53 8.0 References . . . . . . . . . . . . . . . . . . . . . . . . 53 9.0 Authors' Addresses . . . . . . . . . . . . . . . . . . . . 55 Full Copyright Statement . . . . . . . . . . . . . . . . . . . 56 1.0 Introduction This document is a product of the TN3270E Working Group. Its purpose is to define a MIB module for support by a TCP/IP implementation for configuration and management of TN3270E servers. 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, reference [22]. White & Moore Standards Track [Page 2] RFC 2561 TN3270E Using SMIv2 MIB April 1999 2.0 The SNMP Network Management Framework The SNMP Management Framework presently consists of five major components: o An overall architecture, described in RFC 2271 [1]. o Mechanisms for describing and naming objects and events for the purpose of management. The first version of this Structure of Management Information (SMI) is called SMIv1 and described in STD 16, RFC 1155 [2], STD 16, RFC 1212 [3] and RFC 1215 [4]. The second version, called SMIv2, is described in RFC 1902 [5], RFC 1903 [6] and RFC 1904 [7]. o Message protocols for transferring management information. The first version of the SNMP message protocol is called SNMPv1 and described in STD 15, RFC 1157 [8]. A second version of the SNMP message protocol, which is not an Internet standards track protocol, is called SNMPv2c and described in RFC 1901 [9] and RFC 1906 [10]. The third version of the message protocol is called SNMPv3 and described in RFC 1906 [10], RFC 2272 [11] and RFC 2274 [12]. o Protocol operations for accessing management information. The first set of protocol operations and associated PDU formats is described in STD 15, RFC 1157 [8]. A second set of protocol operations and associated PDU formats is described in RFC 1905 [13]. o A set of fundamental applications described in RFC 2273 [14] and the view-based access control mechanism described in RFC 2275 [15]. Managed objects are accessed via a virtual information store, termed the Management Information Base or MIB. Objects in the MIB are defined using the mechanisms defined in the SMI. This memo specifies a MIB module that is compliant to the SMIv2. A MIB conforming to the SMIv1 can be produced through the appropriate translations. The resulting translated MIB must be semantically equivalent, except where objects or events are omitted because no translation is possible (use of Counter64). Some machine readable information in SMIv2 will be converted into textual descriptions in SMIv1 during the translation process. However, this loss of machine readable information is not considered to change the semantics of the MIB. White & Moore Standards Track [Page 3] RFC 2561 TN3270E Using SMIv2 MIB April 1999 3.0 Structure of the MIB The TN3270E-MIB is split into the following components: o TN3270E Server Control o TN3270E Server Resource Configuration o Resource/Client Address Mappings There are three additional sections to address: o Advisory Spin Lock Usage o Row Persistence o IANA Considerations The TN3270E-MIB is defined primarily for TN3270E servers. This memo does not explicitly address use of the MIB by TN3270 servers that do not support the TN3270E protocol. Even though a significant number of the objects in the MIB do apply in the TN3270-only case, the case was not addressed, since it is unlikely that a TN3270-only server would implement this MIB. The SYSAPPL-MIB, reference [24], contains the Utf8String textual convention (TC) that the TN3270E-MIB imports. This TC, which is used for some MIB objects containing textual information, enables internationalization of text strings, whereas the DisplayString TC does not. The SNMP-FRAMEWORK-MIB, reference [1], contains the SnmpAdminString TC that the TN3270E-MIB also imports. Like the Utf8String TC, this TC also enables internationalization of text strings; in addition, it provides some guidelines on the length and content of the strings. It is important to note that implementation of the SYSAPPL-MIB is not actually a prerequisite for implementing the TN3270E-MIB. On the other hand, implementation of the TN3270E-MIB does not preclude implementing the SYSAPPL-MIB as well. When both MIBs are implemented, the primary index into most of the TN3270E-MIB tables, tn3270eSrvrConfIndex, SHOULD equal one of the SYSAPPL-MIB's sysApplElmtRunIndex values. In this case the entry in the sysApplElmtRunTable provides additional information on a TN3270E server. The MIB defined by this memo supports use of both IPv4 and IPv6 addressing. Two textual conventions, IANATn3270eAddrType and Tn3270eAddress, are defined for this purpose. IANATn3270eAddress is essentially equivalent to the TAddress TC, defined by RFC 1903. The difference between the two is that IANATn3270eAddress allows a zero- length octet string, while TAddress doesn't. It is important that IANATn3270eAddress allow for the absence of an address, because some White & Moore Standards Track [Page 4] RFC 2561 TN3270E Using SMIv2 MIB April 1999 objects with this syntax are used as table indexes, and have special meanings when they contain zero-length strings. The IANATn3270eAddrType textual convention is used rather than the TDomain TC (defined by RFC 1903) for identifying the contents of a tn3270eTAddress object. TDomain uses an OID to characterize the contents of an associated TAddress object. IANATn3270eAddrType was chosen over TDomain because, with a SYNTAX of Unsigned32 (enumeration type), it is much simpler to use as a component in an instance identifier. It was placed in the IANA-administered module to allow for the addition of values to cover cases (such as proxy servers) not covered by the TN3270E-MIB itself. 3.1 TN3270E Server Control This group of objects provides for TN3270E server configuration and control. It consists of three tables: o tn3270eSrvrConfTable o tn3270eSrvrPortTable o tn3270eSrvrStatsTable The tn3270eSrvrConfTable is the primary table within the entire TN3270E-MIB. As section 3.1.1 indicates, each TN3270E server is represented by an entry in this table, indexed by tn3270eSrvrConfIndex. Most of the other tables defined by the TN3270E-MIB have tn3270eSrvrConfIndex as their primary index. Entries in these tables MUST NOT exist for a TN3270E server when it does not have a tn3270eSrvrConfigEntry. 3.1.1 tn3270eSrvrConfTable The tn3270eSrvrConfTable contains a set of objects primarily used for configuring and managing TN3270E servers. As with most of the other tables in the TN3270E-MIB, this table is indexed by an unsigned integer, tn3270eSrvrConfIndex. This primary index element enables support of multiple TN3270E servers by a single SNMP agent. Within the set of MIB objects returned by one SNMP agent, tn3270eSrvrConfIndex values MUST be unique, and need not be contiguous. The tn3270eSrvrConfInactivityTimer object defines the inactivity period for user traffic on TN3270 and TN3270E sessions. White & Moore Standards Track [Page 5] RFC 2561 TN3270E Using SMIv2 MIB April 1999 The four objects: o tn3270eSrvrConfConnectivityChk o tn3270eSrvrConfTmNopInterval o tn3270eSrvrConfTmNopInactTime o tn3270eSrvrConfTmTimeout define the parameters for performing the "Telnet Timing Mark Option" as defined by RFC 860 [17]. The object tn3270eSrvrConfConnectivityChk allows a Management Station to select either a NOP command or a TIMING-MARK command. Sending a NOP command results in less overhead then a TIMING-MARK command, since a client doesn't send a reply. The objects tn3270eSrvrConfAdminStatus and tn3270eSrvrConfOperStatus enable remote starting and stopping of a TN3270E server, and report the current state of the server. The object tn3270eSrvrConfFunctionsSupported indicates which of the TN3270 and TN3270E options a server supports. The object tn3270eSrvrConfSessionTermState defines as a TN3270E server-wide option what SHOULD occur when the SNA portion of a TN3270 or TN3270E session terminates with respect to the associated TCP connection. The object tn3270eSrvrConfSrvrType indicates whether the TN3270E server represented by a tn3270eSrvrConfEntry is a host or a gateway server. The object tn3270eSrvrConfContact provides a scratch pad area for a TN3270E server administrator to store information for later retrieval. The object tn3270eSrvrConfLastActTime reports the DateAndTime when the server was most recently activated. The special value of all '00'Hs indicates that the server has never been active. The object tn3270eSrvrConfRowStatus provides the capability to perform row creation and deletion operations on this table. 3.1.2 tn3270eSrvrPortTable The tn3270eSrvrPortTable represents the local TCP ports associated with a TN3270E server. This information is important because some TN3270E server implementations support usage of multiple local ports. A tn3270eSrvrPortEntry is indexed by: o tn3270eSrvrConfIndex o tn3270eSrvrConfPort o tn3270eSrvrConfPortAddrType o tn3270eSrvrConfPortAddress Certain TN3270E server implementations restrict a local TCP port to a particular local IP address, instead of allowing connections for any local IP address to occur via the port. tn3270eSrvrConfPortAddrType White & Moore Standards Track [Page 6] RFC 2561 TN3270E Using SMIv2 MIB April 1999 and tn3270eSrvrConfPortAddress allow this restriction to be represented in the MIB. A TN3270E server that doesn't restrict connections over a port to a local IP Address SHALL use the value unknown(0) for tn3270eSrvrConfPortAddrType, and a zero-length octet string for tn3270eSrvrConfPortAddress. 3.1.3 tn3270eSrvrStatsTable The tn3270eSrvrStatsTable defines a series of objects that provide general usage statistics for a TN3270E server. An entry can represent the total activity for a server, or it can represent the activity occurring at the server on either a port or a port-and- local-address basis. An implementation of this table MUST use only one of the three levels of refinement that the indexing of this table supports for the entries associated with a single TN3270E server. The objects in this table reporting maximum, in-use, and spare LUs for terminals and printers presuppose an implementation where terminal resources and printer resources come from disjoint, dedicated pools. An implementation where resources for the two types of LUs come from a single shared pool should return the following values: o maximum: maximum size of the shared pool o in-use: number currently in use as this type of LU o spare: maximum - (terminal in-use + printer in-use) 3.2 TN3270E Server Resource Configuration The following three tables provide for configuration of resources at a TN3270E server: o tn3270eClientGroupTable o tn3270eResPoolTable o tn3270eClientResMapTable tn3270eClientGroupTable and tn3270eResPoolTable enable implementations to define groupings of both client addresses and resource pools for mapping client addresses to resources. The tn3270eClientResMapTable provides a mapping from a client group to a resource pool. White & Moore Standards Track [Page 7] RFC 2561 TN3270E Using SMIv2 MIB April 1999 3.3 Resource Name / Client Address Mappings The TN3270E-MIB contains three tables for mapping resource names to client addresses, and client addresses to resource names: o tn3270eSnaMapTable o tn3270eResMapTable o tn3270eTcpConnTable 3.3.1 tn3270eSnaMapTable The tn3270eSnaMapTable is a read-only table that maps a secondary LU's SNA network name to the name by which it is known locally at the TN3270E server. For correlation with data from the SNA network, the name of the associated primary LU also appears in a tn3270eSnaMapEntry. An entry in this table is created when the Activate LU (ACTLU) request carrying the SNA network name of the SLU is received from the SSCP. The entry is deleted when the SLU is deactivated. A TN3270E server provides a client with access to an SNA application by associating a TCP connection from the client with an SNA secondary LU (SLU) at the server. This SLU in turn has an SNA session with a primary LU (PLU) running on an SNA host. This PLU represents the application with which the client is communicating. The TN3270E-MIB includes two tables for mapping back and forth among the SNA name identifying the PLU, the SNA name identifying the SLU, and the TCP connection with the client. In order to understand how these name mappings work, it is necessary to understand a subtlety involving the names of the SLUs at the TN3270E server: these names are often different from the names by which the SLUs are known in the rest of the SNA network. In the TN3270E-MIB, these two types of SLU names are termed "local names" and "SSCP-supplied names"; the latter term indicates that the name by which the SLU is known in the SNA network comes to the TN3270E server from the SNA System Services Control Point. SSCPs don't always send SLU names down to secondary LUs; in some cases this capability must be turned on. In the case of SLUs served by a Dependent LU Requester (DLUR), an SSCP always sends SLU names to the DLUR. It is necessary, however, to enable the DLUR's PU/LU Network Name Forwarding function, so that it forwards the SLU names it receives from the SSCP down to the PUs that it serves. White & Moore Standards Track [Page 8] RFC 2561 TN3270E Using SMIv2 MIB April 1999 For SLUs associated with an SNA type 2.0 node (or with a boundary- function-attached type 2.1 node) not served by a DLUR, inclusion of SLU names on ACTLU must be enabled explicitly at the SSCP via local configuration. 3.3.2 tn3270eResMapTable The tn3270eResMapTable is a read-only table that maps a resource name to a client's address. An entry in this table is created when a TCP connection is received by a TN3270E server and mapped to a resource. The entry is deleted when the resource-to-address association is no longer valid. 3.3.3 tn3270eTcpConnTable The TCP Connection Table is currently defined by RFC 2012 (Refer to reference [20], TCP-MIB Definitions). It contains the following objects: o tcpConnState (INTEGER) o tcpConnLocalAddress (IpAddress) o tcpConnLocalPort (INTEGER) o tcpConnRemAddress (IpAddress) o tcpConnRemPort (INTEGER) It is indexed by: tcpConnLocalAddress, tcpConnLocalPort, tcpConnRemAddress, and tcpConnRemPort. The tn3270eTcpConnTable contains objects for keeping a list of the current set of TN3270 and TN3270E sessions at a TN3270E server. The relationship between the tcpConnTable and the Tn3270eTcpConnTable is not one-to-one, since the tn3270eTcpConnTable contains information pertaining only to TN3270(E) sessions. The tn3270eTcpConnTable has a different indexing structure from that of the tcpConnTable. Instead of using IpAddress objects, Tn3270eAddress and IANATn3270eAddrType object pairs are used to specify client addresses (both local and remote). This enables support of IPv6 addresses. In addition, the remote address pair precedes the local address pair in the index clause, in order to enable a GET-NEXT operation using only the remote address pair. 3.4 Advisory Spin Lock Usage Within the TN3270E-MIB, tn3270eConfSpinLock is defined as an advisory lock that allows cooperating TN3270E-MIB applications to coordinate their use of the tn3270eSrvrConfTable, the tn3270eSrvrPortTable, the tn3270eClientGroupTable, the tn3270eResPoolTable, and the White & Moore Standards Track [Page 9] RFC 2561 TN3270E Using SMIv2 MIB April 1999 tn3270eClientResMapTable. When creating a new entry or altering an existing entry in any of these tables, an application SHOULD make use of tn3270eConfSpinLock to serialize application changes or additions. Since this is an advisory lock, its use by management applications SHALL NOT be enforced by agents. Agents MUST, however, implement the tn3270eConfSpinLock object. 3.5 Row Persistence The following tables enable remote creation of their entries by including RowStatus objects: o tn3270eSrvrConfTable o tn3270eSrvrPortTable o tn3270eClientGroupTable o tn3270eResPoolTable o tn3270eClientResMapTable An implementation SHOULD NOT retain SNMP-created entries in these tables across reIPLs (Initial Program Loads) of the corresponding TN3270E server, since management applications need to see consistent behavior with respect to the persistence of the table entries that they create. It is expected that local, implementation-dependent configuration information will be used to define the initial and persistent configurations for TN3270E server usage. Thus it is not necessary to enable persistence of table entries by adding StorageType (refer to RFC 1903 [6]) objects to these tables. 3.6 IANA Considerations The tn3270eSrvrFunctionsSupported, tn3270eTcpConnFunctions, tn3270eTcpConnClientIdFormat, and tn3270eTcpConnLogInfo objects, as well as a number of objects identifying various address types, resource types, and device types, use textual conventions imported from the IANATn3270eTC-MIB. The purpose of defining these textual conventions in a separate MIB module is to allow additional values to be defined without having to issue a new version of this document. The Internet Assigned Numbers Authority (IANA) is responsible for the assignment of all Internet numbers, including various SNMP-related numbers; it will administer the values associated with these textual conventions. The rules for additions or changes to the IANATn3270eTC-MIB are outlined in the DESCRIPTION clause associated with its MODULE- IDENTITY statement. White & Moore Standards Track [Page 10] RFC 2561 TN3270E Using SMIv2 MIB April 1999 The current version of the IANATn3270eTC-MIB can be accessed from the IANA home page at: "http://www.iana.org/". 4.0 Definitions TN3270E-MIB DEFINITIONS ::= BEGIN IMPORTS MODULE-IDENTITY, OBJECT-TYPE, Unsigned32, TimeTicks, IpAddress, Counter32, Gauge32, Counter64 FROM SNMPv2-SMI TEXTUAL-CONVENTION, RowStatus, TestAndIncr, DateAndTime, TimeStamp FROM SNMPv2-TC MODULE-COMPLIANCE, OBJECT-GROUP FROM SNMPv2-CONF snanauMIB FROM SNA-NAU-MIB Utf8String FROM SYSAPPL-MIB SnmpAdminString FROM SNMP-FRAMEWORK-MIB IANATn3270eAddrType, IANATn3270eAddress, IANATn3270eClientType, IANATn3270Functions, IANATn3270ResourceType, IANATn3270DeviceType, IANATn3270eLogData FROM IANATn3270eTC-MIB; tn3270eMIB MODULE-IDENTITY LAST-UPDATED "9807270000Z" -- July 27, 1998 ORGANIZATION "TN3270E Working Group" CONTACT-INFO "Kenneth White (kennethw@vnet.ibm.com) IBM Corp. - Dept. BRQA/Bldg. 501/G114 P.O. Box 12195 3039 Cornwallis RTP, NC 27709-2195 USA Robert Moore (remoore@us.ibm.com) IBM Corp. - Dept. BRQA/Bldg. 501/G114 P.O. Box 12195 3039 Cornwallis RTP, NC 27709-2195 USA +1-919-254-4436" DESCRIPTION "This module defines a portion of the management White & Moore Standards Track [Page 11] RFC 2561 TN3270E Using SMIv2 MIB April 1999 information base (MIB) for managing TN3270E servers." REVISION "9807270000Z" -- July 27, 1998 DESCRIPTION "RFC nnnn (Proposed Standard)" -- RFC Editor to fill in ::= { snanauMIB 8 } -- Textual Conventions SnaResourceName ::= TEXTUAL-CONVENTION STATUS current DESCRIPTION "The textual convention for defining an SNA resource name. A fully qualified SNA resource name, consisting of a 1 to 8 character network identifier (NetId), a period ('.'), and a 1 to 8 character resource name (ResName). The NetId and ResName are constructed from the uppercase letters 'A' - 'Z' and the numerics '0' - '9', all encoded in ASCII, with the restriction that the first character of each must be a letter. Blanks are not allowed. Earlier versions of SNA permitted three additional characters in NetIds and ResNames: '#', '@', and '