POLYCENTER Common Agent Developer's Toolkit for DEC OSF/1 AXP Version V1.1-0 Release Notes June 1993 Introduction This document provides the latest information about the POLYCENTER Common Agent Developer's Toolkit for DEC OSF/1 AXP Version V1.1-0. It describes restrictions, problems, suggestions and recommended procedures. It also includes information which could not be included in the documentation. Please read this document before you attempt to install or use this software. CHAPTER 1 INTRODUCTION 1.1 POLYCENTER COMMON AGENT DEVELOPER'S TOOLKIT FOR DEC OSF/1 AXP V1.1-0 Before you install this kit, read Chapter 2, "System Considerations". This chapter contains critical information about the installation and runtime requirements of the kit. Chapter 3 contains detailed information about undocumented features and current limitations of the components contained in this product release. CHAPTER 2 SYSTEM CONSIDERATIONS This chapter contains the system-specific information required to run the POLYCENTER Common Agent Developer's Toolkit for DEC OSF/1 AXP Version V1.1-0 software. It includes the following topics: o General system considerations o Security considerations 2.1 GENERAL SYSTEM CONSIDERATIONS This section discusses general system considerations for installing, managing, or using POLYCENTER Common Agent Developer's Toolkit for DEC OSF/1 AXP Version V1.1-0. 2.1.1 Interprocess Communication The interprocess communication used is based on UNIX domain sockets. The sockets are named with the following UNIX pathnames: /dev/eca_evd /dev/eca_mold /dev/eca_mom_ /dev/eca_snmp_pe The process that binds the name to the socket must have "write" permission on the directory where the bound socket will reside. Therefore, the daemon processes must have root priviledges (UID = 0) to write to the /dev directory. If the snmp_pe, mold, or evd daemon is stopped for any reason, then the Common Agent must be re-started by the following startup command: /sbin/init.d/common_agent start SYSTEM CONSIDERATIONS Page 2-2 In most circumstances the MOM images may be successfully re-executed without restarting all the Common Agent daemons. 2.2 SECURITY CONSIDERATIONS All the runtime daemons of the Common Agent must execute under the root account (UID = 0): o snmp_pe process o mold process o evd process o internet_mom process o fddi_mom process o all MOM processes CHAPTER 3 SOFTWARE NOTES This chapter describes any known problems and workaround solutions with the POLYCENTER Common Agent V1.1-0 for DEC OSF/1 AXP. 3.1 MANAGED OBJECT LOCATION DIRECTORY (MOLD) When the /usr/sbin/mold program begins executing, it reads the Common Agent MIR and produces an internal directory of the class hierarchy. The default pathname of the MIR is /etc/eca/mir.dat, which is the mir for the internet_mom and fddi_mom processes. The mir also contains the class information for the example MOMs provided with the kit. You can override the default pathname using the environment variable ECA_MIR, such as in the following example: % setenv ECA_MIR /users/u1/ca_dev/mir.dat (csh) % export ECA_MIR; ECA_MIR=/users/u1/ca_dev/mir.dat (ksh, sh) If you wish to use an alternate MIR, you must do the following: 1. Stop the Common Agent processes (including your MOM(s)) 2. Set the ECA_MIR environment variable 3. Restart the Common Agent processes If you are a MOM developer and have a private MIR file for development, you must set the above environment variable to point to your MIR file, and then restart the Common Agent processes. To aid in debugging during MOM development, the MOLD will take a -d option to dump the MOLD internal data structures to a file. In the following example, the MOLD starts up in the background, reads the MIR file and dumps its internal data structures to the file /users/u1/ca_dev/mold.dmp. SOFTWARE NOTES Page 3-2 mold -d /users/u1/ca_dev/mold.dmp This MOLD dump file can be examined to check if the MIR file has been read correctly. Another debugging tool called the mold_dump utility is also available. Using this tool, you can dump the MOLD internal data structures any time after the MOLD has started up. In the following example, the MOLD internal data structures are dumped to the file /users/u1/ca_dev/a.dmp: mold_dump -d /users/u1/ca_dev/a.dmp When a MOM starts up and registers its Managed Objects with the MOLD via calls to the moss_register() routine, it can register the Managed Objects in any order. Parent classes need be to defined in the MIR but they do not need to be registered. 3.1.1 Restrictions Each MOM must register its top-most Managed Object as defined in the MIB definition file under the SNMP Object (1.3.6.1.2.1) which is provided by the DEC OSF/1 AXP Common Agent. The above restriction is also required for the 'mold -d' option and 'mold_dump' utility to work correctly. 3.2 INTERNET_MOM 1. If /usr/sbin/gated is not executing, then default information will be returned for the following ipRoute table variables and the entire Egp group. 1. ipRouteMetric1 2. ipRouteAge 3. ipRouteProto 4. ipRouteType 2. The value of the ifSpeed variable is always returned as zero for all interfaces. (DEC OSF/1 bug) 3. The following list of mib objects are specified by IETF RFC-1213 to be read-write. The security policy for the DEC OSF/1 AXP platform restricts access to these variables to be read-only: SOFTWARE NOTES Page 3-3 1. sysName 2. ifAdminStatus 3. atIfIndex 4. atPhysAddress 5. atNetAddress 6. ipForwarding 7. ipDefaultTTL 8. ipRouteDest 9. ipRouteIfIndex 10. ipRouteMetric1 11. ipRouteMetric2 12. ipRouteMetric3 13. ipRouteMetric4 14. ipRouteNextHop 15. ipRouteType 16. ipRouteAge 17. ipRouteMask 18. ipRouteMetric5 19. IpNetToMediaIfIndex 20. ipNetToMediaPhysAddress 21. ipNetToMediaNetAddress 22. ipNetToMediaType 23. tcpConnState 4. The following list of read-write mib objects which are specified by IETF RFC-1213 to be read-write are supported as read-write variables: 1. sysContact 2. sysLocation SOFTWARE NOTES Page 3-4 3. snmpEnableAuthenTraps 5. The egpNeighborLoss trap is not supported. 3.3 SNMP PROTOCOL ENGINE (SNMP_PE) 3.3.1 Usage Before you run the SNMP Protocol Engine process (/usr/sbin/snmp_pe), check that the DEC OSF/1 AXP SNMP daemon (/usr/sbin/snmpd) is stopped. The snmp_pe process uses the getservbyname service to determine the port numbers for the following services using the UDP protocol: o snmp - for servicing incoming SNMP PDU requests o snmp-trap - for sending outgoing response and trap PDUs o snmp-rt - for interfacing with routed/gated 3.4 MOMGEN 3.4.1 Restrictions 1. Multithreaded MOMs The development libraries and the generated code are designed to support multithreaded MOMs using the DECthreads POSIX 1003.4 interface. 2. Instance Datatypes Table entries are typically identified using an integer index and the generated code supports this. Other datatypes are possible, most notably ipAddress. The only datatype supported at this time is integer. You will have to modify the code in [class_prefix]perform_getnext.c where noted in the generated code if you are using a non-integer datatype. Examine the 00readme.txt and source files in /usr/examples/eca/udpexample_mom.dir for examples of how to index into a table using a value other than an integer. SOFTWARE NOTES Page 3-5 3.5 MODIFYING MOM CODE 3.5.1 Clarification MOMGEN generates routines, _perform_init(), that perform class initialization. This includes allocating memory for an element that gets linked to the head of the list in the _DEF structure. This first element in the list should NOT be used for instantiation. To load instance data, allocate memory using malloc() (even when there is only a single instance in the class), add that element to the end of the doubly-linked-list using the _add_new_instance routine, and then populate it! This needs to be repeated for each instance in the class. It is recommended that a separate module be created to maintain the instance information, which can then be called from the MOM routines that need this information. Refer to the refresh_hrStorageEntry_list() routine in dstor_mom's hrstorageentry_getmnt.c module for an example of how the instance information is maintained. 3.6 EXAMPLE MOMS The example MOMs referenced in the documentation have been included in the kit. You can use them as coding examples and as running MOMs. The required files are under /usr/opt/EDO110/examples. To generate either example MOM, change your default directory to one of these directories, and then issue a make command: % cd /examples/ % make 3.7 TEST MANAGER (TMAN) The Test Manager can be used to debug and/or test MOMs by sending and receiving SNMP PDUs to/from the Common Agent. The program is installed as /usr/sbin/tman. This test utility is an unsupported utility. 3.7.1 Usage Notes The following is a dump of the instructions given when tman is run without arguments. % tman SOFTWARE NOTES Page 3-6 SNMP Protocol Engine Test Manager options: ([ ...OPTIONAL... ]) [-p ] (a number) [-c ""] (a string) [-r ] (a number) [-d ] (otherwise stdout) [-x ] (positive integer) [ ASN1 ] (exactly as shown for ASN.1 dump) (REQUIRED) (One of SET, GET, GETNEXT, GETNEXTLOOP or PESHUTDOWN) (For GET, GETNEXT & GETNEXTLOOP) (in "dot" notation, as many as needed) (For SET, any number of groups of) (in "dot" notation) where is one of: INTEGER OCTETSTRING OBJECTID NULL IPADDR COUNTER GAUGE TIMETICKS OPAQUE where is one of: "" for OCTETSTRING OPAQUE for INTEGER COUNTER GAUGE TIMETICKS in "dot" notation for IPADDR in "dot" notation for OBJECTID Note that for NULL, is omitted Examples: tman dirac get 1.2.3.4 --simple GET tman asn1 dirac get 1.2.3.4 -- ...with ASN.1 dump tman dirac get 1.2.3.4 1.3.3 --multiple GET tman dirac set 1.2.3.4 integer 4 --simple SET tman dirac set 1.2.3.4 integer 4 1.3.4 objectid 1.3 --multiple SET tman dirac getnext 1.2.3.4 --simple GET-NEXT tman dirac getnextloop 1.2.3.4 --simple GET-NEXT Loop tman dirac peshutdown --shutdown test SNMP PE GETNEXTLOOP performs as a normal GET-NEXT, but upon receipt of a "noerror" response, immediately re-issues the received PDU as another GET-NEXT request. This operation repeats until an "error" response is received. Can be used to walk a MIB. CHAPTER 4 DOCUMENTATION This chapter lists the documentation provided for the POLYCENTER Common Agent Developer's Toolkit for DEC OSF/1 AXP Version V1.1-0, and any documentation errata. 4.1 LIST OF DOCUMENTS The documentation set consists of the following manuals: o POLYCENTER Common Agent Installation Guide for DEC OSF/1 AXP Systems o POLYCENTER Common Agent Managed Object Module Developer's Guide o POLYCENTER Common Agent Managed Object Module Developer's Reference CHAPTER 5 PROBLEM REPORTING PROCEDURES If you encounter a problem with the POLYCENTER Common Agent Developer's Toolkit V1.1-0 for DEC OSF/1 AXP software or documentation, take the following actions: 1. If the problem is a software crash, or if the software does not behave correctly (a function does not work as documented), then record the environment in which you found the problem. If the problem was seen with a particular process or utility, note the exact process or note the utility exactly as entered. If the problem was with data about a particular system or component, then record the identified component. 2. Attempt to reproduce the problem by going over the steps you took that led up to the crash. 3. Submit an SPR for the problem.