DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 
Developing SMUX peers for SNMP agents

How the SMUX protocol works

As shown in the preceding example, the SMUX protocol is fairly simple. As you might suspect, there are some refinements to the basic sequence of events described above. Let's take a closer look at the details of initialization, information exchange, and termination.

Initialization

The SNMP agent listens for SNMP messages from SNMP clients on UDP port 161. The agent also listens on TCP port 199 for connection requests from SMUX peers. When an SMUX peer starts running, it calls a routine which initiates a TCP connection with the agent. Once the TCP connection is established, the peer initializes the SMUX association by sending a Protocol Data Unit (PDU) message called an OpenPDU to the agent.

The SNMP agent checks authentication information in the OpenPDU against that contained in the configuration file /etc/netmgt/snmpd.peers. This file lists all SMUX peers known to the agent, passwords for each, and (optionally) maximum allowable priority for each (refer to ``Priority'' for more information about this parameter). If for any reason the agent refuses the association with this SMUX peer, the agent sends the peer a ClosePDU and closes the TCP connection. Otherwise, the agent accepts this association and no response PDU is sent back to the peer.

Registration

Once the SMUX association has been established, the peer registers the MIB module it wishes to manage by sending a RReqPDU to the agent. The agent responds by returning a RRspPDU. The peer must issue a separate RReqPDU for each MIB module it wants to manage; the agent accepts or declines the requests by sending the appropriate RRspPDUs in the same order as it received the RReqPDUs from the peer.

Priority

What happens when more than one SMUX peer attempts to register the same MIB module? The SMUX protocol has a priority mechanism built in to handle these cases.

Each peer registration has associated with it an integer priority value in the range 0 to the maximum value of a 32-bit signed long integer, (2^31-1). A registration with a priority value of zero is given the highest possible priority and (2^31-1) the lowest. The highest allowed priority for each peer is specified in the agent's /etc/netmgt/snmpd.peers file. If a peer attempts to register at a priority higher than allowed, the agent arbitrarily assigns that registration a priority at or below the priority specified in /etc/netmgt/snmpd.peers. More than one peer can register the same MIB module, but the peer with the highest registration priority handles all management station requests for variables in that module. When a peer wishes to register a MIB module at a priority which has already been assigned to another SMUX peer, the agent continues to increment the priority value of the registration request until it finds an available priority value for that module. For example, if peer A has registered the module at priority 4, and peer B sends a registration request for the same module at priority 4, the agent will attempt to register the module to peer B at priority 5, and then 6, and so on until the agent finds an available priority for that module.

And what happens when a peer attempts to register a MIB module which encompasses a MIB module already registered by another SMUX peer? When peer B registers a MIB module which encompasses the module registered by peer A, peer B assumes responsibility for managing A's module as well.

RReqPDUs may have a special priority value of -1. When a peer uses this priority to register a MIB module, the agent assigns the highest available priority (that is, the lowest integer value available for that module) to that registration.

Information exchange

In the example SMUX session, the agent used the SNMP ``get'' operation to retrieve information from the peer. The agent can also use the SNMP ``set'' operation to write values to variables in the peer's MIB module. This topic takes a closer look at the get and set operations.

Agent gets data from peer

The sequence of events during the execution of an SNMP ``get'' or ``get-next'' operation is represented in ``An SNMP ``get'' or ``get-next'' operation''.

An SNMP ``get'' or ``get-next'' operation

When the SNMP client on the network management station issues a GetRequest or GetNextRequest PDU to the agent, the agent determines which MIB modules contain the variable(s) requested.

The agent processes each variable in turn, and issues a GetRequestPDU or GetNextRequestPDU to the appropriate SMUX peer for each variable.

Upon receiving the request PDU from the agent, the peer performs the specified operations and returns a GetResponsePDU to the agent. If the peer is unable to process the request, it returns an error code in the GetResponsePDU.

Then the agent collates the result contained in the response(s) and issues a GetResponsePDU to the network management station.

Agent sets peer data

The sequence of events for the execution of an SNMP ``set'' operation is represented in ``An SNMP ``set'' operation''.

An SNMP ``set'' operation

When the network management station user wishes to alter the value of one or more MIB variables, the SNMP client on the management station issues a SetRequestPDU for that variable to the agent. The agent processes each variable sequentially, determining which MIB modules contain the variable(s) in the request. For those variables in registered MIB modules, the agent sends a SetRequestPDU to the appropriate peer.

Because any peer may accept or refuse a set operation, carrying out a set operation is a two-phase process.

  1. Upon receiving the SetRequestPDU, the peer determines several things about each variable in turn: whether the variable exists, whether it permits writing, and that the request supplies correct values and syntax. If any variable in the request does not exist, or does not permit writing, or if a variable value is improper or if a variable's syntax is incorrect, the peer returns an appropriate error code in its GetResponsePDU to the agent.

    If the peer accepts the set operation, it issues a GetResponsePDU with error-status noError.

  2. If a peer refuses the set operation, it issues a GetResponsePDU with a non-zero error-status. The agent examines all the GetResponsePDUs from the SMUX peers. If any peer has refused the set operation, the agent issues a ``rollback'' SOutPDU to all peers saying, in effect: ``Never mind. Discard any knowledge of the requested set operation.''

    However, if all peers accepted the set operation, the agent issues a ``commit'' SOutPDU to all peers saying, in effect, ``Proceed with the set operation.''

The agent collates the responses from all peers involved in the SetRequest, and sends a GetResponsePDU back to the management station. Peers do not send response messages to the ``commit'' and ``rollback'' SOutPDUs.

Peer sends trap to agent

You will recall from ``Asynchronous events'' that a peer sends an unsolicited ``trap'' message to the agent when the peer detects an unusual event or condition. This trap message is sent in a TrapPDU; the sequence of events in this operation is represented in ``An SNMP ``trap'' operation''.

An SNMP ``trap'' operation

Up to this point, we have referred to traps sent to the agent by the peer; you should be aware that the agent also generates traps, which it sends to the network management station. The TrapPDU contains a generic-trap field which contains a value in the range zero to six, which corresponds to one the following extraordinary events or conditions:


coldStart (0)

This means the peer is initializing itself and objects it manages may be altered.

warmStart (1)

This means the peer is re-initializing itself, but the objects it manages are not altered.

linkDown (2)

This means an attached interface has changed from the ``up'' state to the ``down'' state.

linkUp (3)

This means an attached interface has changed from the ``down'' state to ``up''. This trap is not meaningful from the peer's perspective.

authenticationFailure (4)

This occurs when a PDU has been received from an SNMP entity which falsely claimed to belong to a specific community. This trap is not meaningful for peers, as they do not perform any authentication checking.

egpNeighborLoss (5)

This means an EGP (Exterior Gateway Protocol) peer has changed to the ``down'' state. This is not a meaningful trap for peers.

enterpriseSpecific (6)

This means the peer has noticed some enterprise-specific event has occurred. The specific-trap field of the PDU contains a value which indicates exactly which type of event this was. These values were defined as representing specific types of events by the programmer who implemented the peer.

Terminating an SMUX association

A ClosePDU is issued to end an SMUX association. This PDU removes all registrations for the peer and closes the TCP connection between the agent and the peer.

There are several possible reasons for the termination of an SMUX association between a peer and an agent:


goingDown

Either the peer or the agent is being brought down.

unsupportedVersion

The agent sends a ClosePDU, indicating a version mismatch.

packetFormat

The PDU received has been encoded incorrectly or was corrupted in transit, resulting in a decoding error.

protocolError

An incorrect sequence of PDUs, or an unexpected PDU was received.

internalError

A fatal error has occurred in the processing of a PDU.

authenticationFailure

The agent sends a ClosePDU, indicating that the ``OID-password'' pair in the OpenPDU did not match with any of those present in the local configuration file.
Termination can be initiated by either the peer or the agent except for unsupportedVersion and authenticationFailure type terminations; these types can only be initiated by the agent.

The SMUX peer removes its MIB module registrations before it terminates the SMUX association with the agent. A peer can only remove registration for the modules it registered. If the peer does not record the priority at which it registered a module, it can unregister the module with a priority -1; the agent removes that peer's highest priority registration for that module.

Subsequent requests from the management station for information contained in the now unregistered module are responded to by the SNMP agent. If the unregistered module has since been registered by another peer, the agent forwards the requests to that peer. If the agent is now managing the MIB module, the agent performs the requested operations. However, if the MIB module in question has not been registered to another peer and that module contains variables which are inaccessible to the agent, the agent sends a response PDU containing a noSuchName error code to the management station.


© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 27 April 2004