Analysis

Use the following checklist to check for problems connecting an SNMP subagent program to the SNMP agent:
  1. Are there multiple TCP/IP stacks active on the same MVS™ image, are there subagents active for each stack, and are the subagents using UNIX to connect to the agent (as opposed to using TCP)? If so, have you configured a unique UNIX pathname to be used by the subagents connecting to the Agent through UNIX? In a multi-stack environment, each Agent must use a unique UNIX pathname for subagent connections. The default UNIX pathname is /var/dpi_socket. Additional UNIX pathnames can be specified in one of two ways:
    • As the value of the dpiPathNameForUnixStream MIB object in the OSNMPD.DATA configuration file read by the Agent.
    • On the -s start option in the PARM= field of the EXEC JCL statement in the Agent's started procedure.
  2. Is the subagent in question the TCP/IP subagent? If so,
    • Is the SACONFIG statement configured correctly?
    • Is SACONFIG disabled?
  3. Is the subagent in question the OMPROUTE subagent?
    • Is the OMPROUTE ROUTESA_CONFIG statement configured correctly?
    • Is the OMPROUTE subagent (ROUTESA) disabled?
    • Does the port number match the SNMP agent and OMPROUTE application for the OMPROUTE ROUTESA_CONFIG parameter AGENT=<agent port number>?
    • Does the community name (or password) match with the SNMP agent and OMPROUTE application for the OMPROUTE ROUTESA_CONFIG parameter COMMUNITY=<community string>?
  4. Is the subagent in question the Network SLAPM2 subagent?
    • Does the port number specified on the -P parameter of the Network SLAPM2 subagent match the port number specified by the SNMP agent?
    • Does the community name (or password) specified on the -c parameter of the Network SLAPM2 subagent match the community name (or password) specified by the SNMP agent?
  5. Is the subagent in question the TN3270E Telnet subagent? If so:
    • Is the TNSACONFIG statement configured correctly?
    • Is TNSACONFIG DISABLED specified?
  6. If you are using an hlq.HOSTS.SITEINFO file (or its z/OS® UNIX file system equivalent, /etc/hosts), you must ensure that the IP address in this file for the system on which the agent/subagent are executing matches an interface IP address of the TCP/IP stack to which the agent/subagent are connected. The interface IP addresses for a TCP/IP stack are defined on the HOME profile statement.
  7. Is the subagent using the correct IP address to send the connection request to the SNMP agent? The subagent uses the IPv4 primary interface IP address of this stack when sending the connection request to the SNMP agent. The IPv4 primary interface IP address is either the first IP address in the HOME list or the IP address specified on a PRIMARYINTERFACE TCP/IP profile statement. Check the Netstat HOME/-h output to verify the IPv4 primary interface address of the stack. This IP address is the one that is used by the SNMP agent, along with the community name to verify the subagents authority to connect to the SNMP agent.
  8. Is the port number correct?
  9. Is the community name (or password) correct?
    Guideline: Community name is a mixed-case, case-sensitive field. Many times the client cannot get a response from an agent because the agent has a community string of PUBLIC. Most clients default their community string to public.
  10. If the SNMP agent is configured for SNMPv3, is the community name configured in the agent SNMPD.CONF file? The subagent can use the community name only if VACM_GROUP, VACM_VIEW, and VACM_ACCESS are defined. For the subagent to connect, the VACM_VIEW must include the dpiPort objects.
  11. Did any socket-related errors occur?

    Check the SNMP agent/subagent syslogd for socket(), bind(), accept(), or other socket error messages, particularly error messages related to the DPI connection.

  12. If the subagent is using TCP to connect to the SNMP agent then the connection could have been closed by the agent due to a security authorization failure. If the agent security resource name has been defined in the SERVAUTH class, then the subagent must be running on the same TCP/IP stack as the agent and the user ID of the subagent must be permitted to the resource name in order for the connection to succeed. See the SNMP information of the z/OS Communications Server: IP Configuration Guide for a description of the agent security resource name used with TCP connections between SNMP agent and subagent.
If the problem still occurs after checking the preceding items and making any needed changes, obtain the following documentation:
  • SNMP agent 255 (trace all) output.
  • If the problem is with the TCP/IP subagent, get the subagent traces (level 2). These are turned on by specifying the ITRACE statement in the PROFILE.TCPIP file. This can be done as part of the initial TCP/IP startup. It can also be done after TCP/IP has been started by using the VARY TCPIP command, which is documented in the z/OS Communications Server: IP System Administrator's Commands.
  • If the problem is with the OMPROUTE subagent, get the OMPROUTE subagent traces. Turn these on by starting OMPROUTE with the -s1 option or by issuing the MODIFY SADEBUG command to start OMPROUTE subagent tracing.
  • If the problem is with the Network SLAPM2 subagent, get the Network SLAPM2 subagent traces. Turn these on by starting the Network SLAPM2 subagent with the -d 131 option or by issuing the MODIFY DEBUG,LEVEL command to start Network SLAPM2 subagent tracing.
  • If the problem is with a user-written subagent program, use the DPIdebug() DPI library routine to collect dpi traces in the user-written subagent program. DPIdebug() sends output to the syslogd.
  • If the problem is with the TN3270E Telnet subagent, get the subagent traces. These are turned on by specifying the TNSATRACE keyword on the TNSACONFIG statement in the PROFILE.TCPIP file. This can be done as part of the initial TCP/IP startup. It can also be done after TCP/IP has been started by using the VARY TCPIP,,OBEYFILE command, which is documented in the z/OS Communications Server: IP System Administrator's Commands. To enable tracing using the VARY TCPIP,,OBEYFILE command, the subagent must first be disabled and then re-enabled with the TNSATRACE keyword.
The following is a list of things to look for in the SNMP agent trace:
  • One of the following incoming SNMP GetRequest-PDU:
    • dpiPortForTcp (1.3.6.1.4.1.2.2.1.1.1) for TCP connect. This is caused by DPIconnect_to_agent_TCP
    • dpiPathNameForUnixStream (1.3.6.1.4.1.2.2.1.1.3) for UNIX connect. This is caused by DPIconnect_to_agent_UNIXstream.
      Some questions to consider:
      • Was the GetRequest-PDU received? If the GetRequest was not received, was it sent to the right port?

        In the case of the TCP/IP subagent, the value of the AGENT keyword on the SACONFIG statement in the profile must match the value of -p that was specified (or defaulted) when the agent was invoked.

      • Does it have a valid community name in the request?
        • SNMP subagents must use a valid (including correct case) community name as defined in the PW.SRC data set (or SNMPD.CONF data set when using SNMPv3 security) when requesting the dpiPort or dpiPath variable.
        • Note that community name is a mixed-case, case-sensitive field. Specify as follows:
          • For the TCP/IP subagent, specify the community name in the SACONFIG statement.
          • For the OMPROUTE subagent, specify the community name in the ROUTESA_CONFIG statement.
          • For the Network SLAPM2 subagent, specify the community name by way of the -c parameter.
      • For the TN3270E Telnet subagent, specify the community name on the TNSACONFIG statement.
      • If SNMPv3 is being used, the community name must be defined in the VACM_GROUP statement in the SNMPD.CONF file for the SNMP agent. A VACM_ACCESS statement also needs to be defined to give that group read access to a VACM_VIEW that includes dpiPort objects.
      • dpiPathNameForUnixStream defaults to /var/dpi_socket and provides a z/OS UNIX file system pathname used in connecting a DPI subagent with the SNMP agent. The default can be overridden by using the -s parameter when starting the agent or by adding an entry for dpiPathNameForUnixStream in the OSNMPD.DATA file.

        A user-written subagent running from a nonprivileged user ID needs write access to the file. Otherwise, a subagent using DPIconnect_to_agent_UNIXstream() would have to be run from an OMVS superuser user ID or other user ID with the appropriate privilege.

  • Outgoing GetResponse-PDU for the dpiPort variable:
    • Was the SNMP GetResponse-PDU sent back to the SNMP subagent?
    • Was it sent to the correct IP address?
    • Did it have the correct value for the DPI port?
      • The actual value for the DPI port for TCP can be determined by issuing a Netstat ALL/-A command at the SNMP agent. This displays the port on which the agent is accepting incoming UDP requests.
      • To display the dpiPath name, issue an osnmp get request for dpiPathNameForUnixStream.
  • One of the following incoming subagent connections:
    • Message EZZ6244I Accepted new DPI inet subagent connection on fd fd=xx from inet address xxxx port xxxx.
    • EZZ6246I Accepted new DPI inet socket connection on fd=xx
    Note: fd=xx is the number associated with this specific subagent connection. Use it to correlate with later DPI trace messages. The name and number of the port xxxxx port xxxx.
  • DPI packets transferred for this FD number
The following documentation might also be needed in some cases, but it is suggested that the IBM® Software Support Center be contacted before this documentation is obtained:
  • Dump of SNMP agent address space
  • Dump of TCP/IP address space (for TCP/IP and TN3270E Telnet subagent problems)
  • Dump of OMPROUTE address space (for OMPROUTE subagent problems)
  • Dump of Network SLAPM2 subagent address space (for Network SLAPM2 subagent problems)
  • Dump of user SNMP subagent address space
  • Trace from subagent in syslogd

Information about obtaining a dump can be found in z/OS MVS Diagnosis: Tools and Service Aids. Obtaining SNMP agent traces is discussed in Starting SNMP agent traces.

Parent topic: Problems connecting subagents to the SNMP agent