test

Java Dynamic Management Kit 5.1 Getting Started Guide

Chapter 2 Architectural Components

This chapter presents the components of the Java Dynamic Management Kit (Java DMK) and explains how you can use them in a complete management solution. Some features are implemented in a slightly different way for the deprecated legacy connectors. For further information on features specific to legacy connectors, see Chapter 4, Legacy Connectors and Related Features.

This chapter contains the following sections:

2.1 Instrumenting Resources as MBeans

The instrumentation level of the JMX specification defines standards for making resources manageable in the Java programming language. The instrumentation of a manageable resource is provided by one or more management beans, or MBeans. An MBean is a Java object that exposes attributes and operations for management. These attributes and operations enable any Java dynamic management agent to recognize and manage the MBean.

The design patterns for MBeans give the developer explicit control over how a resource, device, or application is managed. For example, attribute patterns enable you to distinguish between a read-only and a read-write property in an MBean. The set of all attributes and operations exposed to management through the design patterns is called the management interface of an MBean.

Any resource that you want to make accessible through an agent can be represented as an MBean. Both the agent application and remote managers can access MBeans in an agent. MBeans can generate notification events that are sent to all local or remote listeners. For more information about managing MBeans remotely, see 2.3 Communication Components.

You can make resources accessible through Java DMK agents even if they are not instrumented as MBeans, by using MBean Interceptors. See 2.6.1.4 Server authentication for details.

You can also download MBeans from a web server and plug them into an agent at any time, in response to a demand from the management application. This is called dynamic class loading and means that future services and applications can be loaded on the fly and without any downtime. For example, dynamic class loading can be used to provide rapid, low-cost delivery of end-user applications across very large bases of Java technology enabled devices, such as desktop PCs or Web phones.

There are four types of MBean:

2.1.1 Standard MBeans

Standard MBeans are Java objects that conform to certain design patterns that are derived from the JavaBeans component model. Standard MBeans allow you to define your management interface straightforwardly in a Java interface. The method names of this interface determine getters and setters for attributes and the names of operations. The class implementation of this interface contains the equivalent methods for reading and writing the MBean's attributes and for invoking its operations, respectively.

The management interface of a standard MBean is static, and this interface is exposed statically. Standard MBeans are static because the management interface is defined by the source code of the Java interface. Attribute and operation names are determined at compilation time and cannot be altered at runtime. Changes to the interface must be recompiled.

Standard MBeans are the quickest and easiest type of MBeans to implement. They are suited to creating MBeans for new manageable resources and for data structures that are defined in advance and that are unlikely to change often.

2.1.2 Dynamic MBeans

Dynamic MBeans do not have getter and setter methods for each attribute and operation. Instead, dynamic MBeans have generic methods for getting or setting an attribute by name, and for invoking operations by name. These methods are common to all dynamic MBeans and are defined by the DynamicMBean interface.

The management interface is determined by the set of attribute and operation names to which these methods respond. The getMBeanInfo method of the DynamicMBean interface must also return a data structure that describes the management interface. This metadata contains the attribute and operation names, their types, and the notifications that can be sent if the MBean is a broadcaster.

Dynamic MBeans provide a simple way to wrap existing Java objects that do not follow the design patterns for standard MBeans. You can also implement dynamic MBeans to access resources that are not based on Java technology by using the Java Native Interface (JNI).

The management interface of a dynamic MBean is static, but this interface is exposed dynamically when the MBean server calls its getMBeanInfo method. The implementation of a dynamic MBean can be complex, for example, if the MBean determines its own management interface based on existing conditions when it is instantiated.

2.1.3 Model MBeans

A model MBean is a generic, configurable, dynamic MBean that you can use to instrument a resource at runtime. A model MBean is an MBean template. The caller tells the model MBean what management interface to expose. The caller also determines how attributes and operations are implemented, by designating a target object on which attribute access and operation invocation are actually performed.

The model MBean implementation class is mandated by the JMX specification and therefore is always available for instantiation in an agent. Management applications can use model MBeans to instrument resources on the fly.

To instrument a resource and expose it dynamically, you need to:

The management interface of a model MBean is dynamic, and it is also exposed dynamically. The application that configures a model MBean can modify its management interface at any time. The application can also change its implementation by designating a new target object.

Management applications access all types of MBeans in the same manner, and most applications are not aware of the various MBean types. However, if a manager understands model MBeans, it can obtain additional management information about the managed resource. This information includes behavioral and runtime metadata that is specific to model MBeans.

2.1.4 Open MBeans

Open MBeans allow management applications and the users to understand and use new managed objects as the objects are discovered at runtime. These MBeans are called open because they rely on a small, predefined set of universal Java types and they advertise their functionality.

Management applications and open MBeans are thus able to share and use management data and operations at runtime without requiring the recompiling, reassembly, or expensive dynamic linking of management applications. In the same way, human operators can use the newly discovered managed object intelligently without having to consult additional documentation.

To provide its own description to management applications, an open MBean must be a dynamic MBean. Beyond the DynamicMBean interface, no corresponding open interface exists that must be implemented. Instead, an MBean earns its openness by providing a descriptively rich metadata and by using only certain predefined data types in its management interface.

An open MBean has attributes, operations, constructors, and possibly notifications like any other MBeans. An open MBean is a dynamic MBean with the same behavior and all of the same functionality. An open MBean also has the responsibility of providing its own description. However, all of the object types that the MBean manipulates, its attribute types, its operation parameters and return types, and its constructor parameters, must belong to a defined set of basic data types. It is the developer's responsibility to implement the open MBean fully by using these data types only.

An MBean indicates whether it is open or not through the MBeanInfo object it returns. Open MBeans return an OpenMBeanInfo interface. This interface is implemented by OpenMBeanInfoSupport, which inherits from MBeanInfo. If an MBean is marked as open in this manner, it is a guarantee that a management application compliant with the JMX specification can immediately make use of all attributes and operations without requiring additional classes.

Since open MBeans are also dynamic MBeans and they provide their own description, the MBean server does not check the accuracy of the OpenMBeanInfo object. The developer of an open MBean must guarantee that the management interface relies on the basic data types and provides a rich, human-readable description. As a rule, the description provided by the various parts of an open MBean must be suitable for displaying to a user through a graphical user interface (GUI).

2.2 The MBean Server

The MBean server is a registry for JMX manageable resources, which it exposes to management requests. The MBean server provides a protocol-independent and information model independent framework with services for manipulating JMX manageable resources.

If you choose to register a resource's MBean with the MBean server, the MBean becomes visible to management applications and is exposed to management requests. The MBean server makes no distinction between the types of MBeans. Standard, dynamic, model and open MBeans are managed in exactly the same manner.

You can register objects in the MBean server through the following.

The MBean server responds to the following management requests on registered MBeans.

The MBean server never provides the programmatic reference of its MBeans. The MBean server treats an MBean as an abstraction of a management entity, not as a programmatic object. All management requests are handled by the MBean server, which dispatches them to the appropriate MBean, thus ensuring the coherence in an agent.

An MBean is identified by a unique symbolic name, that is called its object name. The object name can be assigned either by the entity registering the MBean or by the MBean itself, if its implementation has been designed to provide one. Managers give this object name to designate the target of their management requests. Unless specified otherwise, object names are local to a specific MBean server. You can however make object names global if you want to implement the cascading service (see 2.5.5 Cascading).

It is possible to have multiple MBean servers within the same Java virtual machine, with each MBean server managing a set of resources.

2.3 Communication Components

Connectors and protocol adaptors interact with the Java communication objects such as sockets to establish connections and respond to requests from other host machines. Connectors and protocol adaptors enable agents to be accessed and be managed by remote management applications.

An agent can contain any number of connectors or protocol adaptors, enabling the agent to be managed simultaneously by several managers, through different protocols. The agent application is responsible for coordinating all the ports on which it intends to receive requests.

2.3.1 Connectors

Connectors establish a point-to-point connection between an agent and a management application, each running in a separate Java virtual machine.

A connector is composed of two parts:

Therefore, a Java application that instantiates a connector client can perform all management operations that are available through the agent's MBean server.

The Java DMK 5.1 provides the three standard connectors that are defined by the JMX Remote API 1.0 (JSR 160) specification. The standard connectors are based on RMI, RMI/IIOP, and JMX Messaging Protocol (JMXMP) which uses Java serialization over TCP.

The Java DMK 5.1 also provides connectors for the HTTP/TCP, HTTP/SSL, and RMI protocols. These “legacy” connectors were included in previous versions of the product, and are deprecated in version 5.1, now that standard connectors are available. Java DMK 5.1 provides a mechanism to wrap legacy connectors so that they can be created in the same way as the new connectors. Use of the legacy connectors is discouraged, although the use of the legacy HTTP(S) connector is acceptable as long as no native standard HTTP connectors are present.

Every standard connector provides the same remote API, which frees management applications from protocol dependencies. The API provided by standard connectors is similar to that provided by legacy connectors, but they are not interchangeable. In particular, the address format used by standard connectors is different from that used by legacy connectors.

The addresses of the new connectors are instances of the JMX Remote API interface JMXServiceURL. The address must adhere to the following syntax.


service:jmx:protocol:sap

Here, protocol is the transport protocol to be used to connect to the connector server, and sap is the address at which the connector server is found. The following is an example JMX service URL.


service:jmx:jmxmp://localhost:5555

In this example, the transport protocol is JMXMP and it is found at port 5555 of the local host. See the API documentation for the JmxServiceURL interface for more information about the syntax of these addresses.

2.3.1.1 RMI Connectors

The RMI connector is specified by the JMX Remote API. User code uses the same generic factories to create a client or server as it would to create any other kind of connector. Every connection to an RMI connector is implemented by means of a separate RMI object, which is destroyed when the connection is closed. Communication is always from client to server, even for notifications, which simplifies configuration and firewall use.

The RMI connector works over both JRMP, (the native Java transport for RMI) and IIOP. The same remote interfaces are used in both cases. Only the way in which these interfaces are exported differs. Because of class-loading issues, the RMI/IIOP connector cannot easily be used to interact with clients or servers that are not written in the Java language.

2.3.1.2 JMXMP Connectors

The JMX Remote API specifies an optional connector using a custom protocol called JMXMP, that is based on Java serialization running over TCP connections. JMXMP can optional use one or both of SSL and the Simple Authentication and Security Layer (SASL) for security.

Communication between a given client and the server happens over a single TCP connection. Every message is a serialized Java object. Coomunication is conceptually in two independent streams of messages, from client to server and from server to client. Thus, there can be many concurrent client requests over the connection at any given time. Replies do not have to arrive in the same order as the corresponding requests.

Notifications are handled in the same way as for the RMI connector. A message from client to server asks for notifications, and a reply message from server to client supplies them.

2.3.1.3 Monitoring Standard Connectors Using the Heartbeat Mechanism

All connectors provided in the Java DMK implement a heartbeat mechanism. This is true for both legacy connectors and the new standard connectors. This section outlines the heartbeat mechanism used for standard connectors. For information on the heartbeat mechanism used for legacy connectors, see 4.1.2 Monitoring Legacy Connectors Using the Heartbeat Mechanism.

The heartbeat mechanism monitors the connection between a manager and an agent, and automates the cleanup procedure when the connection is lost. This allows both the manager and the agent to free resources that were allocated for maintaining the connection.

The mechanism is entirely contained in the connector client and connector server components. No additional objects are involved. In addition, connector clients and servers send notifications that the manager application can receive to be aware of changes in the status of a connection.

The connector client generates a periodic heartbeat, by performing an innocuous operation on the server. If any beat fails because of a communication failure, the connection is considered to be dead. The server does not need to know that the heartbeat exists. The innocuous beat operations look like any other client operation.

Furthermore, client death is not detected by heartbeat. Instead, connectors are defined in such a way that there is no permanent client state on the server. Thus, the server can close client connections after a specified idle time. If the client is still alive, it will establish another connection. This is essentially an implicit lease mechanism.

2.3.1.4 Generating Proxies

Java DMK supports the notion of proxies. Proxies simplify the interactions between an application and the MBeans the application wants to manage. The purpose of a proxy is to invoke the methods that access the attributes and operations of an MBean, through its MBean server. The proxy performs the task of constructing the method calls at every invocation, on behalf of the caller:

Conceptually, a proxy instance makes the MBean server and, optionally, a protocol connector completely transparent. With the exception of MBean registration and connector connection phases, all management requests on MBeans can be fully served through proxies, with identical results, apart from some details concerning exceptions. However, all functionality of the Java DMK is available without using proxies, so their use is never mandatory.

Figure 2–1 shows management components interacting with an MBean through a proxy.

Figure 2–1 Binding Proxy MBeans to Local and Remote Servers

Binding proxy MBeans to Local and Remote Servers

Figure 2–1 also shows that proxies can be instantiated either locally in the agent or remotely in the manager. Since the MBean server and the connector client have the same API, management requests to either of them are identical. This creates a symmetry so that the same management components can be instantiated either in the agent or in the manager application. This feature contributes to the scalability of Java dynamic management applications.

In Java DMK 5.0, proxies were generated using the proxygen tool, supplied with Java DMK 5.1 but now deprecated. This tool is still needed if proxies are required for legacy connectors. However, Java DMK 5.1 provides a useful enchancement for generating proxies. Because Java DMK 5.1 is an implementation of JMX 1.2, you can generate a proxy object at runtime given just its Java interface, using the dynamic proxies provided with the J2SE platform (java.lang.reflect.Proxy). These proxies cannot be used with the legacy connectors.

2.3.2 MBean Server Interceptors

As stated previously, the Java DMK does not require every MBean in a Java DMK agent to be represented by a Java object in that agent. MBean Server interceptors enable you to intercept operations on MBeans and handle them arbitrarily. Handling the operations can involve handing the request to other interceptors, possibly after logging or authenticating them for security. Alternatively, handling can involve processing the request directly. For example, with very volatile MBeans, direct handling avoids having to keep up with the creation and deletion of objects. Instead, the managed object is effectively synthesized when there is a request on it, which for volatile objects happens much less often than creation and deletion.

Note –

In Java DMK version 5.1, it is necessary to use the new JdmkMBeanServerBuilder class to add interceptor functionality. This can be done by specifying a Java system property. See the Java Dynamic Management Kit 5.1 Tutorial for details.

2.3.3 Protocol Adaptors

Protocol adaptors have only a server component and provide a view of an agent and its MBeans through a different protocol. Protocol adaptors can also translate requests that are formulated in this protocol into management requests on the JMX agent. The view of the agent and the range of possible requests depends upon the given protocol.

For example, Java DMK provides an HTML adaptor that presents the agent and its MBeans as HTML pages that are viewable in any web browser. Because the HTML protocol is text based, only data types that have a string representation can be viewed through the HTML adaptor. However, this is sufficient to access most MBeans, view their attributes, and invoke their operations.

Due to limitations of the chosen protocol, adaptors have the following limitations.

The SNMP adaptor provided in the Java DMK is limited by the constraints of SNMP. The richness of the JMX architecture cannot be translated into SNMP, but all the operations of SNMP can be imitated by methods of the MBean server. This translation requires a structure of MBeans that imitates the MIB. While an SNMP manager cannot access the full potential of the JMX agent, the MBeans representing the MIB are available for other managers to access and incorporate into their management systems.

In general, a protocol adaptor tries to map the elements of the JMX architecture into the structures provided by the given protocol. However, the completeness or accuracy of this mapping is not guaranteed.

2.4 The Notification Model

The JMX architecture defines a notification model that enables MBeans to broadcast notifications. Management applications and other objects register as listeners with the broadcaster MBean. In this way, MBeans can signal asynchronous events to any interested parties.

The JMX notification model enables a listener to register only once and still receive all the various notifications that an MBean can broadcast. A listener object can also register with any number of broadcasters, but it must then sort all notifications it receives according to their source.

2.4.1 Local Notification Listeners

In the simplest case, listeners are objects in the same application as the broadcaster MBean. The listener is registered by calling the addNotificationListener method on the MBean. The MBean server exposes the same method so that listeners can also be added to an MBean identified by its symbolic name.

In Figure 2–2, one listener has registered directly with the MBean and another has registered through the MBean server. The end result is the same, and both listeners receive the same notifications directly from the broadcaster MBean.

Figure 2–2 Adding Local Listeners on the Agent Side

Adding Local Listeners on the Agent Side

2.4.2 Remote Notification Listeners

The connector client interface also exposes the addNotificationListener method so that notifications can be received in remote management applications. Standard proxies expose this method as well and transmit any listener registrations through the connector client.

Listeners do not need to be aware that they are remote. The connector transmits registration requests and forwards notifications back to the listeners. The whole process is transparent to the listener and to the management components.

As shown in Figure 2–3, the connector components implement a complex mechanism for registering remote listeners and forwarding notifications. Because notifications are based on the Java event model, broadcasters cannot send notifications outside their Java virtual machine. So, the connector server instantiates local listeners that receive all notifications and places them in a cache buffer, to wait to be sent to the manager application. This enables the connector to avoid saturating the communication layer in case of a burst of notifications.

Figure 2–3 Adding Remote Listeners on the Manager Side

Adding Remote Listeners on the Manager Side

Notifications in the new RMI and JMXMP connectors are pulled periodically at the client's request. The pull mechanism is used to group notifications and reduce bandwidth usage. The connector client acts as a broadcaster and sends the notifications to their intended listeners.

Notifications in the legacy RMI and HTTP connectors are pulled in the same way as the new connectors. However, the legacy connector notifications can also can be pushed from the agent to the connector client as they are received.

2.5 Agent Services

To simplify the development of agents for network, system, application, and service management, the Java DMK supplies a set of agent services. These services are implemented as MBeans that perform some operations on the other MBeans in an agent. All the provided agent services are briefly explained in this section.

2.5.1 Querying and Filtering

Querying and filtering are performed by the MBean server, not by a separate MBean. This ensures that such critical services are always available. Queries and filters are performed in a single operation, whose goal is to select the MBeans on which management operations are performed.

Usually, a management application performs a query to find the MBeans that are the target of its management requests. To select MBeans, applications can specify the following.

For example, a filter could select all the MBeans whose object names contain MyMBeans and for which the attribute named color is currently equal to red.

The result of a query operation is a list of MBean object names, which can then be used in other management requests.

2.5.2 Dynamic Loading

Dynamic class loading is performed by loading management applets or m-lets containing MBeans. This service loads classes from an arbitrary network location and creates the MBeans that they represent. The m-let service is defined by the JMX specification. The m-let service makes it possible to create dynamically extensible agents.

A management applet is an HTML-like tag called <MLET> that specifies information about the MBeans to be loaded. It resembles the <APPLET> tag, except that it loads only MBean classes. The tag contains information for downloading the class, such as the classname and the location of its class file. You can also specify any arguments to the constructor that is used to instantiate the MBean.

The m-let service loads a URL that identifies the file containing <MLET> tags, one for each MBean to be instantiated. The service uses a class loader to load the class files into the application's Java virtual machine. It then instantiates these classes and registers them as MBeans in the MBean server.

The m-let service is implemented as an MBean and instantiated and registered in the MBean server. Thus, the m-let service can be used either by other MBeans or by management applications. For example, an application could make new MBean classes available at a location, generate the m-let file, and instruct the m-let service in an agent to load the new MBeans.

Dynamic loading effectively pushes new functionality into agents, allowing management applications to deploy upgrades and to implement new resources in their agents.

2.5.3 Monitoring

The monitoring service complies with the JMX specification and provides a polling mechanism based on the value of MBean attributes. The monitoring service contains three monitor MBeans, one MBean for counter attributes, another MBean for gauge-like attributes, and a third MBean for strings. These monitors send notifications when the observed attribute meets certain conditions, mainly equaling or exceeding a threshold.

Monitor MBeans observe the variation of an MBean attribute's value over time. All monitors have a configurable granularity period that determines how often the attribute is polled. Each monitor has specific settings for the type of the observed attribute, as follows.

Monitor notifications contain the name of the observed MBean, the name of the observed attribute, and the value that triggered the event, as well as the previous value for comparison. This information allows listeners to know which MBean triggered an event. The listeners do not need to access the MBean before taking the appropriate action.

Monitor MBeans can also send notifications when certain error cases are encountered during an observation.

2.5.4 Scheduling

The timer service is a notification broadcaster that sends notifications at specific dates and times. The timer service provides a scheduling mechanism that can be used to trigger actions in the listeners. Timer notifications can be single events, repeated events, or indefinitely repeating events. The timer notifications are sent to all of the service's listeners when a timer event occurs.

The timer service manages a list of dated notifications, each of which has its own schedule. Users can add or remove scheduled notifications from this list at any time. When adding a notification, users provide its schedule, defined by the trigger date and repetition policy, and information that identifies the notification to its listeners. The timer service uses a single Java thread to trigger all notifications at their designated time.

You can stop the timer service to prevent it from sending notifications. When you start it again, notifications that could not be sent while the timer was stopped are either sent immediately or discarded, as determined by the configuration of the service.

Like all other agent services, the timer is implemented as an MBean so that it can be registered in an agent and configured by remote applications. However, the timer MBean can also be used as a stand-alone object in any application that needs a simple scheduling service.

For more information about the timer service, see the JMX specification document.

2.5.5 Cascading

Cascading is the term used to describe a hierarchy of agents, where management requests are passed from a master agent to one of its subagents. A master agent connects to other agents, possibly remotely, through their connector server components, much like a manager connects to an agent. In a set of cascading agents, all MBeans in a subagent are visible as if they are registered in their master agent. The master agent hides the physical location of subagents and provides client applications with a centralized access point.

In Java DMK 5.1, the cascading service is implemented over JMX Remote API connectors. The CascadingServiceMBean makes it possible to mount source MBean servers, that are possibly located in subagents, into a target MBean server, that is located in the master agent, in a manner that is somewhat analogous to a File System mount operation.

2.5.5.1 Object Names and Domain Paths

The Java DMK cascading API introduces the notion of a domain path. An ObjectName is thus decomposed into three parts, as follows.


domain-path/domain-base-name:key-property-list

The domain path is a hierarchical name similar to a File System path name, using the character `/' as a separator.

2.5.5.2 File System Analogy

The CascadingServiceMBean provided in the Java DMK 5.1 makes it possible to mount MBeans from a source MBean server under a target domain path in a target MBean server, in a similar way to a File System mount operation.

Although our API also allows you to implement different cascading schemes, we recommend that applications only implement those schemes that can be compared to a regular File System mount, as follows.

Our implementation does not enforce those rules, but applications which are concerned with naming consistency and coherency should make sure to respect them. See the package description in the API documentation for the com.sun.jdmk.remote.cascading package for details.

2.5.5.3 CascadingServiceMBean

The cascading service proposed in the com.sun.jdmk.remote.cascading package is based on a simple MBean class, the CascadingServiceMBean.

The default CascadingService implementation provided in the Java DMK 5.1 relies on proxy-based cascading and implements the mount operation by instantiating a ProxyCascadingAgent behind the scenes. Although the ProxyCascadingAgent offers a public API, you should not use it directly. Applications should use the CascadingServiceMBean instead.

CascadingServiceMBeans are also notification emitters, which emit notifications when mountpoints are unmounted, as a result of a an unmount operation, or because the underlying connection with the source MBean server has been closed or failed.

2.5.5.4 Cascading over Java DMK legacy connectors

There are two possibilities to implement cascading over Java DMK legacy connectors.

2.5.6 Discovering Agents

You can use the discovery service to discover Java dynamic management agents in a network. Only agents that have a discovery responder registered in their MBean server can be discovered when you use this service.

The discovery service for legacy connectors can be functionally divided into two parts:

2.5.7 Discovery Search Service

In a discovery search operation, the discovery client sends a discovery request to a multicast group and waits for responses. To be found by the discovery service, the agents must have a DiscoveryResponder registered in their MBean server. All discovery responders that receive the discovery request send a response that contains information about the connectors and the protocol adaptor that are available in their agent.

Figure 2–4 The Discovery Search Service

The Discovery Search Service

A manager application might use the discovery search service during its initialization phase, to determine all agents that are accessible in its network environment.

2.5.8 Discovery Support Service

The discovery support service passively monitors discovery responders in a multicast group. When discovery responders are activated or deactivated, indicating that their agent is starting or stopping, they send a multicast message about their new state. A discovery monitor object listens for discovery responder objects starting or stopping in the multicast group.

By registering listeners with the discovery monitor, a management application knows when agents become available or unavailable. The discovery support message for an agent that is being started also lists its connector and protocol adaptor.

A management application can use the discovery monitor to maintain a list of active agents and the protocols they support.

2.5.9 Defining Relations

The Relation Service is used to record relationships between MBeans in an MBean server. The Relation Service is itself an MBean. More than one instance of a Relation Service MBean can be registered in an MBean server.

A relation type defines a relationship between MBeans. A relation type contains roles that the MBeans play in the relationship. Usually, there are at least two roles in a relation type.

A relation is a named instance of a relation type, where specific MBeans appear in the roles, represented by their object names.

For example, suppose Module MBeans represent the modules within an application. A DependsOn relation type could express the relationship that some modules depend on others, which could be used to determine the order in which the modules are started or stopped. The DependsOn relation type would have two roles, dependent and dependedOn.

Every role is typed, meaning that an MBean that appears in that role must be an instance of the role's type. In the DependsOn example, both roles would be of type Module.

Every role has a cardinality, which provides lower and upper bounds on the number of MBeans that can appear in that role in a given relation instance. Usually, the lower and upper bounds are both 1, with exactly one MBean appearing in the role. The cardinality only limits the number of MBeans in the role per relation instance. The same MBean can appear in the same role in any number of instances of a relation type. In the DependsOn example, a given module can depend on many other modules, and be depended on by many others, but any given relation instance links exactly one dependent module with exactly one dependedOn module.

A relation type can be created explicitly, as an object implementing the RelationType interface, typically a RelationTypeSupport. Alternatively, a relation type can be created implicitly using the Relation Service's createRelationType method. A relation instance can be created explicitly, as an object implementing the Relation interface, typically a RelationSupport. A RelationSupport is itself a valid MBean, so it can be registered in the MBean server, though this is not required. Alternatively, a relation instance can be created implicitly using the Relation Service's createRelation method.

Through the relation service, users can create relation types and then create, access, and delete instances of a relation. All MBeans are referenced by their object name, so that a relation can be accessed from a remote application. An MBean does not need to know what relations it participates in. New kinds of relations can be added to an agent without having to modify the code of the MBeans that they link.

The relation service provides query mechanisms to retrieve MBeans that are related to each other. The relation service is notified when MBeans in a relation are unregistered, and it verifies that any relation involving that MBean still has the required cardinality.

The relation service can represent a relation instance either internally or externally. If the user defines a relation instance through the API of the relation service, the relation is represented by internal structures that are not accessible to the user. This is the simplest way to define relations, because the relation service handles all coherence issues through its internal structures.

A relation instance can also be a separate MBean object that fulfills certain requirements. The user instantiates and registers these MBeans, ensures that they represent a coherent relationship, and places these MBeans under the control of the relation service. This process places the responsibility of maintaining coherency on the user, but external relations have certain advantages. They can implement operations on a relation instance. Because external relations are MBeans, these extended operations are available to remote management applications.

2.6 Security

The Java DMK provides several security mechanisms to protect your agent applications. As is always the case, simple security that enforces management privileges is relatively easy to implement. However, full security against mischievous attacks requires a more sophisticated implementation and deployment scheme. However, in all cases the security mechanisms preserve the Java dynamic management architecture and management model.

New connector protocols were brought into Java DMK in version 5.1, with the integration of the JMX Remote API. These new connectors implement new security mechanisms.

The following sections give an overview of the new security features that are provided through components of the Java DMK.

2.6.1 Security for Standard Connectors

Three main aspects to connector security exist in Java DMK.

2.6.1.1 Privacy

The JMXMP connector negotiates security parameters during the initial handshake of a connection. In particular, the JMXMP connector can negotiate that the connection use transport layer security (TLS), which is basically the same as SSL 3.0. The server can require that only connections with TLS are accepted.

The SASL mechanisms DIGEST-MD5 and GSSAPI also provide connection privacy. See 2.6.1.2 Client Authentication in the JMXMP connector.

Privacy can be assured for the RMI connector by using an RMI socket factory to cause connections to be created using TLS. Java DMK 5.1 includes a socket factory that does this. The connector server imposes the socket factory, which is serialized into client stubs so that all clients automatically use it.

2.6.1.2 Client Authentication in the JMXMP connector

Authentication in the JMXMP connector is based on SASL. The handshake phase of a JMXMP connection can negotiate the SASL mechanism to use. The connector server can mandate a list of mechanisms, and reject connections that do not negotiate one of them. When a SASL mechanism successfully completes, it has authenticated a client identity, which is used to derive the Subject for the connection.

The SASL mechanisms DIGEST-MD5 and GSSAPI also provide connection privacy. For these mechanisms, a TLS connection is superfluous.

TLS also supports client authentication. The JMXMP connector can exploit this to accept only clients that can authenticate themselves, but in this case it does not currently support authorization based on the authenticated identity.

2.6.1.3 Client Authentication in the RMI connector

The RMI connector provides a simple way to add authentication. This mechanism is unambitious, but is powerful enough to build real solutions. However, where security is a major concern, users should consider using the JMXMP connector instead.

An RMI connector server can supply a JMXAuthenticator. This is a Java object with a method that takes an arbitrary credentials object and either returns a Java Subject if the credentials are accepted, or throws an exception if they are not. When a connection is made, if the authenticator accepts the credentials then subsequent operations over the connection are performed as the returned Subject. If the authenticator does not accept the credentials, then the connection is refused.

Challenge-response mechanisms can be introduced into this scheme by having the authenticator throw a specific exception containing a challenge. The client responds with new credentials that respond to the challenge.

A simple JMXAuthenticator is included in Java DMK 5.1. This simple authenticator is also included in Sun's implementation of the J2SE platform, version 1.5. The credentials consist of two strings, a role name and a clear text password. The authenticator consults a text file to validate the credentials. In this file, blank lines and lines beginning with # are ignored. Other lines must contain two blank-separated fields, again a role name and a clear text password. If the credentials match one of these lines then the connection is authenticated with a Subject containing the role name.

Obviously, where clear text passwords are involved, considerable caution is necessary. Connection privacy must be established if there is any danger of snooping. We talk of role names rather than user names so as not to encourage naive users to put real user passwords in the password file. A template file is included in the relevant examples that warns in comments that the file must be read-protected, that valuable passwords should not be used, and that in environments with strong security requirements this solution is inappropriate. We include this scheme for simple uses and for getting started, but expect that most deployed systems will prefer a system that does not use clear text passwords and that integrates into an existing security infrastructure.

Again, TLS also supports client authentication. Using the socket factory mentioned in 2.2 The MBean Server, the RMI connector can be configured to accept only clients that can authenticate themselves. However, in this case it does not currently support authorization based on the authenticated identity.

2.6.1.4 Server authentication

The Java DMK's security model is focused on ensuring that rogue clients cannot harm legitimate servers. However, a complete security solution must also ensure that, if a rogue server somehow substitutes itself for the legitimate server a client expects to find, the client is not compromised. For example, a rogue server could send bogus data to the client, or overload it, or receive sensitive information from it.

Server authentication can be done using TLS. The SASL mechanisms DIGEST-MD5 and GSSAPI also support server authentication.

2.6.1.5 Authorization

Authorization works in the same way with both connectors. The authentication step produces a Java Subject, which is a collection of Principals. The security mechanisms in the Java platform allow permissions to be associated with each Principal. When a remote operation is performed, the required permissions must be present, usually because they are associated with one of the authenticated Principals in the policy file.

A simplified authorization scheme is supported by Java DMK. This scheme is also used in Sun's implementation of the J2SE platform, version 1.5. In the simplified scheme, Java permissions are not involved. This removes the need to create policy files and to set a security manager, which are relatively complicated. Instead, there are just two access levels, readonly and readwrite.

The readwrite level gives access to all MBean server operations. The only exceptions are the creation of m-lets and the addition of URLs to existing m-lets. Since these operations could allow arbitrary code to be loaded into the MBean server and run, they are forbidden even at the readwrite level. When there is a security manager, running arbitrary downloaded code is acceptable because it will have no permissions by default. But the simplified scheme is specifically intended for the case where there is no security manager.

The readonly level gives access only to operations that do not change the state of the MBean server, such as reading attributes or querying existing MBeans.

A text file defines the access levels for different principals. In this file, blank lines and lines beginning with # are ignored. Other lines must contain two blank-separated fields. The first is an authenticated principal name, and the second is readonly or readwrite.

The mechanism that checks authorization in this simplified scheme is intended for simple uses and for getting started. It is expected that users with strong security requirements will eventually graduate to using the full Java security model, with permissions, policy files, and a security manager.

2.6.1.6 Subject Delegation

Java DMK 5.1 provides for subject delegation. The idea is that a single connection authenticated with a trusted identity, the delegate, can perform operations on behalf of other identities, without having to authenticate those identities explicitly or to establish a different connection per identity.

The delegate must have a specific permission to perform operations on behalf of each identity it assumes. This permission can be specified with a wildcard, to allow delegation from a set of identities. Unlike most permission checks, this one happens even if there is no Java security manager.

2.7 The SNMP Toolkit

The Java Dynamic Management Kit provides a toolkit for integrating SNMP management into a JMX architecture. SNMP management includes:

For more information regarding the SNMP toolkit, refer to the Java Dynamic Management Kit 5.1 Tools Reference Guide and the Java Dynamic Management Kit 5.1 Tutorial.

2.7.1 SNMP Packaging in Java DMK 5.1

The Java packaging of the SNMP classes for Java DMK 5.1 has changed. In Java DMK 5.0, the SNMP classes were included in the SUNWjsnmp package, and they required a separate Java archive (JAR) file, jsnmpapi.jar. In Java DMK 5.1, the SNMP classes are packaged in the SUNWjdmk-runtime package, and require the same jdmkrt.jar JAR file as the rest of the current Java DMK classes. This new arrangement avoids the issue of potentially conflicting versions of the SUNWjsnmp package encountered under Java DMK 5.0.

In addition, the SNMP API delivered with Java DMK 5.0 is now deprecated. The SNMP API in Java DMK 5.1 is effectively a completely new SNMP API, that introduces a more orthodox system of Java class naming.

To use existing SNMP implementations that you created using Java DMK 5.0 alongside SNMP implementations created using Java DMK 5.1, you must translate the class names of the 5.0 implementations into the new format. How to perform this translation is explained in the Release Notes.

To continue to use SNMP implementations you created using version 5.0 of Java DMK under version 5.1, a new JAR file called legacysnmp.jar is provided. You must add this new JAR to your classpath when running your Java DMK 5.0 SNMP implementations under Java DMK 5.1.

All the examples of SNMP code given in the /examples/current/Snmp directory have already been translated to implement the new class naming system. However, should you require them, a full set of SNMP examples that follow the package naming from Java DMK 5.0 have been retained in the /examples/legacy/Snmp directory.

2.7.2 Developing an SNMP Agent

An SNMP agent is an application that responds to SNMP requests formulated as get, set, getnext, and getbulk operations on variables defined in a MIB. This behavior can be fully mapped onto the MBean server and MBean resources of a Java dynamic management agent, provided that those MBeans specifically implement the MIB. An SNMP agent can be issued either with or independently from an MBean server.

There are two SNMP protocol adaptors: one that supports SNMPv1 and v2, and another introduced in the Java DMK 5.0 that supports SNMPv3 as well as the two previous versions. All features added in the Java DMK 5.0 therefore support SNMPv3 USM MIBs, providing user-based security, and scoped MIBs, that can be registered in the adaptor using a context name. The addition of multithread support in SNMP adaptors and timers in Java DMK 5.0 has also improved the performance of SNMP.

The SNMP protocol adaptors respond to requests in SNMP and translate the requests into management operations on the specific MIB MBeans. The SNMP adaptors also send traps, the equivalent of a JMX agent notification, in response to SNMP events or errors.

The SNMP protocol adaptors can manage an unlimited number of different MIBs. These MIBs can be loaded or unloaded dynamically, by registering and unregistering the corresponding MBeans. The adaptors attempt to respond to an SNMP request by accessing all loaded MIBs. However, MIBs are dynamic only through the agent application, and the SNMP protocol does not support requests for loading or unloading MIBs.

One advantage of the dual JMX–SNMP agent is that MIBs can be loaded dynamically in response to network conditions, or even in response to SNMP requests. Other Java dynamic management applications can also access the MIB through its MBean interface. For example, the value of a MIB variable might be computed in another application and written by a call to the MBean setter.

The SNMP protocol adaptors also send inform requests from an SNMP agent to an SNMP manager. The SNMP manager sends an inform response back to the SNMP agent.

2.7.3 SNMP MIB Compiler – mibgen

The mibgen tool takes as input a set of SNMP MIBs and generates standard MBeans that you can customize. MIBs can be expressed using either structure of management information (SMI) v1 or SMI v2 syntax.

A MIB is like a management interface. It defines what is exposed, but it does not define how to compute the exposed value. Therefore, MBeans generated by mibgen need to be customized to provide the definitive implementation. The MIB is implemented through Java objects, meaning that it has access to all Java runtime libraries and all features of the dynamic agent where it will be instantiated.

The mibgen compiler parses an SNMP MIB and generates the following:

The resulting classes should be made accessible in the agent application. When the single MBean representing the whole MIB is registered in the MBean server, all the associated groups are automatically instantiated and registered as well.

The mibgen compiler supports all data structure of SMI v1 and v2 protocols, including:

The Java DMK also provides an example program, showing how an agent can act as an SNMP master agent to access MIBs implemented remotely in subagents. This allows SNMP managers to access hierarchies of agents through a single master agent. In this way, some MIBs can be implemented by native devices and others can be implemented in JMX agents, yet this heterogeneous architecture is completely transparent to the manager issuing a request.

2.7.4 SNMP Manager API

The SNMP manager API simplifies the development of Java applications for managing SNMP agents. Its classes represent SNMP manager concepts such as sessions, parameters, and peers through Java objects. Using this API, you can develop an application that can issue requests to SNMP agents.

For example, you could create an SNMP resource using the SNMP manager API. You would define a management interface that corresponds to your resource's MIB, in which variables are easily mapped as MBean attributes. In response to calls on the attribute getters and setters, your MBean would construct and issue an SNMP request to the SNMP agent that represents the resource.

The SNMP manager API supports requests in the SNMP v1, v2 or v3 protocol, including inform requests for communicating between SNMP managers. The manager API is used to access any compliant SNMP agent, including those developed with the use of the Java DMK.

2.7.5 SNMPv1 and SNMPv2 Security

Because of backward compatibility, Java DMK 5.1 implements the security aspects of the SNMP protocol v1 and v2. However, you should implement the superior security mechanisms of SNMPv3, which are added in the Java DMK 5.1.

2.7.5.1 SNMPv1 and SNMPv2 Access Control

SNMPv1 and v2 define an access control mechanism similar to password authentication. Lists of authorized manager host names are defined in an access control list (ACL) stored in a file on the agent side, called the IP ACL file. There are no passwords, but logical community names (IP addresses) can be associated with authorized managers to define sets of allowed operations.

The SNMP adaptor performs access control if an ACL file is defined. Because SNMP is a connection—free protocol, the manager host and community are verified with every incoming request. By default, the file is not loaded and any SNMP manager can send requests.

The ACL file is the default access control mechanism in the SNMP protocol adaptor. However, you can replace this default implementation with your own mechanism. For example, if your agent runs on a device with no file system, you could implement access control lists through a simple Java class.

2.7.5.2 SNMPv1 and SNMPv2 Encoding

SNMP requests follow the standardized Basic Encoding Rules (BER) for translating management operations into data packets. At the communication level, an SNMP request is represented by an array of bytes in a UDP protocol packet. The SNMP components in the Java DMK provide access to the byte encoding of these packets.

Your applications can customize the encoding and decoding of SNMP requests, as follows:

2.7.6 SNMPv3 Security

The main addition to Java DMK 5.1 provided by SNMPv3 is the possibility of secure SNMP operation. The SNMPv3 security in Java Dynamic Management Kit 5.1 implements the following SNMP RFCs:

RFC 2571

Architecture

RFC 2572

Message Processing and Dispatching

RFC 2574

USM

The SNMPv3 protocol implementation provides:

Despite the differences between the previous versions of SNMP and SNMPv3, agents in Java DMK 5.1 can respond to requests from any version if the SNMPv3 protocol adaptor is used. SNMP v1 and v2 requests have greater security constraints than v3 requests in an agent compatible with SNMPv3.

The USM MIB is accessible remotely and is not registered to the SNMPv3 adaptor by default.

The USM MIB can be registered in an MBean server, thus making it accessible through the HTML adaptor. This is particularly useful when debugging, although it does create a security risk. Exposing the USM MIB through SNMP without the MBean server, however, is not insecure.

Users can also be configured into an agent by means of an ASCII text file that acts as an initial configuration template for all agents created.

2.7.6.1 SNMPv3 Authentication and Privacy

Inside SNMP domains, every SNMP entity is issued a unique identifier, the engine ID. Java DMK 5.1 provide a set of classes to allow you to generate engine IDs based on, amongst other identifiers, host names, internet protocol (IP) addresses, port numbers and Internet assigned numbers authority (IANA) numbers.

There are two types of SNMP entity:

Authoritative agent entities receive get, set, getnext, and getbulk requests and send traps. Nonauthoritative agents send informs.

Authoritative manager entities receive informs. Nonauthoritative managers send get, set, getnext and getbulk requests and informs, and receive traps. The engine ID and the number of times the engine has booted can be stored and persisted in the SNMPv3 security file, so that the timeliness of the incoming requests can be verified.

Under SNMPv3 there are three levels of security:

Managers and agents are both configured with a username, allowing the manager specific access to that agent. The username has an associated password. Both the agent and the manager sides must be configured according to the desired security policy. For requests to be authenticated, the manager and the agent must share knowledge of the authentication password associated with the username. For requests to be encrypted, the manager and the agent must additionally share knowledge of the privacy password associated with the username.

Unsecured SNMP Requests

When an agent receives a request from a manager, it checks its LCD. If the user is found in the LCD, the request is granted. No timeliness checking is performed, and the content of the request is not encrypted.

Authenticated Requests

The agent checks the identity of the originator of the request as previously described and then checks the timeliness of the request to ensure that it has not been delayed or intercepted for improper purposes. To monitor the timeliness of the arrival of requests, both manager and agent maintain synchronized clocks, and the manager's local notion of the authoritative engine's time of sending is included in the request. If the difference between the time of sending included in the request and the time of receipt recorded by the agent exceeds 150 seconds, then the request is not considered timely and is rejected.

Once the timeliness of the request has been confirmed, the request is authenticated using either of the HMAC-MD5 or HMAC-SHA protocols. These protocols check that the message digest included in the message matches the one computed locally in the receiving agent.

Authenticated and Encrypted Requests

If privacy has been activated, the content of the request is encrypted, using the DES encryption protocol provided by the Java cryptography extension (JCE) from JDK 1.4. The secure hash algorithm (SHA) and MD5 encryption protocols provided in JDK 1.2 are also used. The requests are decrypted and forwarded once the identity of the sender and the timeliness of the request have been established.

Error Messages

If any of the preceding checks fail, one of the following errors will be generated:

unknownUser

Unregistered user

unknownEngineID

Unregistered SNMP entity

encryptionFailed

Encryption error

unsupportedSecurityLevel

Unsupported security level

authentificationFailed

Password error

notInTimeWindow

Timeliness error

Note –

You can optionally implement alternative authentication and encryption algorithms. You cannot, however, plug in customized security or access control models in Java Dynamic Management Kit 5.1, although this will be possible in future versions.

2.7.6.2 SNMPv3 Access Control

SNMPv3 access control differs from the access control defined by versions 1 and 2, in that it is based on contexts and user names, rather than on IP addresses and community strings. The configuration for SNMPv3 access control is located in a text file, called the user ACL file. See the Java Dynamic Management Kit 5.1 Tutorial for information about the user ACL file and how to configure it.

When managers send a requests to an agent, the agent authenticates and, if necessary, decrypts the request, as explained earlier. It then passes the request through SNMP context-checking filters to determine whether it is authorized.

2.7.6.3 SNMPv3 Security Configuration

The configuration for SNMPv3 user-based security is located in a text file, called the security file. Each SNMP engine has its own security file. See the Java Dynamic Management Kit 5.1 Tutorial for information about the user security file and how to configure it.

You can view examples of security files at:

installDir/SUNWjdmk/5.1/examples/current/Snmp