home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 29 Fixes_o / 29-Fixes_o.zip / tcpcsd2.zip / BASECSD2.EXE / DOC / SNMPREAD.ME < prev    next >
Text File  |  1992-12-16  |  18KB  |  465 lines
  1. Date:    Wednesday, December 9th, 1992.
  2. From:    Bert Wijnen, wijnen@vnet.ibm.com, IBM-vnet: wijnen at uitvm1
  3. To:      OS/2 TCP/IP 1.2.1 December CSD users
  4. Subject: SNMP and DPI related info for the December 1992 CSD
  5.  
  6. This CSD includes the following files:
  7.    tcpip\bin\SNMPD.EXE         fixes and enhancements applied
  8.    tcpip\bin\SNMP.EXE          fixes and enhancements applied
  9.    tcpip\bin\SNMPGRP.EXE       recompiled with changed ISODE
  10.    tcpip\bin\SNMPTRAP.EXE      recompiled with changed ISODE
  11.    tcpip\bin\SNMPREQD.EXE      recompiled
  12.    tcpip\bin\MAKE_PW.EXE       enhancements applied
  13.    tcpip\dll\ISODEDLL.DLL      fixes and enhancements applied
  14.    tcpip\lib\DPI.LIB           fixes and enhancements applied
  15.    tcpip\include\snmp_dpi.h    fixes and enhancements applied
  16.    tcpip\etc\MIB2TBL           enhancements applied
  17.    tcpip\samples\snmpsamp      SNMP related samples
  18.  
  19.  
  20. The following describes the changes made to each component.
  21.  
  22. 1. SNMPD enhancements:
  23.  
  24.    a. Now accepts an argument in the form
  25.          SNMPD -d <debug_level>
  26.  
  27.       The debug_level is a number; the following values are recognized:
  28.  
  29.          1    - reserved
  30.          2    - trace DPI internals
  31.          4    - trace DPI packets
  32.          8    - trace snmpd internals
  33.          16   - trace snmpd externals
  34.          32   - trace snmp requests
  35.          64   - trace snmp replies and traps
  36.          128  - reserved
  37.  
  38.       Values can be combined. So to trace everything, you can issue:
  39.          SNMPD -d 255
  40.  
  41.       The value defaults to 255, so to trace everything you can also issue:
  42.          SNMPD -d
  43.  
  44.       Or for example to trace just DPI related code, you can issue:
  45.          SNMPD -d 6
  46.  
  47.       You can also use multiple -d arguments, like:
  48.          SNMPD -d 2 -d 4 -d 8
  49.  
  50.       When any tracing is specified, the SNMPD version adn level will also be
  51.       displayed.
  52.  
  53.       When you use the "trace snmpd internals" flag, SNMPD will display which
  54.       snmptrap.dst file it uses and which host(s) or IP address(es) will be
  55.       used to send traps to. It will also display when a trap is actually sent.
  56.  
  57.    b. SNMPD will be able to recognize specially configured community names to
  58.       dynamically enable/disable tracing. See MAKE_PW enhancements below for a
  59.       detailed description.
  60.  
  61.    c. Normally (default) the SNMPD agent waits a maximum of 5 seconds for a
  62.       reply from an SNMP DPI sub-agent. A new argument can be passed to SNMPD
  63.       at START-UP to change that value, like:
  64.  
  65.          SNMPD -t 10
  66.  
  67.       The value specified is in seconds. Beware, that SNMPD will not respond to
  68.       any other requests while it is awaiting a response from a sub-agent.
  69.  
  70.    d. The new SNMPD.EXE will accept both old SNMP DPI sub-agents (at DPI level
  71.       1.0) and new SNMP DPI sub-agents (at DPI level 1.1). However, old agents
  72.       could get away with errors (like not having a trailing dot at the end of
  73.       an objectID to be registered) in the past but not with the new SNMPD.EXE.
  74.  
  75. 2. SNMPD fixes:
  76.  
  77.    a. SNMPD has been fixed to correctly pass the SNMP_TYPE for SET requests
  78.       to SNMP DPI sub-agents. (As specified in RFC1228 and the Programmers
  79.       Reference).
  80.  
  81.    b. Some potential memory leaks have been fixed in SNMPD.
  82.  
  83.    c. SNMP DPI interface has been fixed to allow 4 byte integers for generic
  84.       trap type and specific trap type.
  85.  
  86.    d. SNMP now issues a warning (when "snmpd internal tracing" is active) if
  87.       an SNMP DPI sub-agent tries to register an objectID without a trailing
  88.       dot (.).
  89.  
  90. 3. ISODEDLL.DLL enhancements and fixes
  91.  
  92.    This DLL is used by SNMP.EXE and SNMPTRAP.EXE. Also SNMPD.EXE uses this
  93.    code, but has it linked in statically. The code has been fixed to:
  94.  
  95.    a. Correctly handle >64K values in the ObjectID
  96.  
  97.    b. Correctly display information when an SNMP_Message is printed (used by
  98.       the -d options of SNMP and SNMPD).
  99.  
  100. 4. SNMP enhancements and fixes
  101.  
  102.    a. A new argument can be passed (must be first argument) to enable tracing
  103.       such that you can see what kind of SNMP request is sent and what kind
  104.       of SNMP response comes back. Sample:
  105.  
  106.         SNMP -d get localhost public sysDescr.0
  107.  
  108.    b. When an SNMP response arrived, SNMP would always print a OCTET_STRING
  109.       as ascii printable text, except for a limited set of hard-coded objectIDs.
  110.       This worked fine for the MIB-II, but not when other MIBs were added.
  111.       The new SNMP command will do the following:
  112.  
  113.       - By default it prints an OCTET_STRING in hexadecimal form.
  114.  
  115.       - If the objectID is defined in MIB2TBL, then is displays the value
  116.         according its type specified in MIB2TBL. So in hexadecimal form if
  117.         the type is "string" and in printable ASCII if the type is "display"
  118.  
  119.       Beware that DISPLAY_STRING as defined in RFC1213 is a Textual Convention
  120.       (TC) and that the SNMP packet itself tags both types of data as an
  121.       OCTET_STRING.
  122.  
  123. 5. The externals of MAKE_PW have not changed but the command itself has been
  124.     enhanced to:
  125.  
  126.    a. Recognize comments in the input file (pw.src)
  127.  
  128.    b. Give better error messages if it finds an invalid entry in pw.src.
  129.  
  130.    c. Allow you to specify special community names that will dynamically
  131.       enable/disable tracing in the SNMP agent (SNMPD).
  132.  
  133.       The pw.src file can have a priv_mask added to its entries. The mask can
  134.       have some extra flags set to turn tracing(debugging) on/off. The format
  135.       of a line in the pw.src file is:
  136.  
  137.       community name  netw_addr    mask             priv_mask
  138.  
  139.       The mask must be 32 bits (0-31). The bits have the following meaning:
  140.  
  141.                           /-------> bit 0 (trace on or off)
  142.                           |/------> bit 1 (trace SNMP responses)
  143.                           ||/-----> bit 2 (trace SNMP requests)
  144.                           |||/----> bit 3 (trace external)
  145.                           ||||/---> bit 4 (trace internal)
  146.                           |||||/--> bit 5 (trace DPI)
  147.                           |||||/--> bit 6 (trace DPI Internals)
  148.                           ||||||/-> bit 7 (reserved)
  149.                           |||||||                        bit 31 (last bit)
  150.                           vvvvvvv                        v
  151.       Priv_mask:          xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxs
  152.  
  153.       The default mask is xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxs which gives regular
  154.       access rights if that community name is used just as in the past. This
  155.       is the equivalent of not having a mask. Note that the trailing 's', in
  156.       position 31, is required.
  157.  
  158.       Some samples of pw.src entries:
  159.  
  160.       public           0.0.0.0   0.0.0.0
  161.       password1        0.0.0.0   0.0.0.0   xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxs
  162.       password2        9.0.0.0   255.0.0.0
  163.       password3        9.132.2.4 255.255.255.255
  164.       debug_all        0.0.0.0   0.0.0.0   sssssssxxxxxxxxxxxxxxxxxxxxxxxxs
  165.       debug_off        0.0.0.0   0.0.0.0   xssssssxxxxxxxxxxxxxxxxxxxxxxxxs
  166.  
  167.  
  168.       Community names "debug_all" and "debug_off" are used by an SNMP client
  169.       (e.g. the SNMP.EXE cmd) to dynamically turn tracing on and off at the
  170.       agent side. Operationally, when you issue a command using 'debug_all' as
  171.       a community name, all possible traces are started and tracing will
  172.       continue, for all future SNMP requests regardless of the community name
  173.       used, until 'debug_off' is used with a command.
  174.  
  175.       See the sample pw.src file, in the tcpip\samples\snmpsamp directory, for
  176.       more information and samples.
  177.  
  178. 6. DPI.LIB and SNMP_DPI.H enhancements (DPI level 1.1)
  179.  
  180.    Although SNMPD does support correctly coded SNMP DPI sub-agents at DPI
  181.    level 1.0, it is recommended that you recompile your DPI sub-agents and
  182.    re-link them.
  183.  
  184.    a. The interface between a DPI sub-agent and a SNMP DPI capable agent has
  185.       been fixed to correctly pass the generic trap-type and specific trap-type
  186.       as 4 byte integers. So specific-type can now be a value that is >255.
  187.  
  188.    b. The interface has also been enhanced to allow a DPI sub-agent to specify
  189.       the enterprise Objectid when it emits a trap.
  190.  
  191.    c. The interface has been enhanced so that you can pass multiple variables
  192.       when you generate a trap.
  193.  
  194.    d. The interface has been fixed to not accept a mkDPIregister if the you
  195.       forget the trailing dot (.) in the objectID to be registered.
  196.  
  197.    e. The interface allows you to call DPIdebug(1) to enable tracing of DPI
  198.       internals.
  199.  
  200. 7. New DPISAMPL.C program , in directory tcpip\samples\snmpsamp, replaces the
  201.    old (and incorrect) DPI sample. The new sample is much more elaborate, has
  202.    many more comments and is correct. Please discard the old sample and use
  203.    the new one.
  204.  
  205.    a. The old program had bug in that it did not register the objectIDs with a
  206.       trailing dot. This worked with the old agent, but it will not work with
  207.       the new agent (SNMPD.EXE). If you coded a DPI sub-agent after the old
  208.       sample, assure all of your mkDPIregister(...) calls to have a trailing
  209.       dot for all the ObjectIDs to be registered.
  210.  
  211.    b. The old sample program did not show all possibilities of the DPI
  212.       interface.
  213.  
  214.    c. The old sample shows how variable 1.3.6.1.9.1.0 returned an ASCII string
  215.       of "PS/2 Mod 80". The SNMP get command would display that correctly, even
  216.       though the objectID 1.3.6.1.9.1.0 was not defined in MIB2TBL. With the
  217.       new SNMP.EXE, this will now be displayed as hexadecimal unless you add a
  218.       line to the MIB2TBL file as follows:
  219.  
  220.         sampleSysDescr  1.3.6.1.9.1.0 display
  221.  
  222.       Then it will display in human readable form.
  223.  
  224.   d. The new DPI sample program also has a set of objectIDs defined in the
  225.      MIB2TBL file (in \TCPIP\ETC directory), such that you can easily issue an
  226.      SNMP 'get' for them. If you issue 'SNMPSAMPL ?', it displays a usage
  227.      statement.
  228.  
  229. 8. SNMP Agent Distributed Program Interface (DPI)
  230.  
  231.    This interface still supports all the old functions as described in the
  232.    Programmers Reference. But 3 new functions have been added for DPI 1.1
  233.    level. These 3 functions are:
  234.  
  235.       DPIdebug()       - to turn tracing(debug) on or off
  236.       mkDPIlist()      - to create a list of objectID/value pairs
  237.       mkDPItrape()     - to create an (extended) TRAP packet which can have an
  238.                          enterprise objectID and multiple variables.
  239.  
  240.   See "SNMP DPI Version 1.1" below for a description of these new functions.
  241.  
  242.  
  243. 9. SNMP DPI VERSION 1.1
  244.    ____________________
  245.  
  246.   ABSTRACT
  247.   ________
  248.  
  249.     This document describes the enhancements made to SNMP-DPI. The original
  250.     SNMP DPI (version 1.0) has been documented in RFC1228. Please refer to
  251.     that document for a complete description.
  252.  
  253.     You can also use the MVS, VM or OS2 Programmers Reference Manuals, section
  254.     "SNMP Agent Distributed Program Interface (DPI)", as a reference for SNMP
  255.     DPI version 1.0.
  256.  
  257.     Version 1.1 basically has the same interface, plus:
  258.  
  259.     -   3 additional DPI Library Routines
  260.     -   Some changes to the structures made available.
  261.  
  262.     We have coded the SNMP DPI 1.1 agents such that they will be able to handle
  263.     both DPI 1.0 and DPI 1.1 clients.
  264.  
  265.  
  266.   NEW DPI LIBRARY  ROUTINES.
  267.   __________________________
  268.  
  269.  
  270.   DPIDEBUG()
  271.   DDDDDDDDDD
  272.     #include <snmp_dpi.h>
  273.     #include <types.h>
  274.  
  275.     void DPIdebug (onoff)
  276.  
  277.     int   onoff;
  278.  
  279.  
  280.     Parameter Description
  281.  
  282.     onoff     If value is 1, tracing is turned on.
  283.               If value is 0, tracing if turned off.
  284.  
  285.     Description: The DPIdebug() routine can be used to turn DPI internal
  286.     tracing on or off.
  287.  
  288.  
  289.   MKDPILIST()
  290.   ___________
  291.  
  292.     #include <snmp_dpi.h>
  293.     #include <types.h>
  294.  
  295.     struct dpi_set_packet *mkDPIlist(packet, oid_name, type, len, value)
  296.  
  297.     struct dpi_set_packet *packet;
  298.     char  *oid_name;
  299.     int    type;
  300.     int    len;
  301.     char  *value;
  302.  
  303.     Parameter Description
  304.  
  305.     packet    A pointer to a structure dpi_set_packet.  Or NULL.
  306.  
  307.     oid_name  The object identifier of the variable.
  308.  
  309.     type      The type of the value.
  310.  
  311.     len       The length of the value.
  312.  
  313.     value     A pointer to the value.
  314.  
  315.  
  316.     Description: The mkDPIlist() routine can be used to create the portion of
  317.     the parse tree that represents a list of name and value pairs. Each entry
  318.     in the list represents a name and value pair (as would normally be returned
  319.     in a response packet).
  320.  
  321.     If the pointer packet is NULL, then a new dpi_set_packet structure is
  322.     dynamically allocated and the pointer to that structure is returned. The
  323.     structure will contain the new name and value pair.
  324.  
  325.     If the pointer packet is not NULL, then a new dpi_set_packet structure is
  326.     dynamically allocated and chained to the list. The new structure will
  327.     contain the new name and value pair.
  328.  
  329.     The pointer packet will be returned to the caller.
  330.  
  331.     If an error is detected, a NULL pointer is returned.
  332.  
  333.     The value of type can be the same as for mkDPIset(). This is defined in the
  334.     snmp_dpi.h header file.
  335.  
  336.     As a result of this change, the structure dpi_set_packet has changed and
  337.     now has a next pointer (zero in case of a mkDPIset() call and also zero
  338.     upon the first mkDPIlist() call). The new structure is shown below:
  339.  
  340.       struct dpi_set_packet {
  341.         char                 *object_id;
  342.         unsigned char         type;
  343.         unsigned short        value_len;
  344.         char                  *value;
  345.         struct dpi_set_packet *next;
  346.       };
  347.  
  348.  
  349.   MKDPITRAPE()
  350.   ____________
  351.  
  352.     #include <snmp_dpi.h>
  353.     #include <types.h>
  354.  
  355.     unsigned char *mkDPItrape(generic, specific, value_list, enterprise_oid)
  356.  
  357.     long int  generic;       /* 4 octet integer */
  358.     long int  specific;
  359.     struct    dpi_set_packet *value_list;
  360.     char     *enterprise_oid;
  361.  
  362.  
  363.     Parameter       Description
  364.  
  365.     generic         The generic field for the SNMP TRAP packet.
  366.  
  367.     specific        The specific field for the SNMP TRAP packet.
  368.  
  369.     value_list      A ptr to a structure dpi_set_packet, which contains one or
  370.                     more variables to be send with the SNMP TRAP packet. Or
  371.                     NULL if no variables are to be send.
  372.  
  373.     enterprise_oid  A ptr to a character string representing the enterprise
  374.                     object ID (in ASN.1 notation, e.g. 1.3.6.1.4.1.2.2.1.4). Or
  375.                     NULL if you want the SNMP agent to use its own enterprise
  376.                     object ID.
  377.  
  378.     Description:    The mkDPItrape() routine can be used to create an "extended"
  379.                     trap. It is basically the same as the mkDPItrap() routine,
  380.                     but allows you to pass a list of variables, and also an
  381.                     enterprise object ID.
  382.  
  383.     As a result, the structure for dpi_trap_packet has changed, but this
  384.     structure is not exposed to sub_agent writers.
  385.  
  386.  
  387.   PDPIPACKET()
  388.   ____________
  389.  
  390.     This function returns a pointer to a structure, snmp_dpi_hdr, which in case
  391.     of a SET request, contains a pointer to a structure, dpi_set_packet. The
  392.     new structure is shown below:
  393.  
  394.       struct dpi_set_packet {
  395.         char                 *object_id;
  396.         unsigned char         type;
  397.         unsigned short        value_len;
  398.         char                  *value;
  399.         struct dpi_set_packet *next;
  400.       };
  401.  
  402.  
  403.   EXAMPLE OF AN EXTENDED TRAP
  404.   ___________________________
  405.  
  406.   The following is a piece of sample code to send an extended trap. No error
  407.   checking is done.
  408.  
  409.        struct dpi_set_packet *set;
  410.        int                    len;
  411.        long int               num = 15;  /* 4 octet integer */
  412.        unsigned long int      ctr = 1234;
  413.        char                   strY = "a string";
  414.        unsigned char         *packet;
  415.  
  416.        set = 0;                     /* First call to mkDPIlist req. 0 ptr */
  417.  
  418.        set = mkDPIlist (set, "1.3.6.1.4.1.2.2.1.4.1", SNMP_TYPE_NUMBER,
  419.                         sizeof(num), &num);
  420.  
  421.        set = mkDPIlist (set, "1.3.6.1.4.1.2.2.1.4.2", SNMP_TYPE_STRING,
  422.                         strlen(str), str);
  423.  
  424.        set = mkDPIlist (set, "1.3.6.1.4.1.2.2.1.4.6", SNMP_TYPE_COUNTER,
  425.                         sizeof(ctr), &ctr);
  426.  
  427.        packet = mkDPItrape (6L, 37L, set, "1.3.6.1.4.1.2.2.1.4");
  428.  
  429.        len = *packet * 256 + *(packet+1);
  430.        len += 2;
  431.  
  432.        write (fd, packet, len)                 /* use send for OS/2 */
  433.  
  434.  
  435.    You can use a mkDPIset() call to create an initial dpi_set_packet for the
  436.    first name and value pair. So the following sample is equivalent to the one
  437.    above.
  438.  
  439.        struct dpi_set_packet *set;
  440.        int                    len;
  441.        long int               num = 15;  /* 4 octet integer */
  442.        unsigned long int      ctr = 1234;
  443.        char                   strY = "a string";
  444.        unsigned char         *packet;
  445.  
  446.        set = mkDPIset ("1.3.6.1.4.1.2.2.1.4.1", SNMP_TYPE_NUMBER,
  447.                        sizeof(num), &num);
  448.  
  449.        set = mkDPIlist (set, "1.3.6.1.4.1.2.2.1.4.2", SNMP_TYPE_STRING,
  450.                         strlen(str), str);
  451.  
  452.        set = mkDPIlist (set, "1.3.6.1.4.1.2.2.1.4.6", SNMP_TYPE_COUNTER,
  453.                         sizeof(ctr), &ctr);
  454.  
  455.        packet = mkDPItrape (6L, 37L, set, "1.3.6.1.4.1.2.2.1.4");
  456.  
  457.        len = *packet * 256 + *(packet+1);
  458.        len += 2;
  459.  
  460.        write (fd, packet, len)   /* use send for OS/2 */
  461.  
  462.  
  463.    If the high order bit must be on for the specific trap type, then a negative
  464.    integer must be passed.
  465.