4.3  DISMAN-NSLOOKUP-MIB

DISMAN-NSLOOKUP-MIB DEFINITIONS ::= BEGIN

IMPORTS
    MODULE-IDENTITY, OBJECT-TYPE,
    Unsigned32, mib-2, Integer32
        FROM SNMPv2-SMI                  -- RFC2578
    RowStatus
        FROM SNMPv2-TC                   -- RFC2579
    MODULE-COMPLIANCE, OBJECT-GROUP
        FROM SNMPv2-CONF                 -- RFC2580
    SnmpAdminString
        FROM SNMP-FRAMEWORK-MIB          -- RFC2571

    InetAddressType, InetAddress
        FROM INET-ADDRESS-MIB;           -- RFC2851


 lookupMIB MODULE-IDENTITY
    LAST-UPDATED "200009210000Z"         -- 21 September 2000
    ORGANIZATION "IETF Distributed Management Working Group"
    CONTACT-INFO
        "Kenneth White

        International Business Machines Corporation
        Network Computing Software Division
        Research Triangle Park, NC, USA

        E-mail: wkenneth@us.ibm.com"
    DESCRIPTION
        "The Lookup MIB (DISMAN-NSLOOKUP-MIB) enables determination
        of either the name(s) corresponding to a host address or of
        the address(es) associated with a host name at a remote host."

     --  Revision history

     REVISION     "200009210000Z"         -- 21 September 2000
     DESCRIPTION
         "Initial version, published as RFC 2925."

    ::= { mib-2 82 }

 -- Top level structure of the MIB

 lookupObjects        OBJECT IDENTIFIER ::= { lookupMIB 1 }
 lookupConformance    OBJECT IDENTIFIER ::= { lookupMIB 2 }

 -- Simple Object Definitions

 lookupMaxConcurrentRequests OBJECT-TYPE
    SYNTAX      Unsigned32
    UNITS       "requests"
    MAX-ACCESS  read-write
    STATUS      current
    DESCRIPTION
       "The maximum number of concurrent active lookup requests
       that are allowed within an agent implementation.  A value
       of 0 for this object implies that there is no limit for
       the number of concurrent active requests in effect."
    DEFVAL { 10 }
    ::= { lookupObjects 1 }

 lookupPurgeTime OBJECT-TYPE
    SYNTAX      Unsigned32 (0..86400)
    UNITS       "seconds"
    MAX-ACCESS  read-write
    STATUS      current
    DESCRIPTION
       "The amount of time to wait before automatically
       deleting an entry in the lookupCtlTable and any
       dependent lookupResultsTable entries
       after the lookup operation represented by an
       lookupCtlEntry has completed.

       An lookupCtEntry is considered complete
       when its lookupCtlOperStatus object has a
       value of completed(3)."
    DEFVAL { 900 }  -- 15 minutes as default
    ::= { lookupObjects 2 }

 -- Lookup Control Table

 lookupCtlTable OBJECT-TYPE
    SYNTAX      SEQUENCE OF LookupCtlEntry
    MAX-ACCESS  not-accessible
    STATUS      current
    DESCRIPTION
        "Defines the Lookup Control Table for providing
        the capability of performing a lookup operation,
        gethostbyname or gethostbyaddr, from a remote host."
   ::= { lookupObjects 3 }

 lookupCtlEntry OBJECT-TYPE
    SYNTAX      LookupCtlEntry
    MAX-ACCESS  not-accessible
    STATUS      current
    DESCRIPTION
        "Defines an entry in the lookupCtlTable.  A
        lookupCtlEntry is initially indexed by
        lookupCtlOwnerIndex, which is of type SnmpAdminString,
        a textual convention that allows for use of the SNMPv3
        View-Based Access Control Model (RFC 2575 [11], VACM)
        and also allows an management application to identify
        its entries.  The second index element,
        lookupCtlOperationName, enables the same
        lookupCtlOwnerIndex entity to have multiple outstanding
        requests.

        The value of lookupCtlTargetAddressType determines which
        lookup function to perform.  Specification of dns(16)

        as the value of this index implies that the gethostbyname
        function should be performed to determine the numeric
        addresses associated with a symbolic name via
        lookupResultsTable entries.  Use of a value of either
        ipv4(1) or ipv6(2) implies that the gethostbyaddr function
        should be performed to determine the symbolic name(s)
        associated with a numeric address at a remote host."
    INDEX {
             lookupCtlOwnerIndex,
             lookupCtlOperationName
          }
    ::= { lookupCtlTable 1 }

 LookupCtlEntry ::=
    SEQUENCE {
        lookupCtlOwnerIndex         SnmpAdminString,
        lookupCtlOperationName      SnmpAdminString,
        lookupCtlTargetAddressType  InetAddressType,
        lookupCtlTargetAddress      InetAddress,
        lookupCtlOperStatus         INTEGER,
        lookupCtlTime               Unsigned32,
        lookupCtlRc                 Integer32,
        lookupCtlRowStatus          RowStatus
    }

 lookupCtlOwnerIndex OBJECT-TYPE
    SYNTAX      SnmpAdminString (SIZE(0..32))
    MAX-ACCESS  not-accessible
    STATUS      current
    DESCRIPTION
       "To facilitate the provisioning of access control by a
       security administrator using the View-Based Access
       Control Model (RFC 2575, VACM) for tables in which
       multiple users may need to independently create or
       modify entries, the initial index is used as an 'owner
       index'.  Such an initial index has a syntax of
       SnmpAdminString, and can thus be trivially mapped to a
       securityName or groupName as defined in VACM, in
       accordance with a security policy.

       When used in conjunction with such a security policy all
       entries in the table belonging to a particular user (or
       group) will have the same value for this initial index.
       For a given user's entries in a particular table, the
       object identifiers for the information in these entries
       will have the same subidentifiers (except for the
       'column' subidentifier) up to the end of the encoded
       owner index. To configure VACM to permit access to this

       portion of the table, one would create
       vacmViewTreeFamilyTable entries with the value of
       vacmViewTreeFamilySubtree including the owner index
       portion, and vacmViewTreeFamilyMask 'wildcarding' the
       column subidentifier.  More elaborate configurations
       are possible."
    ::= { lookupCtlEntry 1 }

 lookupCtlOperationName OBJECT-TYPE
    SYNTAX      SnmpAdminString (SIZE(0..32))
    MAX-ACCESS  not-accessible
    STATUS      current
    DESCRIPTION
        "The name of a lookup operation.  This is locally unique,
        within the scope of an lookupCtlOwnerIndex."
    ::= { lookupCtlEntry 2 }

 lookupCtlTargetAddressType OBJECT-TYPE
    SYNTAX      InetAddressType
    MAX-ACCESS  read-create
    STATUS      current
    DESCRIPTION
        "Specifies the type of address for either performing a
        gethostbyname or a gethostbyaddr function at a remote host.
        Specification of dns(16) as the value for this object
        means that the gethostbyname function should be performed
        to return one or more numeric addresses.  Use of a value
        of either ipv4(1) or ipv6(2) means that the gethostbyaddr
        function should be used to return the symbolic names
        associated with a remote host."
    ::= { lookupCtlEntry 3 }

 lookupCtlTargetAddress OBJECT-TYPE
    SYNTAX      InetAddress
    MAX-ACCESS  read-create
    STATUS      current
    DESCRIPTION
        "Specifies the address used for a resolver lookup at a
        remote host.  The corresponding lookupCtlAddressType
        objects determines its type as well as the function
        that can be requested.

        A value for this object MUST be set prior to
        transitioning its corresponding lookupCtlEntry to
        active(1) via lookupCtlRowStatus."
    ::= { lookupCtlEntry 4 }

 lookupCtlOperStatus OBJECT-TYPE

    SYNTAX      INTEGER {
                   notStarted(2), -- operation has not started
                   completed(3)   -- operation is done
                }
    MAX-ACCESS  read-only
    STATUS      current
    DESCRIPTION
        "Reflects the operational state of an lookupCtlEntry:

           enabled(1)    - Operation is active.
           notStarted(2) - Operation has not been enabled.
           completed(3)  - Operation has completed.

         An operation is automatically enabled(1) when its
         lookupCtlRowStatus object is transitioned to active(1)
         status.  Until this occurs lookupCtlOperStatus MUST
         report a value of notStarted(2).  After the lookup
         operation completes (success or failure) the value
         for lookupCtlOperStatus MUST be transitioned to
         completed(3)."
    ::= { lookupCtlEntry 5 }

 lookupCtlTime OBJECT-TYPE
    SYNTAX      Unsigned32
    UNITS       "milliseconds"
    MAX-ACCESS  read-only
    STATUS      current
    DESCRIPTION
        "Reports the number of milliseconds that a lookup
        operation required to be completed at a remote host.
        Completed means operation failure as well as
        success."
    ::= { lookupCtlEntry 6 }

 lookupCtlRc OBJECT-TYPE
    SYNTAX      Integer32
    MAX-ACCESS  read-only
    STATUS      current
    DESCRIPTION
        "The system specific return code from a lookup
        operation.  All implementations MUST return a value
        of 0 for this object when the remote lookup
        operation succeeds.  A non-zero value for this
        objects indicates failure.  It is recommended that
        implementations that support errno use it as the
        value of this object to aid a management
        application in determining the cause of failure."
    ::= { lookupCtlEntry 7 }

 lookupCtlRowStatus OBJECT-TYPE
    SYNTAX      RowStatus
    MAX-ACCESS  read-create
    STATUS      current
    DESCRIPTION
        "This object allows entries to be created and deleted
        in the lookupCtlTable.

        A remote lookup operation is started when an
        entry in this table is created via an SNMP SET
        request and the entry is activated.  This
        occurs by setting the value of this object
        to CreateAndGo(4) during row creation or
        by setting this object to active(1) after
        the row is created.

        A value MUST be specified for lookupCtlTargetAddress
        prior to a transition to active(1) state being
        accepted.

        A remote lookup operation starts when its entry
        first becomes active(1).  Transitions in and
        out of active(1) state have no effect on the
        operational behavior of a remote lookup
        operation, with the exception that deletion of
        an entry in this table by setting its RowStatus
        object to destroy(6) will stop an active
        remote lookup operation.

        The operational state of a remote lookup operation
        can be determined by examination of its
        lookupCtlOperStatus object."
    REFERENCE
        "See definition of RowStatus in RFC 2579,
        'Textual Conventions for SMIv2.'"
    ::= { lookupCtlEntry 8 }


-- Lookup Results Table

 lookupResultsTable OBJECT-TYPE
    SYNTAX      SEQUENCE OF LookupResultsEntry
    MAX-ACCESS  not-accessible
    STATUS      current
    DESCRIPTION
        "Defines the Lookup Results Table for providing
        the capability of determining the results of a
        operation at a remote host.

        One or more entries are added to the
        lookupResultsTable when a lookup operation,
        as reflected by an lookupCtlEntry, completes
        successfully.  All entries related to a
        successful lookup operation MUST be added
        to the lookupResultsTable at the same time
        that the associating lookupCtlOperStatus
        object is transitioned to completed(2).

        The number of entries added depends on the
        results determined for a particular lookup
        operation.  All entries associated with an
        lookupCtlEntry are removed when the
        lookupCtlEntry is deleted.

        A remote host can be multi-homed and have more
        than one IP address associated with it
        (gethostbyname results) and/or it can have more
        than one symbolic name (gethostbyaddr results).

        The gethostbyaddr function is called with a
        host address as its parameter and is used
        primarily to determine a symbolic name to
        associate with the host address.  Entries in
        the lookupResultsTable MUST be made for each
        host name returned.  The official host name MUST
        be assigned a lookupResultsIndex of 1.

        The gethostbyname function is called with a
        symbolic host name and is used primarily to
        retrieve a host address.  If possible the
        primary host address SHOULD be assigned a
        lookupResultsIndex of 1."
   ::= { lookupObjects 4 }

 lookupResultsEntry OBJECT-TYPE
    SYNTAX      LookupResultsEntry
    MAX-ACCESS  not-accessible
    STATUS      current
    DESCRIPTION
        "Defines an entry in the lookupResultsTable.  The
        first two index elements identify the
        lookupCtlEntry that a lookupResultsEntry belongs
        to.  The third index element selects a single
        lookup operation result."
    INDEX {
             lookupCtlOwnerIndex,
             lookupCtlOperationName,

             lookupResultsIndex
          }
    ::= { lookupResultsTable 1 }

 LookupResultsEntry ::=
    SEQUENCE {
        lookupResultsIndex        Unsigned32,
        lookupResultsAddressType  InetAddressType,
        lookupResultsAddress      InetAddress
     }

 lookupResultsIndex OBJECT-TYPE
    SYNTAX      Unsigned32 (1..'ffffffff'h)
    MAX-ACCESS  not-accessible
    STATUS      current
    DESCRIPTION
        "Entries in the lookupResultsTable are created when
        the result of a lookup operation is determined.

        Entries MUST be stored in the lookupResultsTable in
        the order that they are retrieved.  Values assigned
        to lookupResultsIndex MUST start at 1 and increase
        in order."
    ::= { lookupResultsEntry 1 }

 lookupResultsAddressType OBJECT-TYPE
    SYNTAX      InetAddressType
    MAX-ACCESS  read-only
    STATUS      current
    DESCRIPTION
        "Indicates the type of result of a remote lookup
        operation.  A value of unknown(0) implies that
        either the operation hasn't been started or that
        it has failed."
    ::= { lookupResultsEntry 2 }

 lookupResultsAddress OBJECT-TYPE
    SYNTAX      InetAddress
    MAX-ACCESS  read-only
    STATUS      current
    DESCRIPTION
        "Reflects a result for a remote lookup operation
        as per the value of lookupResultsAddressType."
    ::= { lookupResultsEntry 3 }


 -- Conformance information
 -- Compliance statements

 lookupCompliances OBJECT IDENTIFIER ::= { lookupConformance 1 }
 lookupGroups      OBJECT IDENTIFIER ::= { lookupConformance 2 }

 -- Compliance statements

 lookupCompliance MODULE-COMPLIANCE
    STATUS  current
    DESCRIPTION
            "The compliance statement for the DISMAN-NSLOOKUP-MIB."
    MODULE  -- this module
        MANDATORY-GROUPS {
                            lookupGroup
                          }

        OBJECT lookupMaxConcurrentRequests
        MIN-ACCESS  read-only
        DESCRIPTION
            "The agent is not required to support SET
            operations to this object."

        OBJECT lookupPurgeTime
        MIN-ACCESS  read-only
        DESCRIPTION
            "The agent is not required to support a SET
            operation to this object."
    ::= { lookupCompliances 1 }

 -- MIB groupings

 lookupGroup OBJECT-GROUP
   OBJECTS {
             lookupMaxConcurrentRequests,
             lookupPurgeTime,
             lookupCtlOperStatus,
             lookupCtlTargetAddressType,
             lookupCtlTargetAddress,
             lookupCtlTime,
             lookupCtlRc,
             lookupCtlRowStatus,
             lookupResultsAddressType,
             lookupResultsAddress
           }
   STATUS  current
   DESCRIPTION
       "The group of objects that comprise the remote
       Lookup operation."
    ::= { lookupGroups 1 }

END

5.0  Security Considerations

   Certain management information in the MIBs defined by this document
   may be considered sensitive in some network environments.  Therefore,
   authentication of received SNMP requests and controlled access to
   management information SHOULD be employed in such environments.  The
   method for this authentication is a function of the SNMP
   Administrative Framework, and has not been expanded by this MIB.

   To facilitate the provisioning of access control by a security
   administrator using the View-Based Access Control Model (VACM)
   defined in RFC 2575 [11] for tables in which multiple users may need
   to independently create or modify entries, the initial index is used
   as an "owner index".  Such an initial index has a syntax of
   SnmpAdminString, and can thus be trivially mapped to a securityName
   or groupName as defined in VACM, in accordance with a security
   policy.

   All entries in related tables belonging to a particular user will
   have the same value for this initial index.  For a given user's
   entries in a particular table, the object identifiers for the
   information in these entries will have the same subidentifiers
   (except for the "column" subidentifier) up to the end of the encoded
   owner index. To configure VACM to permit access to this portion of
   the table, one would create vacmViewTreeFamilyTable entries with the
   value of vacmViewTreeFamilySubtree including the owner index portion,
   and vacmViewTreeFamilyMask "wildcarding" the column subidentifier.
   More elaborate configurations are possible.  The VACM access control
   mechanism described above provides control.

   In general, both the ping and traceroute functions when used
   excessively are considered a form of system attack.  In the case of
   ping sending a system requests too often can negatively effect its
   performance or attempting to connect to what is supposed to be an
   unused port can be very unpredictable.  Excessive use of the

   traceroute capability can like ping negatively affect system
   performance.  In insecure environments it is RECOMMENDED that the
   MIBs defined within this memo not be supported.

6.0  Intellectual Property

   The IETF takes no position regarding the validity or scope of any
   intellectual property 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; neither does it represent that it
   has made any effort to identify any such rights.  Information on the
   IETF's procedures with respect to rights in standards-track and
   standards-related documentation can be found in BCP-11.  Copies of
   claims of rights made available for publication 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 Secretariat.

   The IETF invites any interested party to bring to its attention any
   copyrights, patents or patent applications, or other proprietary
   rights which may cover technology that may be required to practice
   this standard.  Please address the information to the IETF Executive
   Director.

7.0  Acknowledgments

   This document is a product of the DISMAN Working Group.

8.0  References

   [1]  Case, J., Fedor, M., Schoffstall, M. and J. Davin, "Simple
        Network Management Protocol", STD 15, RFC 1157, May 1990.

   [2]  Postel, J., "Echo Protocol", STD 20, RFC 862, May 1983.

   [3]  McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose,
        M. and S. Waldbusser, "Structure of Management Information
        Version 2 (SMIv2)", STD 58, RFC 2578, April 1999.

   [4]  McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose,
        M. and S. Waldbusser, "Textual Conventions for SMIv2", STD 58,
        RFC 2579, April 1999.

   [5]  McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose,
        M. and S. Waldbusser, "Conformance Statements for SMIv2", STD
        58, RFC 2580, April 1999.

   [6]  Case, J., McCloghrie, K., Rose, M. and S. Waldbusser, "Protocol
        Operations for Version 2 of the Simple Network Management
        Protocol (SNMPv2)", RFC 1905, January 1996.

   [7]  Harrington D., Presuhn, R. and B. Wijnen, "An Architecture for
        Describing SNMP Management Frameworks", RFC 2571, April 1999.

   [8]  Case, J., Harrington D., Presuhn, R. and B. Wijnen, "Message
        Processing and Dispatching for the Simple Network Management
        Protocol (SNMP)", RFC 2572, April 1999.

   [9]  Levi D., Meyer, P. and B. Stewart, "SNMPv3 Applications", RFC
        2573, April 1999.

   [10] Blumenthal, U. and B. Wijnen, "User-based Security Model (USM)
        for version 3 of the Simple Network Management Protocol
        (SNMPv3)", RFC 2574, April 1999.

   [11] Wijnen, B., Presuhn, R. and K. McCloghrie, "View-based Access
        Control Model (VACM) for the Simple Network Management Protocol
        (SNMP)", RFC 2575, April 1999.

   [12] Hovey, R. and S. Bradner, "The Organizations Involved in the
        IETF Standards Process", BCP 11, RFC 2028, October 1996.

   [13] Bradner, S., "Key words for use in RFCs to Indicate Requirement
        Levels", BCP 14, RFC 2119, March 1997.

   [14] Rose, M. and K. McCloghrie, "Structure and Identification of
        Management Information for TCP/IP-based Internets", RFC 1155,
        May 1990.

   [15] Rose, M. and K. McCloghrie, "Concise MIB Definitions", RFC 1212,
        March 1991.

   [16] Rose, M., "A Convention for Defining Traps for use with the
        SNMP", RFC 1215, March 1991.

   [17] Case, J., McCloghrie, K., Rose, M. and S. Waldbusser,
        "Introduction to Community-based SNMPv2", RFC 1901, January
        1996.

   [18] Case, J., McCloghrie, K., Rose, M. and S. Waldbusser, "Transport
        Mappings for Version 2 of the Simple Network Management Protocol
        (SNMPv2)", RFC 1906, January 1996.

   [19] Bradner, S., "The Internet Standards Process -- Revision 3", RFC
        2026, BCP 9, October 1996.

   [20] Postel, J., "Internet Control Message Protocol", RFC 792,
        September 1981.

   [21] Nichols, K., Blake, S., Baker, F. and D. Black, "Definition of
        the Differentiated Services Field (DS Field) in the IPv4 and
        IPv6 Headers", RFC 2474, December 1998.

   [22] Daniele, M., Haberman, B., Routhier, S. and J. Schoenwaelder,
        "Textual Conventions for Internet Network Addresses", RFC 2851,
        June 2000.

   [23] McCloghrie, K. and F. Kastenholz, "The Interfaces Group MIB",
        RFC 2863, June 2000.

9.0  Author's Address

   Kenneth D. White
   Dept. BRQA/Bldg. 501/G114
   IBM Corporation
   P.O.Box 12195
   3039 Cornwallis
   Research Triangle Park, NC 27709, USA

   EMail: wkenneth@us.ibm.com

10.  Full Copyright Statement

   Copyright (C) The Internet Society (2000).  All Rights Reserved.

   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implementation may be prepared, copied, published
   and distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph are
   included on all such copies and derivative works.  However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or other
   Internet organizations, except as needed for the purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into languages other than
   English.

   The limited permissions granted above are perpetual and will not be
   revoked by the Internet Society or its successors or assigns.

   This document and the information contained herein is provided on an
   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
   TASK FORCE DISCLAIMS 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.

Acknowledgement

   Funding for the RFC Editor function is currently provided by the
   Internet Society.