CLOSE reason codes. You should not expect a response to the CLOSE
request.
A sub-agent should also be prepared to handle an incoming DPI CLOSE
packet from the agent. Again, the packet will contain a reason code
for the CLOSE request. A sub-agent need not send a response to a
CLOSE request. The agent just assumes that the sub-agent will handle
it appropriately. The close takes place, no matter what the sub-
agent does with it.
5.2.7 REGISTER REQUEST
Before a sub-agent will receive any requests for MIB variables it
must first register the variables or sub-tree it supports with the
SNMP agent. The sub-agent must specify a number of things in the
REGISTER request:
o The sub-tree to be registered. This is a null terminated
string in the selected character set. The sub-tree must have a
trailing dot (example: "1.3.6.1.2.3.4.5.").
o The requested priority for the registration, one of:
-1 Request for best available priority.
0 Request for next better available priority than highest
priority currently registered for this sub-tree.
NNN Any other positive value requests that specific priority if
available or the first worse priority that is available.
o The max timeout value in seconds. The agent is requested to
wait this long for a response to any request for an object in
this sub-tree. The agent may have an absolute maximum timeout
value which will be used if the sub-agents asks for too big a
timeout value. A value of zero can be used to indicate that
the DPI OPEN value should be used for timeout.
o A specification if the sub-agent wants to do view selection.
If it does, then the community name (from SNMPv1 packets) will
be passed in the DPI GET, GETNEXT, SET packets).
o A specification if the sub-agent wants to receive GETBULK
packets or if it just prefers that the agent converts a GETBULK
into multiple GETNEXT requests.
Once a sub-agent has sent a DPI REGISTER packet to the agent, it
should expect a DPI RESPONSE packet that informs the sub-agent about
the result of the request. The packet ID of the RESPONSE packet
should be the same as that of the REGISTER packet to which the
RESPONSE packet is the response. If the response indicates success,
then the error_index field in the RESPONSE packet contains the
priority that the agent assigned to the sub-tree registration. See
Table 19 for a list of valid DPI RESPONSE error codes that may be
expected.
5.2.8 UNREGISTER REQUEST
A sub-agent may unregister a previously registered sub-tree. The
sub-agent must specify a few things in the UNREGISTER request:
o The sub-tree to be unregistered. This is a null terminated
string in the selected character set. The sub-tree must have a
trailing dot (example: "1.3.6.1.2.3.4.5.").
o The reason for the unregister. See Table 20 for a
list of valid reason codes.
Once a sub-agent has sent a DPI UNREGISTER packet to the agent, it
should expect a DPI RESPONSE packet that informs the sub-agent about
the result of the request. The packet ID of the RESPONSE packet
should be the same as that of the REGISTER packet to which the
RESPONSE packet is the response. See Table 19 for a list of valid
DPI RESPONSE error codes that may be expected.
A sub-agent should also be prepared to handle incoming DPI UNREGISTER
packets from the agent. Again, the DPI packet will contain a reason
code for the UNREGISTER. A sub-agent need not send a response to an
UNREGISTER request. The agent just assumes that the sub-agent will
handle it appropriately. The registration is removed, no matter what
the sub-agent returns.
5.2.9 TRAP REQUEST
A sub-agent can request that the SNMP agent generates a trap for it.
The sub-agent must provide the desired values for the generic and
specific parameters of the trap. It may optionally provide a set of
one or more name/type/length/value tuples that will be included in
the trap packet. Also, it may optionally specify an Enterprise ID
(Object Identifier) for the trap to be generated. If a NULL value is
specified for the Enterprise ID, then the agent will use the sub-
agent Identifier (from the DPI OPEN packet) as the Enterprise ID to
be sent with the trap.
5.2.10 ARE_YOU_THERE REQUEST
A sub-agent can send an ARE_YOU_THERE packet to the agent. This may
be useful to do if you have a DPI "connection" over an unreliable
transport protocol (like UDP).
If the "connection" is in a healthy state, the agent responds with a
RESPONSE packet with SNMP_ERROR_DPI_noError.
If the "connection" is not in a healthy state, the agent may respond
with a RESPONSE packet with an error indication, but the agent might
not react at all, so you would timeout while waiting for a response.
5.2.11 HOW TO QUERY THE DPI PORT.
The DPI API implementations are encouraged to provide a facility that
helps DPI sub-agent programmers to dynamically find the port that the
agent is using for the TCP and/or UDP DPI port(s). A suggested name
for such a function is: query_DPI_port().
6. REFERENCES
[1] Case, J., Fedor, M., Schoffstall M., and J. Davin, "Simple
Network Management Protocol (SNMP)", STD 15, RFC1157, SNMP
Research, Performance Systems International, MIT Laboratory for
Computer Science, May 1990.
[2] Information processing systems - Open Systems Interconnection,
"Specification of Abstract Syntax Notation One (ASN.1)",
International Organization for Standardization, International
Standard 8824, December 1987.
[3] Information processing systems - Open Systems Interconnection,
"Specification of Basic Encoding Rules for Abstract Syntax
Notation One (ASN.1)", International Organization for
Standardization, International Standard 8825, December 1987.
[4] McCloghrie, K., and M. Rose, "Management Information Base for
Network Management of TCP/IP-based internets: MIB II", STD 17,
RFC1213, Hughes LAN Systems, Performance Systems International,
March 1991.
[5] Rose, M., and K. McCloghrie, "Structure and Identification of
Management Information for TCP/IP-based internets", STD 16, RFC
1155, Performance Systems International, Hughes LAN Systems, May
1990.
[6] Rose, M., "SNMP MUX Protocol and MIB", RFC1227, Performance
Systems International, RFC1227, May 1991.
[7] Carpenter G., and B. Wijnen, "SNMP-DPI, Simple Network Management
Protocol Distributed Program Interface", RFC1228, International
Business Machines, Inc., May 1991.
[8] Case, J., McCloghrie, K., Rose, M., and S. Waldbusser, "SNMPv2
RFCs (RFC1441 through RFC1452)", SNMP Research Inc, Hughes LAN
Systems, Dover Beach Consulting Inc, Carnegie Mellon University,
Trusted Information Systems, April 1993.
[9] International Business Machines, Inc., TCP/IP for VM:
Programmer's Reference, SC31-6084-0, 1990.
[10] International Business Machines, Inc., Virtual Machine System
Facilities for Programming, Release 6, SC24-5288-01, 1988.
7. SECURITY CONSIDERATIONS
Security issues are not discussed in this memo.
8. AUTHORS' ADDRESSES
Bert Wijnen
IBM International Operations
Watsonweg 2
1423 ND Uithoorn
The Netherlands
Phone: +31-2975-53316
Fax: +31-2975-62468
EMail: wijnen@vnet.ibm.com
Geoffrey C. Carpenter
IBM T.J. Watson Research Center
P.O. Box 218
Yorktown Heights, NY 10598
USA
Phone: +1-914-945-1970
EMail: gcc@watson.ibm.com
Kim Curran
Bell Northern Research Ltd.
P.O. Box 3511 Station C
Ottawa, Ontario K1Y 4HY
Canada
Phone: +1-613-763-5283
EMail: kcurran@bnr.ca
Aditya Sehgal
Bell Northern Research Ltd.
P. O. Box 3511 Station C
Ottawa, Ontario K1Y 4HY
Canada
Phone: +1-613-763-8821
EMail: asehgal@bnr.ca
Glen Waters
Bell Northern Research Ltd.
P.O. Box 3511 Station C
Ottawa, Ontario K1Y 4HY
Canada
Phone: +1-613-763-3933
EMail: gwaters@bnr.ca
9. SAMPLE SOURCES FOR ANONYMOUS FTP
An implementation sample of a DPI API (as used at the agent and sub-
agent side) plus sample sub-agent code and documentation are
available for anonymous FTP from:
software.watson.ibm.com (129.34.139.5)
To obtain the source, perform the following steps:
ftp software.watson.ibm.com
user: anonymous
password: your_e-mail_address
cd /public/dpi
get README
binary
get dpi_api.tar (or compressed dpi_api.tar.Z)
quit