Xmlrpcd configuration
Subscribe

From OpenNMS

Jump to: navigation, search

Contents

XMLRPCD Configuration

Note: This functionality is described in Bug #1487 but it has yet to be applied to the code base.

The existing xmlrpcd implementation exported 6 specific events:

  • Service Up
  • Service Down
  • Node Up
  • Node Down
  • Interface Up
  • Interface Down

It would export these events (or fewer if the config file did not list the UEIs for all these events) via six specific XMLRPC method calls. It would export them to a single XMLRPC server. If more than one server was listed in the xmlrpcd-configuration.xml, it would treat them as serially redundant -- ie., one was the primary server and the others were used as backups. It would connect to the first one to which it could establish an XMLRPC connection, and would only connect another if it lost its first connection.

With the new modification, xmlrpcd can export any event to any number of XMLRPC servers simultaneously. Groups of events can be named, and each server can subscribe to a list of named groups.

Sample configuration 

<?xml version="1.0"?>
<xmlrpcd-configuration max-event-queue-size="5000" generic-msgs="true">
        <external-servers retries="3" elapse-time="15000">
                <xmlrpc-server url="http://localhost:9000" />
                <xmlrpc-server url="http://localhost:10000" />
                <serverSubscription>baseEvents</serverSubscription>
                <serverSubscription>extraEvents</serverSubscription>
        </external-servers>
        <external-servers retries="3" elapse-time="15000">
                <xmlrpc-server url="http://localhost:7000" />
                <serverSubscription>baseEvents</serverSubscription>
                <serverSubscription>extraEvents</serverSubscription>
        </external-servers>
        <subscription name="baseEvents">
                <subscribed-event uei="uei.opennms.org/nodes/nodeLostService"/>
                <subscribed-event uei="uei.opennms.org/nodes/nodeRegainedService"/>
                <subscribed-event uei="uei.opennms.org/nodes/nodeUp"/>
                <subscribed-event uei="uei.opennms.org/nodes/nodeDown"/>
                <subscribed-event uei="uei.opennms.org/nodes/interfaceUp"/>
                <subscribed-event uei="uei.opennms.org/nodes/interfaceDown"/>
                <subscribed-event uei="uei.opennms.org/internal/capsd/updateServer"/>
                <subscribed-event uei="uei.opennms.org/internal/capsd/updateService"/>
                <subscribed-event uei="uei.opennms.org/internal/capsd/xmlrpcNotification"/>
	</subscription>
	<subscription name="extraEvents">
                <subscribed-event uei="uei.opennms.org/internal/capsd/forceRescan"/>
                <subscribed-event uei="uei.opennms.org/nodes/nodeGainedService"/> 
                <subscribed-event uei="uei.opennms.org/nodes/nodeGainedInterface"/>
                <subscribed-event uei="uei.opennms.org/generic/traps/EnterpriseDefault"/>
                <subscribed-event uei="uei.opennms.org/generic/traps/SNMP_Link_Down"/>
                <subscribed-event uei="uei.opennms.org/generic/traps/SNMP_Link_Up"/>
        </subscription>
</xmlrpcd-configuration>

Configuration elements and attributes

  • max-event-queue-size attribute -- the size of the event queue per server
  • generic-msgs attribute (new) -- true to disable the old event-specific XMLRPC calls and enable the new generic calls (sendEvent and sendTrap), false for backward-comptability (defaults to false)
  • external-servers element (changed) -- An XMLRPC server (or list of serially-redundant XMLRPC servers) and the names of the event groups to which it subscribes. By configuring just one of these elements and listing multiple servers in it, you can be backwards compatible with the previous mode of xmlrpcd implementation -- one list of serially-redundant servers, and one list of UEIs.
  • xmlrpc-server element -- the URI of an XMLRPC server that's part of a external-servers element
  • serverSubscription element (new) -- the name of a group of events subscribed to by the servers in a external-servers element
  • retries attribute -- number of retries to connect to a server
  • elapse-time attribute -- amount of time between retries
  • subscription element (modified) -- a group of events that can be subscribed to by name in a serverSubscription element
  • subscribed-event element -- the UEI of an event that's part of a subscription element

Operation

When xmlrpcd initializes, it creates a separate EventListener and message queue for each listening XMLRPC server. When a subscribed event is received by one of the EventListeners, it queues it for future processing. When the event is processed, xmlrpcd checks the generic-msgs attribute. If it's false, then xmlrpcd sends the event to the listening server only if it's one of the supported six events, and does so using one of the following XMLRPC calls:

  • sendServiceUpEvent
  • sendServiceDownEvent
  • sendNodeUpEvent
  • sendNodeDownEvent
  • sendInterfaceUpEvent
  • sendInterfaceDownEvent

These calls must be received using a default handler at the XMLRPC server, because they do not use the object.method nomenclature expected by specific XMLRPC handlers.

If the generic-msgs attribute is true, then generic message export is enabled. Any OpenNMS event that's subscribed in the configuration file will be exported. If it's a trap, it will be converted to a sendTrap XMLRPC call. If it's some other event, it will be converted to a sendEvent XMLRPC call. These calls also expect a default XMLRPC handler.


XMLRPC server implementation

The code snippet below is an example of the key code necessary to set up an XMLRPC web server and listen for generic events using the Apache XMLRPC server package and its XMLRPC-specific web server. 


import org.apache.xmlrpc.*;

   '''initialization:'''
        m_webServer = new WebServer(port);
        m_webServer.addHandler("$default", this);  // configure a default handler
        m_webServer.start();
    

    /**************************************************************************/
    /**
     *  Stop listening for OpenNMS events.
     *
     */
    public void OpenNmsEventListener()
    {
        m_webServer.shutdown();
    }


    /**************************************************************************/
    /**
     *  Execute the received XMLRPC method
     *
     */
    public Object execute(String method, Vector params)
    {
        if (method.equals("sendSnmpTrapEvent"))
        {
            // handle trap here
        }
        else if (method.equals("notifyReceiveEvent"))
        {
            // handle receive notification
        }
        else if (!method.equals("sendEvent"))
        {
            // handle non-trap event
        }
    
        return(params);
    }

Version History/Availability

Retrieved from "http://www.opennms.org/wiki/Xmlrpcd_configuration"