RFC 4560
Definitions of Managed Objects for Remote Ping, Traceroute, and Lookup Operations
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 -- RFC3411 InetAddressType, InetAddress FROM INET-ADDRESS-MIB; -- RFC4001 lookupMIB MODULE-IDENTITY LAST-UPDATED "200606130000Z" -- 13 June 2006 ORGANIZATION "IETF Distributed Management Working Group" CONTACT-INFO "Juergen Quittek
NEC Europe Ltd.
Network Laboratories
Kurfuersten-Anlage 36
69115 Heidelberg
Germany
Phone: +49 6221 4342-115
Email: quittek@netlab.nec.de"
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.
Copyright (C) The Internet Society (2006). This version of
this MIB module is part of RFC 4560; see the RFC itself for
full legal notices."
-- Revision history
REVISION "200606130000Z" -- 13 June 2006
DESCRIPTION
"Updated version, published as RFC 4560.
- Replaced references to RFC 2575 by RFC 3415
- Replaced references to RFC 2571 by RFC 3411
- Replaced references to RFC 2851 by RFC 4001
- Added value enabled(1) to SYNTAX clause of
lookupCtlOperStatus
- Added lookupMinimumCompliance
- Defined semantics of value 0 for object
lookupPurgeTime
- Added DEFVAL { unknown } to object
lookupCtlTargetAddressType OBJECT-TYPE"
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.
The limit applies only to new requests being activated.
When a new value is set, the agent will continue processing
all the requests already active, even if their number
exceed the limit just imposed."
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 a
lookupCtlEntry has been completed.
A lookupCtEntry is considered complete
when its lookupCtlOperStatus object has a
value of completed(3).
A value of 0 indicates that automatic deletion
of entries is disabled."
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
for a symbolic host name or for a host address
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 a type of SnmpAdminString,
a textual convention that allows for the use of the SNMPv3
View-Based Access Control Model (RFC 3415, VACM)
and that also allows a 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."
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 create or
modify entries independently, 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 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 performing a
lookup operation for a symbolic host name or for a host
address from a remote host.
Specification of dns(16) as the value for this object
means that a function such as, for example, getaddrinfo()
or gethostbyname() should be performed to return one or
more numeric addresses. Use of a value of either ipv4(1)
or ipv6(2) means that a functions such as, for example,
getnameinfo() or gethostbyaddr() should be used to return
the symbolic names associated with a host."
DEFVAL { unknown }
::= { 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 lookupCtlTargetAddressType
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 {
enabled(1), -- operation is active
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 been 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 is completed (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 return the error codes that are
generated by the lookup function used."
::= { 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 the acceptance of a transition to active(1) state.
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, is completed
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 (returned by lookup function),
or it can have more than one symbolic name (returned
by lookup function).
A function such as, for example, getnameinfo() or
gethostbyaddr() 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. If the function identifies an 'official host
name,' then this symbolic name MUST be assigned a
lookupResultsIndex of 1.
A function such as, for example, getaddrinfo() or
gethostbyname() is called with a symbolic host name and is
used primarily to retrieve a host address. The entries
MUST be stored in the order that they are retrieved from
the lookup function. lookupResultsIndex 1 MUST be
assigned to the first entry."
::= { 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
consecutively."
::= { 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 either that
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.
The address type (InetAddressType) that relates to
this object is specified by the corresponding value
of lookupResultsAddress."
::= { 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 SNMP entities that
fully implement 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 }
lookupMinimumCompliance MODULE-COMPLIANCE
STATUS current
DESCRIPTION
"The minimum compliance statement for SNMP entities
that implement the minimal subset of the
DISMAN-NSLOOKUP-MIB. Implementors might choose this
subset for small devices with limited resources."
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."
OBJECT lookupCtlRowStatus
MIN-ACCESS read-only
DESCRIPTION
"Write access is not required. If write access is
not supported, then at least one entry in the
lookupCtlTable MUST be established already when the SNMP
agent starts offering access to the NSLOOKUP-MIB module.
If, in such a case, only a single entry is offered, then
it is RECOMMENDED that this entry use strings with a
length of 0 for both of its two index objects."
::= { lookupCompliances 2 }
-- MIB groupings
lookupGroup OBJECT-GROUP
OBJECTS {
lookupMaxConcurrentRequests,
lookupPurgeTime,
lookupCtlOperStatus,
lookupCtlTargetAddressType,
lookupCtlTargetAddress,
lookupCtlTime,
lookupCtlRc,
lookupCtlRowStatus,
lookupResultsAddressType,
lookupResultsAddress
}
STATUS current
DESCRIPTION
"The group of objects that constitute the remote
Lookup operation."
::= { lookupGroups 1 }
END
5. Security Considerations
There are a number of management objects defined in the three MIB
modules with a MAX-ACCESS clause of read-write and/or read-create.
Such objects may be considered sensitive or vulnerable in some
network environments. The support for SET operations in a non-secure
environment without proper protection can have a negative effect on
network operations. These are the tables and objects and their
sensitivity/vulnerability:
o pingMaxConcurrentRequests
o traceRouteMaxConcurrentRequests
o lookupMaxConcurrentRequests
The MIB modules limit their maximum numbers of concurrent requests
by the values of these objects. Unauthorized access to them may
lead to an overload of the managed node and to a disruption of
other functions of the managed node.
o pingCtlTable
o traceRouteCtlTable
o lookupCtlTable
All objects in entries of these tables (except index objects) have
a MAX-ACCESS clause of read-create. Unauthorized access to these
objects can disturb the measurements controlled by the tables.
Also, the functions offered by the MIB modules can be misused for
illegal data retrieval and for attacking other systems by floods
of ping probes, traceroute probes or lookup requests,
respectively.
In general, all three, the ping, traceroute, and lookup functions,
when used excessively are considered a form of system attack. In the
case of ping, sending a system request too often can negatively
effect its performance and 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. The same applies to excessive use of the lookup
service, particularly if the lookup cannot be resolved locally. In
insecure environments, it is RECOMMENDED that the MIBs defined within
this memo not be supported.
o lookupPurgeTime
Unauthorized access to this object can lead to the deletion of
results of lookup operations before they are read by a management
system, if the object is set to 0 or small values close to 0. If
the object is set to very high values, unauthorized access can
lead to a high consumption of resources for storing lookup
results.
Some of the readable objects in this MIB module (i.e., objects with a
MAX-ACCESS other than not-accessible) may be considered sensitive or
vulnerable in some network environments. It is thus important to
control even GET and/or NOTIFY access to these objects and possibly
to even encrypt the values of these objects when sending them over
the network via SNMP. However, the only information that can be
disclosed without encryption is the configuration and results of
measurements that are performed by implementations of the MIB
modules.
To facilitate the provisioning of access control by a security
administrator using the View-Based Access Control Model (VACM),
defined in RFC 3415 [RFC3415], for tables in which multiple users may
need to create or modify entries independently, 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 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.
SNMP versions prior to SNMPv3 did not include adequate security.
Even if the network itself is secure (for example by using IPSec),
even then, there is no control as to who on the secure network is
allowed to access and GET/SET (read/change/create/delete) the objects in this MIB module. It is RECOMMENDED that implementers consider the security features as provided by the SNMPv3 framework (see [RFC3410], section 8), including full support for the SNMPv3 cryptographic mechanisms (for authentication and privacy). Further, deployment of SNMP versions prior to SNMPv3 is NOT RECOMMENDED. Instead, it is RECOMMENDED to deploy SNMPv3 and to enable cryptographic security. It is then a customer/operator responsibility to ensure that the SNMP entity giving access to an instance of this MIB module is properly configured to give access to the objects only to those principals (users) that have legitimate rights to indeed GET or SET (change/create/delete) them.6. Acknowledgements
This document is a product of the DISMAN Working Group. Thanks to Eduardo Cardona for suggesting the minimum compliance statements and to Juergen Schoenwaelder for the very detailed and constructive MIB review.7. References
7.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2578] 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. [RFC2579] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M., and S. Waldbusser, "Textual Conventions for SMIv2", STD 58, RFC 2579, April 1999. [RFC2580] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M., and S. Waldbusser, "Conformance Statements for SMIv2", STD 58, RFC 2580, April 1999. [RFC2863] McCloghrie, K. and F. Kastenholz, "The Interfaces Group MIB", RFC 2863, June 2000.
[RFC3411] Harrington, D., Presuhn, R., and B. Wijnen, "An Architecture for Describing Simple Network Management Protocol (SNMP) Management Frameworks", STD 62, RFC 3411, December 2002. [RFC4001] Daniele, M., Haberman, B., Routhier, S., and J. Schoenwaelder, "Textual Conventions for Internet Network Addresses", RFC 4001, February 2005.7.2. Informative References
[RFC792] Postel, J., "Internet Control Message Protocol", STD 5, RFC 792, September 1981. [RFC862] Postel, J., "Echo Protocol", STD 20, RFC 862, May 1983. [RFC1812] Baker, F., "Requirements for IP Version 4 Routers", RFC 1812, June 1995. [RFC2474] 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. [RFC3260] Grossman, D., "New Terminology and Clarifications for Diffserv", RFC 3260, April 2002. [RFC3410] Case, J., Mundy, R., Partain, D. and B. Stewart, "Introduction and Applicability Statements for Internet- Standard Management Framework", RFC 3410, December 2002. [RFC3415] Wijnen, B., Presuhn, R., and K. McCloghrie, "View-based Access Control Model (VACM) for the Simple Network Management Protocol (SNMP)", STD 62, RFC 3415, December 2002.
Authors' Addresses
Juergen Quittek NEC Europe Ltd. Network Laboratories Kurfuersten-Anlage 36 69115 Heidelberg Germany Phone: +49 6221 4342-115 EMail: quittek@netlab.nec.de 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
Full Copyright Statement Copyright (C) The Internet Society (2006). 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 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).