CD Actual 8

home *** CD-ROM | disk | FTP | other *** search

/ CD Actual 8 / CDACTUAL8.iso / share / os2 / utilidad / csd / basecsd2.exe / DOC / SNMPREAD.ME < prev next >

Wrap

Text File | 1992-12-16 | 17.5 KB | 465 lines

Date: Wednesday, December 9th, 1992. From: Bert Wijnen, wijnen@vnet.ibm.com, IBM-vnet: wijnen at uitvm1 To: OS/2 TCP/IP 1.2.1 December CSD users Subject: SNMP and DPI related info for the December 1992 CSD This CSD includes the following files: tcpip\bin\SNMPD.EXE fixes and enhancements applied tcpip\bin\SNMP.EXE fixes and enhancements applied tcpip\bin\SNMPGRP.EXE recompiled with changed ISODE tcpip\bin\SNMPTRAP.EXE recompiled with changed ISODE tcpip\bin\SNMPREQD.EXE recompiled tcpip\bin\MAKE_PW.EXE enhancements applied tcpip\dll\ISODEDLL.DLL fixes and enhancements applied tcpip\lib\DPI.LIB fixes and enhancements applied tcpip\include\snmp_dpi.h fixes and enhancements applied tcpip\etc\MIB2TBL enhancements applied tcpip\samples\snmpsamp SNMP related samples The following describes the changes made to each component. 1. SNMPD enhancements: a. Now accepts an argument in the form SNMPD -d <debug_level> The debug_level is a number; the following values are recognized: 1 - reserved 2 - trace DPI internals 4 - trace DPI packets 8 - trace snmpd internals 16 - trace snmpd externals 32 - trace snmp requests 64 - trace snmp replies and traps 128 - reserved Values can be combined. So to trace everything, you can issue: SNMPD -d 255 The value defaults to 255, so to trace everything you can also issue: SNMPD -d Or for example to trace just DPI related code, you can issue: SNMPD -d 6 You can also use multiple -d arguments, like: SNMPD -d 2 -d 4 -d 8 When any tracing is specified, the SNMPD version adn level will also be displayed. When you use the "trace snmpd internals" flag, SNMPD will display which snmptrap.dst file it uses and which host(s) or IP address(es) will be used to send traps to. It will also display when a trap is actually sent. b. SNMPD will be able to recognize specially configured community names to dynamically enable/disable tracing. See MAKE_PW enhancements below for a detailed description. c. Normally (default) the SNMPD agent waits a maximum of 5 seconds for a reply from an SNMP DPI sub-agent. A new argument can be passed to SNMPD at START-UP to change that value, like: SNMPD -t 10 The value specified is in seconds. Beware, that SNMPD will not respond to any other requests while it is awaiting a response from a sub-agent. d. The new SNMPD.EXE will accept both old SNMP DPI sub-agents (at DPI level 1.0) and new SNMP DPI sub-agents (at DPI level 1.1). However, old agents could get away with errors (like not having a trailing dot at the end of an objectID to be registered) in the past but not with the new SNMPD.EXE. 2. SNMPD fixes: a. SNMPD has been fixed to correctly pass the SNMP_TYPE for SET requests to SNMP DPI sub-agents. (As specified in RFC1228 and the Programmers Reference). b. Some potential memory leaks have been fixed in SNMPD. c. SNMP DPI interface has been fixed to allow 4 byte integers for generic trap type and specific trap type. d. SNMP now issues a warning (when "snmpd internal tracing" is active) if an SNMP DPI sub-agent tries to register an objectID without a trailing dot (.). 3. ISODEDLL.DLL enhancements and fixes This DLL is used by SNMP.EXE and SNMPTRAP.EXE. Also SNMPD.EXE uses this code, but has it linked in statically. The code has been fixed to: a. Correctly handle >64K values in the ObjectID b. Correctly display information when an SNMP_Message is printed (used by the -d options of SNMP and SNMPD). 4. SNMP enhancements and fixes a. A new argument can be passed (must be first argument) to enable tracing such that you can see what kind of SNMP request is sent and what kind of SNMP response comes back. Sample: SNMP -d get localhost public sysDescr.0 b. When an SNMP response arrived, SNMP would always print a OCTET_STRING as ascii printable text, except for a limited set of hard-coded objectIDs. This worked fine for the MIB-II, but not when other MIBs were added. The new SNMP command will do the following: - By default it prints an OCTET_STRING in hexadecimal form. - If the objectID is defined in MIB2TBL, then is displays the value according its type specified in MIB2TBL. So in hexadecimal form if the type is "string" and in printable ASCII if the type is "display" Beware that DISPLAY_STRING as defined in RFC1213 is a Textual Convention (TC) and that the SNMP packet itself tags both types of data as an OCTET_STRING. 5. The externals of MAKE_PW have not changed but the command itself has been enhanced to: a. Recognize comments in the input file (pw.src) b. Give better error messages if it finds an invalid entry in pw.src. c. Allow you to specify special community names that will dynamically enable/disable tracing in the SNMP agent (SNMPD). The pw.src file can have a priv_mask added to its entries. The mask can have some extra flags set to turn tracing(debugging) on/off. The format of a line in the pw.src file is: community name netw_addr mask priv_mask The mask must be 32 bits (0-31). The bits have the following meaning: /-------> bit 0 (trace on or off) |/------> bit 1 (trace SNMP responses) ||/-----> bit 2 (trace SNMP requests) |||/----> bit 3 (trace external) ||||/---> bit 4 (trace internal) |||||/--> bit 5 (trace DPI) |||||/--> bit 6 (trace DPI Internals) ||||||/-> bit 7 (reserved) ||||||| bit 31 (last bit) vvvvvvv v Priv_mask: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxs The default mask is xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxs which gives regular access rights if that community name is used just as in the past. This is the equivalent of not having a mask. Note that the trailing 's', in position 31, is required. Some samples of pw.src entries: public 0.0.0.0 0.0.0.0 password1 0.0.0.0 0.0.0.0 xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxs password2 9.0.0.0 255.0.0.0 password3 9.132.2.4 255.255.255.255 debug_all 0.0.0.0 0.0.0.0 sssssssxxxxxxxxxxxxxxxxxxxxxxxxs debug_off 0.0.0.0 0.0.0.0 xssssssxxxxxxxxxxxxxxxxxxxxxxxxs Community names "debug_all" and "debug_off" are used by an SNMP client (e.g. the SNMP.EXE cmd) to dynamically turn tracing on and off at the agent side. Operationally, when you issue a command using 'debug_all' as a community name, all possible traces are started and tracing will continue, for all future SNMP requests regardless of the community name used, until 'debug_off' is used with a command. See the sample pw.src file, in the tcpip\samples\snmpsamp directory, for more information and samples. 6. DPI.LIB and SNMP_DPI.H enhancements (DPI level 1.1) Although SNMPD does support correctly coded SNMP DPI sub-agents at DPI level 1.0, it is recommended that you recompile your DPI sub-agents and re-link them. a. The interface between a DPI sub-agent and a SNMP DPI capable agent has been fixed to correctly pass the generic trap-type and specific trap-type as 4 byte integers. So specific-type can now be a value that is >255. b. The interface has also been enhanced to allow a DPI sub-agent to specify the enterprise Objectid when it emits a trap. c. The interface has been enhanced so that you can pass multiple variables when you generate a trap. d. The interface has been fixed to not accept a mkDPIregister if the you forget the trailing dot (.) in the objectID to be registered. e. The interface allows you to call DPIdebug(1) to enable tracing of DPI internals. 7. New DPISAMPL.C program , in directory tcpip\samples\snmpsamp, replaces the old (and incorrect) DPI sample. The new sample is much more elaborate, has many more comments and is correct. Please discard the old sample and use the new one. a. The old program had bug in that it did not register the objectIDs with a trailing dot. This worked with the old agent, but it will not work with the new agent (SNMPD.EXE). If you coded a DPI sub-agent after the old sample, assure all of your mkDPIregister(...) calls to have a trailing dot for all the ObjectIDs to be registered. b. The old sample program did not show all possibilities of the DPI interface. c. The old sample shows how variable 1.3.6.1.9.1.0 returned an ASCII string of "PS/2 Mod 80". The SNMP get command would display that correctly, even though the objectID 1.3.6.1.9.1.0 was not defined in MIB2TBL. With the new SNMP.EXE, this will now be displayed as hexadecimal unless you add a line to the MIB2TBL file as follows: sampleSysDescr 1.3.6.1.9.1.0 display Then it will display in human readable form. d. The new DPI sample program also has a set of objectIDs defined in the MIB2TBL file (in \TCPIP\ETC directory), such that you can easily issue an SNMP 'get' for them. If you issue 'SNMPSAMPL ?', it displays a usage statement. 8. SNMP Agent Distributed Program Interface (DPI) This interface still supports all the old functions as described in the Programmers Reference. But 3 new functions have been added for DPI 1.1 level. These 3 functions are: DPIdebug() - to turn tracing(debug) on or off mkDPIlist() - to create a list of objectID/value pairs mkDPItrape() - to create an (extended) TRAP packet which can have an enterprise objectID and multiple variables. See "SNMP DPI Version 1.1" below for a description of these new functions. 9. SNMP DPI VERSION 1.1 ____________________ ABSTRACT ________ This document describes the enhancements made to SNMP-DPI. The original SNMP DPI (version 1.0) has been documented in RFC1228. Please refer to that document for a complete description. You can also use the MVS, VM or OS2 Programmers Reference Manuals, section "SNMP Agent Distributed Program Interface (DPI)", as a reference for SNMP DPI version 1.0. Version 1.1 basically has the same interface, plus: - 3 additional DPI Library Routines - Some changes to the structures made available. We have coded the SNMP DPI 1.1 agents such that they will be able to handle both DPI 1.0 and DPI 1.1 clients. NEW DPI LIBRARY ROUTINES. __________________________ DPIDEBUG() DDDDDDDDDD #include <snmp_dpi.h> #include <types.h> void DPIdebug (onoff) int onoff; Parameter Description onoff If value is 1, tracing is turned on. If value is 0, tracing if turned off. Description: The DPIdebug() routine can be used to turn DPI internal tracing on or off. MKDPILIST() ___________ #include <snmp_dpi.h> #include <types.h> struct dpi_set_packet *mkDPIlist(packet, oid_name, type, len, value) struct dpi_set_packet *packet; char *oid_name; int type; int len; char *value; Parameter Description packet A pointer to a structure dpi_set_packet. Or NULL. oid_name The object identifier of the variable. type The type of the value. len The length of the value. value A pointer to the value. Description: The mkDPIlist() routine can be used to create the portion of the parse tree that represents a list of name and value pairs. Each entry in the list represents a name and value pair (as would normally be returned in a response packet). If the pointer packet is NULL, then a new dpi_set_packet structure is dynamically allocated and the pointer to that structure is returned. The structure will contain the new name and value pair. If the pointer packet is not NULL, then a new dpi_set_packet structure is dynamically allocated and chained to the list. The new structure will contain the new name and value pair. The pointer packet will be returned to the caller. If an error is detected, a NULL pointer is returned. The value of type can be the same as for mkDPIset(). This is defined in the snmp_dpi.h header file. As a result of this change, the structure dpi_set_packet has changed and now has a next pointer (zero in case of a mkDPIset() call and also zero upon the first mkDPIlist() call). The new structure is shown below: struct dpi_set_packet { char *object_id; unsigned char type; unsigned short value_len; char *value; struct dpi_set_packet *next; }; MKDPITRAPE() ____________ #include <snmp_dpi.h> #include <types.h> unsigned char *mkDPItrape(generic, specific, value_list, enterprise_oid) long int generic; /* 4 octet integer */ long int specific; struct dpi_set_packet *value_list; char *enterprise_oid; Parameter Description generic The generic field for the SNMP TRAP packet. specific The specific field for the SNMP TRAP packet. value_list A ptr to a structure dpi_set_packet, which contains one or more variables to be send with the SNMP TRAP packet. Or NULL if no variables are to be send. enterprise_oid A ptr to a character string representing the enterprise object ID (in ASN.1 notation, e.g. 1.3.6.1.4.1.2.2.1.4). Or NULL if you want the SNMP agent to use its own enterprise object ID. Description: The mkDPItrape() routine can be used to create an "extended" trap. It is basically the same as the mkDPItrap() routine, but allows you to pass a list of variables, and also an enterprise object ID. As a result, the structure for dpi_trap_packet has changed, but this structure is not exposed to sub_agent writers. PDPIPACKET() ____________ This function returns a pointer to a structure, snmp_dpi_hdr, which in case of a SET request, contains a pointer to a structure, dpi_set_packet. The new structure is shown below: struct dpi_set_packet { char *object_id; unsigned char type; unsigned short value_len; char *value; struct dpi_set_packet *next; }; EXAMPLE OF AN EXTENDED TRAP ___________________________ The following is a piece of sample code to send an extended trap. No error checking is done. struct dpi_set_packet *set; int len; long int num = 15; /* 4 octet integer */ unsigned long int ctr = 1234; char str Y = "a string"; unsigned char *packet; set = 0; /* First call to mkDPIlist req. 0 ptr */ set = mkDPIlist (set, "1.3.6.1.4.1.2.2.1.4.1", SNMP_TYPE_NUMBER, sizeof(num), &num); set = mkDPIlist (set, "1.3.6.1.4.1.2.2.1.4.2", SNMP_TYPE_STRING, strlen(str), str); set = mkDPIlist (set, "1.3.6.1.4.1.2.2.1.4.6", SNMP_TYPE_COUNTER, sizeof(ctr), &ctr); packet = mkDPItrape (6L, 37L, set, "1.3.6.1.4.1.2.2.1.4"); len = *packet * 256 + *(packet+1); len += 2; write (fd, packet, len) /* use send for OS/2 */ You can use a mkDPIset() call to create an initial dpi_set_packet for the first name and value pair. So the following sample is equivalent to the one above. struct dpi_set_packet *set; int len; long int num = 15; /* 4 octet integer */ unsigned long int ctr = 1234; char str Y = "a string"; unsigned char *packet; set = mkDPIset ("1.3.6.1.4.1.2.2.1.4.1", SNMP_TYPE_NUMBER, sizeof(num), &num); set = mkDPIlist (set, "1.3.6.1.4.1.2.2.1.4.2", SNMP_TYPE_STRING, strlen(str), str); set = mkDPIlist (set, "1.3.6.1.4.1.2.2.1.4.6", SNMP_TYPE_COUNTER, sizeof(ctr), &ctr); packet = mkDPItrape (6L, 37L, set, "1.3.6.1.4.1.2.2.1.4"); len = *packet * 256 + *(packet+1); len += 2; write (fd, packet, len) /* use send for OS/2 */ If the high order bit must be on for the specific trap type, then a negative integer must be passed.