|C H A P T E R 3|
Getting Started With Netra CT Element Management Agent API
This chapter explains how to get started writing applications that interface with the Netra CT element management agent, using the Java Management Extensions (JMX) compatible Java API supported by the Netra CT management agent. The chapter consists of:
You should become acquainted with the topology of the Netra CT server (see Chapter 2), and have some knowledge of Java programming, JMX specifications, and JDMK framework. For more information about JDMK refer to Java Dynamic Management Kit 4.2 Tutorial (806-6633), or go to http://java.sun.com/docs/books/tutorial/index.html.
Verify that you have the Solaris OS on your development system. In addition, you can download the required Netra CT patch packages from:
These packages consist of:
You will use these installed packages to work with this tutorial.
The Netra CT server software package includes various modules and extensions (see Operating System Specifics), and the netract agent is one of these.
The netract agent, when appropriately invoked, provides configuration monitoring and fault monitoring. This enables you to investigate the installed system, and to determine whether the components are running smoothly.
Individual netract agents run on the alarm card, the host CPU board, and any satellite CPU board. A management application must be able to talk to the different agents and gather information about the system into a database.
Each netract agent notifies the management application of any changes, such as hardware or software configuration changes, and also detects faults when they occur.
The netract agent provides two different interfaces for the management applications, one is SNMP version 2C interface, the other is a JMX-compatible Java API called Netra CT management agent API. This chapter provides an introduction on how to write a management application using this Java API.
For JMX/JDMK/RMI connectivity, the Netra CT agent provides security by authenticating the application connecting to it via the context of a valid username and password pair.
The username and password must be previously created in the Alarm Card database via Alarm Card CLI. An account on Alarm card consists of username, password and permission. For Netra CT agent, there are only two permissions: read-only and read-write. User account on Alarm Card must have ALL PRIVILEDGES ENABLED to have read-write permission. (See the Netra CT Server System Administration Guide for details on setting up user accounts.)
There is a security flag used to enable and disable the Security Feature. This flag is stored persistently and its default value is false. The security flag can be set to true or false via Alarm Card CLI command setmohsecurity. A reset of Alarm Card is required after changing the flag for the feature to take effect. (See the Netra CT Server System Administration Guide for information on the setmohsecurity and showmohsecurity CLI commands).
You can get the state of security flag with the Alarm Card CLI command showmohsecurity or with the API by using the NEMBean's getSecurityFlag method described in NEMBean.
If the flag is true, security is on. This means the application that connects to Netra CT agent must provide a valid username and password to be able to establish connection.
If the flag is false, security is off and no authentication is done. It does not matter whether an application provides username, password or not, it is always allowed to connect.
Sample code with Netra CT Security is shown CODE EXAMPLE 3-1.
Creating an application to interface with and manage the configuration of the Netra CT server involves a series of steps. You must be able to:
1. Cut and paste the relevant code example into a text editor, make any necessary adjustments, and compile the code.
Make sure that SUNW2jdtk is installed before trying to compile Client.java. Refer to the Java Dynamic Management Kit 4.2 Tutorial for background information on Client.java.
2. To compile Client.java, issue the command /usr/j2se/bin/javac -classpath:
Compiling Client.java should produce the file Client.class. If you have difficulty, refer to the Java Tutorial example of running a simple client.
3. Before running Client.java, start the agent by issuing the command/opt/SUNWnetract/mgmt2.0/bin/ctmgx start
4. Use the following command to run Client.java:
The following sections point out various features of the Netra CT element management API.
First, a management application needs to know how the system is configured. The simplest example sets up an agent describing the hardware containment hierarchy. From the root of this tree, the management tree can be developed to show, for example, how many fans there are, which cards are in which slots and so on. Developing code that begins this action is the purpose of Determining the System Configuration Hierarchy.
Listening for Notifications deals with developing a way of monitoring notifications such as power on and power off to a particular slot or device.
Managing Alarms covers alarm management: how to handle the receiving and transmitting of system alarms such as CPU over-temperature alarm.
Software Monitoring shows how to get a list of running software services and daemons, so they can be registered to receive notice of events.
In this section you develop a client to print out the object names of the MBeans representing the system. A complete description of Mbeans, together with examples, can be found in the JDMK documentation.
1. Ensure you have the appropriate software installed on the development system for the application you intend to develop.
Refer to the Netra CT Server System Administration Guide if you need help in installing the appropriate software.
2. Go to: /opt/SUNWnetract/mgmt2.0/docs/api to find the documentation that identifies the pieces you need to communicate with the netract agent.
See the API documentation for:
For JDMK documentation, go to: /opt/SUNWjdmk/jdmk4.2/1.2/docs. For an introduction to JDMK, go to //docs.sun.com, and search for the Java Dynamic Management Kit 4.2 Tutorial.
See the API documentation for:
This simple demonstration lets you connect a client with an instance of netract agent, beginning in CODE EXAMPLE 3-2. This example represents part one of a three-part example. A detailed explanation follows.
CODE EXAMPLE 3-2 instantiates the RmiConnectorClient and RmiConnectorAddress.
The demonstration continues in CODE EXAMPLE 3-3.
CODE EXAMPLE 3-3 continues from the previous example. The code example connects to the client and prints the ContainmentTree by getting the ObjectName of the root MBean in the containment hierarchy.
Each MohNames instance comes up with ObjectNames instances that are accessible via public static fields defined in MohNames. This includes the ContainmentTreeMBean instance, which provides a mechanism for the user to traverse the containment hierarchy representing the Netra CT system.
This demonstration returns the object name of the instance of NEMBean. NEMBean is the name of the network element MBean representing the system as a whole, in other words, the root of the tree.
Now that you have identified the ObjectName of the root of the MOH_CONTAINMENT_TREE you are ready to traverse the tree and find out what other elements are in the tree.
Continuing the demonstration from the previous example, in CODE EXAMPLE 3-4 you traverse the MOH_CONTAINMENT_TREE from a node, and can get a list of all the nodes on the tree using getChildren.
Here, the nodeName is the ObjectName of the MBean where the search should start from. The line beginning Set children gets the children of the specified MBean in the containment hierarchy.
Once you have established the hierarchy of the existing system, your application must receive notification when changes to the system occur. This is the subject of the following section.
This series of examples assumes you continue from the previous three-part example. Return to /opt/SUNWnetract/mgmt2.0/docs/api to find documentation.
In the JDMK framework, look at:
In MOH documentation you need to look at: com.sun.ctmgx.moh.MohNames and com.sun.ctmgx.moh.Moh.EFDMBean.
This example continues from the previous examples and shows you how to register a NotificationListener using a NotificationFilter.You begin by adding a NotificationListener that catches communications from the RmiConnectorClient.
CODE EXAMPLE 3-5 establishes that MohNames can access MOH_DEFAULT_EFD. The EFDMBean exposes the remote management interface of an event forwarding discriminator managed object.
The netract agent of the Netra CT alarm card does not support the PUSH_MODE, so the above code will work for any of the netract agent instances (those on the host, satellite, and alarm card) in a Netra CT drawer.
Before you begin this segment of code example, you should refer back to: /opt/SUNWnetract/mgmt2.0/docs/api
Look at the MOH documentation for:
In this section you identify the kinds of alarms the script listens for when events occur. You can specify the level of action; this example listens for critical or major alarms. AlarmNotification represents an alarm notification emitted by an MBean.
CODE EXAMPLE 3-6 follows the form of the previous example in setting the RmiConnectorClient to PULL_MODE. The alarm filter is set to enableAllAlarmTypes, then refined to enable only AlarmSeverity.CRITICAL and AlarmSeverity.MAJOR.
Each netract agent instance comes up with a default instance of AlarmSeverityProfile which can be accessed by its object name, MohNames.MOH_DEFAULT_ASP. The MBean instances that might generate AlarmNotifications will have this default alarm severity profile associated with them. The user can associate a new profile to any of those MBeans at any time.
In CODE EXAMPLE 3-7, the severity level of HIGH.TEMPERATURE AlarmType in the default alarm severity profile has been set to CRITICAL. The following example shows how to create your own alarm severity profile instances.
You can create your own alarm severity profile by following CODE EXAMPLE 3-8.
CODE EXAMPLE 3-8 assigns alarm notifications for high memory usage, fan failure, and fuse failure, although the current netract agent does not support alarm notifications for fuse failure. The code example is included here for demonstration purposes.
CODE EXAMPLE 3-9 shows how to assign a new alarm severity profile to an MBean which can generate AlarmNotifications.
The new alarm severity profile can be reserved to replace the default profile when required.
The system configuration hierarchy indicates the physical alarm port which corresponds to a termination point, as shown in Hardware Resource Hierarchy Showing Managed Object Classes and subsequent views. The alarm port termination point supports five alarm interfaces: three for output, two for input. In general, when an alarm occurs, the corresponding output alarm pin is driven high based on the alarm severity.
The output alarm pins (alarm0, alarm1, alarm2) are statically mapped into severities of critical, major, and minor respectively.
For example, assume that HIGH_TEMPERATURE is assigned as critical, and HIGH_MEMORY_UTILIZATION is assigned as minor. When a high temperature occurs, alarm0 is driven high to indicate a critical alarm. When a HIGH_MEMORY_UTILIZATION occurs, alarm2 is driven high to indicate a minor alarm.
In JMX, an alarm is defined as a notification with a severity associated with it. These alarms are assigned as NetworkInterfaceMBeans, each of which represent a network interface object in the system. Refer to NetworkInterfaceMBean.
You can configure an alarm card agent to drive output alarms from the alarm card on the Netra CT server using MOH as described in the following section.
The following steps show how to configure an agent from the alarm card to correspond with the mapping in TABLE 3-2.
1. Register a notification listener with an AlarmNotificationFilter.
Use the examples beginning Registering a Notification Listener With an Alarm Notification Filter, and modify the default to listen for critical or major alarms. Return to the start of this chapter for help in getting an ObjectName.
2. Develop an AlarmSeverityProfile based on the default profile.
An AlarmSeverityProfile (ASP) contains multiple entries, and can be assigned to several alarm-generating objects. Some entries in the profile might not be used by an object, because that object might not be generating that specific kind of alarm. The default instance of AlarmSeverityProfile can be accessed by its object name, MohNames.MOH_DEFAULT_ASP.
3. Assign the AlarmSeverityProfile to the corresponding objects.
In CODE EXAMPLE 3-10 extracted from Using the Default Alarm Severity Profile, the severity level of HIGH.TEMPERATURE AlarmType in the default ASP has been set to CRITICAL corresponding with alarm0.
Any number of objects are capable of generating an alarm. If you assign this profile to a particular object, whenever a hardware failure of that object occurs, the netract agent refers to the profile and responds as you have specified.
CODE EXAMPLE 3-11 creates your own alarm severity profile instances based on these examples. In this case, the sensorObjectName is the object name of a temperature sensor MBean instance.
The new alarm severity profile replaces the default profile when required.
You can create several alarm severity profiles, each specifying a different response. One might designate fan failure as critical, another might designate high temperature as major. You then assign the appropriate profile to the object.
Alarms are cleared automatically when each alarm relay is driven low. OperationalState will accordingly be shown to be enabled, disabled or unknown.
The following code examples help monitor software events. The series begins in CODE EXAMPLE 3-12 with establishing the printService to print system status reports, then gathers the list of software services and their associated daemons.
CODE EXAMPLE 3-12 builds on previous examples to establish the status of connectorClient, and examine the hierarchy of the swServiceList in order to find existing services and running daemons.
The following segment of code collects the attributes of each software service so that the service can be registered to receive event notification.
CODE EXAMPLE 3-13 traverses swServiceList and adds NotificationListener to the connectorClient.
The final code segment gets the list of daemons that support the service, and prints out the daemon attributes for event notification.
CODE EXAMPLE 3-14 establishes a DaemonList for each service and prints out the attributes of each daemon. Finally, the code registers these daemons to receive notice of events with addNotificationListener.
For further information, look at /opt/SUNWnetract/mgmt2.0/docs/api which details all the MOH interfaces and classes that are provided for the Netra CT system software.