Previous Next Contents Index


5

Adaptors

An adaptor provides access to m-beans through a communications protocol. It enables management applications to perform management operations on a Java Dynamic Management agent. For a Java Dynamic Management agent to be manageable, it must contain at least one adaptor. However, a Java Dynamic Management agent can contain many adaptors, allowing it to be managed remotely through different protocols.

Supplied Adaptors

The following adaptors are supplied with the Java Dynamic Management Kit:

RMI Adaptor

The RMI adaptor enables Java managers to access a Java Dynamic Management agent using the Java remote method invocation (RMI) system. By default, the RMI adaptor registers as:
rmi://localhost:1099/com.sun.jaw.impl.adaptor.rmi.AdaptorServer

HTTP/TCP Adaptor

The HTTP/TCP adaptor enables Java managers to access a Java Dynamic Management agent using HTTP over a TCP/IP connection. It also allows these management applications to access an agent across proxy servers. By default, the HTTP/TCP adaptor listens for incoming requests on port 8081. The HTTP/TCP adaptor provides login/password authentication.

HTTP/UDP Adaptor

The HTTP/UDP adaptor enables Java managers to access a Java Dynamic Management agent using HTTP over UDP. By default, the HTTP/UDP adaptor listens for incoming requests on port 8083. The HTTP/UDP adaptor provides login/password authentication.

Note - UDP is a lightweight protocol designed to send messages without requiring an extensive protocol mechanism, it does not provide total reliability. UDP does not divide outgoing messages into datagram packets or sequence incoming messages.

HTTP/SSL Adaptor

The HTTP/SSL adaptor enables Java managers to access a Java Dynamic Management agent using HTTP over SSL. It also allows these management applications to access an agent across proxy servers. By default, the HTTP/SSL adaptor listens for incoming requests on port 8084. The HTTP/SSL adaptor provides login/password authentication. The HTTP/SSL adaptor server requires client authentication by default.

The behavior of the HTTP/SSL adaptor is governed by the particular SSL implementation used in your applications. The cipher suites that are enabled are the defaults of the SSL implementation. The SSL implementation must be compliant with the SSL Standard Extension API provided by the Java Development Kit (JDKTM) Version 1.1. If you need to provide your own SSL implementation, you should rewrite the com.sun.jaw.impl.adaptor.https.AdaptorSocket class and replace the one installed with the Java Dynamic Management Kit.

HTML Adaptor

The HTML adaptor is an HTML server that enables web browsers to access a Java Dynamic Management agent through the HTTP communications protocol. When an HTML adaptor is instantiated, it creates a TCP/IP socket and waits for incoming requests. By default, the HTML adaptor listens for incoming requests on port 8082. The HTML adaptor provides login/password authentication.

The HTML adaptor is provided as a tool for debugging and speeding the development of agents. For more information, refer to "The M-Bean Browser Web Page" on page 102.

IIOP Adaptor

The IIOP adaptor enables CORBA clients to communicate with a Java Dynamic Management agent as if it were a CORBA server. The IIOP adaptor allows CORBA clients to create and delete m-beans, get and set properties of m-beans, and perform actions.

The IIOP adaptor uses a CORBA name server. The CORBA name server is specified by the hostname on which the name server is running and the port number. By default, the IIOP adaptor uses the hostname of the local machine and port 8085 as the CORBA naming service location. The CORBA name service must be started before it can be used. To start the name service, you need to run the nameserv script (Solaris) or batch file (Windows NT), using the -ORBInitialPort switch and specifying the port number:  

% nameserv -ORBInitialPort portNumber

CORBA Name

The CORBA name specifies the following properties of the CORBA environment:

The CORBA name that is stored on the name server has the format:
iiop://nameserver_host:nameserver_port/agent_host/adaptor_name

Example CORBA Service
FIGURE 5-1 shows a simple example of a CORBA service. The CORBA client in this example is a third party supplied client, not the IIOP client supplied with the Java Dynamic Management Kit.

FIGURE  5-1 Example CORBA Service
The CORBA name service is running on a machine with the hostname hawaii and using port 9876. The name service is started by executing using the nameserv command on hawaii:
% nameserv -ORBInitialPort 9876

The Java Dynamic Management agent, running on the machine with the hostname summer, instantiates an IIOP adaptor using the CORBA name service running on hawaii. The name used to instantiate the IIOP adaptor is IIOP_adaptor_test. The CORBA name of the IIOP adaptor is:

iiop://hawaii:9876/summer/IIOP_adaptor_test

The default name of the Java Dynamic Management agent adaptor is:

iiop://hawaii:9876/summer/com.sun.jaw.impl.adaptor.iiop.AdaptorServerImpl
   

The Interface Definition Language (IDL) is used to define the interfaces to CORBA objects. The AdaptorServer.idl file and nameserv script/batch file are found in the locations shown in the table, unless the Java Dynamic Management Kit was not installed in the default directory.   

Operating Environment
 		Default IDL File location

Solaris

/etc/opt/SUNWconn/jaw/iiop/AdaptorServer.idl

Windows NT

C:\Program Files\SUNWconn\jaw\etc\iiop\AdaptorServer.idl

Where operations are performed on Java and CORBA objects by the same agent, you must ensure that the correct object type is specified. To avoid problems, you should specify objects as instances of either Java objects or CORBA objects.

SNMP Adaptor

The SNMP adaptor enables an SNMP manager to perform management operations on a Java Dynamic Management agent. Before using the SNMP adaptor, you need to configure it for the MIB used by the SNMP manager application. This is explained in Chapter 17 "The mibgen Compiler".

Adding an Adaptor to an Agent

To add an adaptor, create an instance of the Java class that implements the adaptor you want to use.
Adaptor
 		Java Class

RMI

com.sun.jaw.impl.adaptor.rmi.AdaptorServerImpl

HTTP/TCP

com.sun.jaw.impl.adaptor.http.AdaptorServerImpl

HTTP/UDP

com.sun.jaw.impl.adaptor.udp.AdaptorServerImpl

HTTP/SSL

com.sun.jaw.impl.adaptor.https.AdaptorServerImpl

HTML

com.sun.jaw.impl.adaptor.html.AdaptorServerImpl

IIOP

com.sun.jaw.impl.adaptor.iiop.AdaptorServerImpl

SNMP

com.sun.jaw.impl.adaptor.snmp.AdaptorServerImpl

The Java Dynamic Management Kit provides the following ways to add an adaptor to an agent:

If you want to use more than one RMI adaptor per agent (or client), you need to run the rmiregistry command for each additional RMI adaptor, specifying the port number that the new adaptor is going to use:  
% rmiregistry portNumber

For information on how to add an SNMP adaptor to an agent, refer to "Loading MIBs Into an SNMP Adaptor" on page 243.

Access to an Adaptor

Access to an adaptor depends on the manager that uses it; there are two types of access:

Direct Access
These types of management applications access adaptors directly:

Access Through an Adaptor Client
Java managers access an adaptor through an adaptor client. The Java Dynamic Management Kit provides adaptor clients to enable a Java manager to access an adaptor using these protocols:

For information on how to use the adaptor clients, refer to Chapter 7.

Operation of the Adaptors

The purpose of an adaptor is to enable a manager to:

When a request from a manager to instantiate and register an m-bean is carried out, the Java class of the m-bean is determined by the mapping service. By default the mapping service uses the rules described in "Mapping Rules for Class Names" on page 81. The code of the class does not have to be present on the same machine as the agent in which the m-bean is to be instantiated.

Access Control

The Java Dynamic Management Kit provides mechanisms for controlling access by a manager to an agent. The access control methods available depend on the adaptor used.

The Java Dynamic Management Kit does not provide access control for the RMI adaptor or the IIOP adaptor.

Authentication

The HTTP/TCP, HTTP/UDP, HTTP/SSL and HTML adaptors provide login/password authentication. In this authentication scheme, the client object and the server object contain authentication information. The server side object contains an array of objects that contains authentication information for all known clients. When a client attempts to login, the login/password object that it sends is compared with the array to see if the client is in the list of permitted clients. If the list of permitted clients is null, no client authentication is performed by the adaptor; access is granted to all clients.

The HTTP/TCP, HTTP/UDP, and HTTP/SSL adaptors provide login/password authentication based on `CRAM-MD5 (Challenge-Response Authentication Mechanism using MD5)' as specified in RFC2104 and RFC2195.

The HTML adaptor provides login/password authentication, as specified in the `Basic Authentication Scheme,' in RFC1945.

Default Behavior
The default behavior for the HTTP/TCP, HTTP/UDP, HTTP/SSL, and HTML adaptors is not to require authentication information.

Adding an Adaptor Supporting Authentication

To add an adaptor to an agent, create an instance of the Java class that implements the adaptor. The classes are shown on page 56. To add login/password authentication, create an instance of the AuthInfo class and add this to the adaptor object. CODE EXAMPLE 5-1 shows the instantiation of an HTTP/TCP adaptor and authentication information objects for two users. The second authentication information object is then removed.
CODE  EXAMPLE  5-1     Adding an Adaptor Supporting Authentication  

   // Add the HTTP adaptor service.
   //
   String httpClassName = "com.sun.jaw.impl.adaptor.http.AdaptorServerImpl";
   String httpName = new String(domain + ":" + ServiceName.ADAPTOR +             ".protocol=http,port=8081");
   com.sun.jaw.impl.adaptor.http.AdaptorServerImpl http =
             (com.sun.jaw.impl.adaptor.http.AdaptorServerImpl)              cmf.newObject(httpClassName, httpName);
...
   // Initialize the server authentication information.
   //
   AuthInfo ai1 = new AuthInfo("username1", "password1");
   http.addUserAuthenticationInfo(ai1);
   AuthInfo ai2 = new AuthInfo("username2", password2");
   http.addUserAuthenticationInfo(ai2);
...
   // Remove the user with login "username2" from the server.
   //
   http.removeUserAuthenticationInfo(ai2);

 

Access Control Using an ACL file

For the SNMP adaptor, the Java Dynamic Management Kit provides access control based on the IP address of the host or proxy machine of the manager. Information on each machine and the access rights it has is stored in an ACL file.

Enabling Access Control for the SNMP Adaptor

To enable access control for the SNMP adaptor, ensure that an ACL file exists when any agents are started. The ACL file must be named jaw.acl and must be located in the configuration directory. If the configuration directory is not found in one of the default paths shown in the table, the framework/adaptor uses the CLASSPATH environment variable (see Appendix B "Environment Variables") to determine the correct path. The configuration directory is found in the paths shown in the table unless the Java Dynamic Management Kit was not installed in the default directory.   
Operating Environment
 		Configuration Directory

Solaris

/etc/opt/SUNWconn/jaw/conf/

Windows NT

C:\Program File\SUNWconn\jaw\etc\conf\

If an ACL file exists, the access rights it defines apply to all managers or proxy servers that access agents through the SNMP adaptor. The machine of the agent has read-write access. If this file does not exist when the agents are started, all managers are granted access to the agents through the SNMP adaptor.

The format of an ACL file is defined in "ACL File Format." A template file named template.acl is provided in the configuration directory. Copy this file to jaw.acl and edit it to define the access control you require.

ACL File Format

An ACL file contains the following groups of configuration variables:

Format of the acl Variable Group  
CODE  EXAMPLE  5-2     Format of the acl Configuration Variable Group

   acl = {
      list1
      list2
      ...
      listn
   }

The acl group contains one or more lists of configuration variables. The format of each list is defined in CODE EXAMPLE 5-3.
CODE  EXAMPLE  5-3     Format of a List in the acl Group

   {
      communities = communityList
      access = accessCode
      managers = hostList
   }

The meaning of each item is:

communities = communityList

This item specifies the SNMP community names, where communityList is a list of SNMP community names. Each community name in the list must be separated from the one that precedes it by a comma.

access = accessCode

This item specifies the access rights to be granted to all managers running on the machines specified in the managers item. The accessCode keyword is one of the following:

read-write

The managers are allowed to get and set properties of m-beans.

read-only

The managers are allowed only to get properties of m-beans.

managers = hostList

This item specifies the host machines of the managers to be granted the access rights specified in the access item. The hostList item is a list of hosts. Each host in hostList can be expressed as any one of the following:

Each host in the list must be separated from the one that precedes it by a comma.

Note - To distinguish between IP addresses and subnet masks in an ACL file, each integer in a subnet mask is separated by an exclamation mark instead of a dot.
Format of the trap Variable Group   
The trap group specifies the hosts to which the agent will send traps. The format of the trap variable group is defined in CODE EXAMPLE 5-4.  
CODE  EXAMPLE  5-4     Format of the trap Configuration Variable Group

   trap = {
      trap1
      trap2
      ...
      trapn
   }

The trap group contains one or more trap community definitions. Each defines the association between a set of hosts and the SNMP community string in the traps to be sent to them. The format of each list is defined in CODE EXAMPLE 5-5.  

CODE  EXAMPLE  5-5     Format of a List in the trap Group

   {
      trap-community = trapCommunityString
      hosts = trapInterestHostList
   }

The meaning of each item is:

trap-community = trapCommunityString

This item specifies the SNMP community string. It will be present in the traps sent to the hosts specified in the hosts item.

hosts = trapInterestHostList

This item specifies the set of hosts. Traps sent to these hosts will contain the SNMP community string specified by the trap-community item. The trapInterestHostList item is a list of hosts. Each host in trapInterestHostList can be expressed as any one of the following:

Each host in the list must be separated from the one that precedes it by a comma.

Example ACL File

An example ACL file is given in CODE EXAMPLE 5-6.
CODE  EXAMPLE  5-6     Example ACL File 

acl = {
   {
   communities = public, private
   access = read-only
   managers = hubble, snowbell, nanak
   }
   {
   communities = jerry
   access = read-write
   managers = 123.456.789.123
   }
   {
   communities = jerry
   access = read-write
   managers = 123!456!789!255
   }
}
trap = {
   {
   trap-community = SNMP-trap
   hosts = hubble, snowbell
   }
   {
   trap-community = competitor-trap
   hosts = hp_server, ibm_server, sgi
   }
}

In this example, managers running on the host machines hubble, snowbell, and nanak are allowed only to get properties of m-beans. The managers running on the following host machines are allowed to get and set properties of m-beans:

Managers running on any other host are denied access to m-beans.

The trap group in this example specifies that the agent will send:

Formal Grammar Definition of an ACL File

The formal grammar definition of an ACL file is given in CODE EXAMPLE 5-7.
CODE  EXAMPLE  5-7     Formal Grammar Definition of an ACL File 

   <acl_file:> :[ < acls> ] [ <trap_block> ]
   <acls> : "acl" "=" {<acls_list> }
   <acls_list> : /*empty*/ | <acls_list> <acl_item>
   <acl_item> : {<communities_stmt> <acl_access> <hosts> }
   <communities_stmt> : "communities" "=" <communities_set>
   <communities_set> : <communities_set> , <community_elem> | <community_elem>
   <community_elem>: alphanumeric_string
   <acl_access> : "access" "=" <acl_access_type>
   <acl_access_type> : read-only | read-write
   <hosts> : "managers" "=" <hosts_list>
   <hosts_list> : <hosts_list> , <host_item> | <host_item>
   <host_item> : <host_alphanumeric_string>
   <host_alphanumeric_string> : <hostname> | <ipaddress> | <subnet_mask>
   <trap_block> : "trap" "=" { <traps_list> }
   <traps_list> : /*empty*/ | <traps_list> <trap_item> | <trap_item>
   <trap_item> : { <trap_community_string> <trap_interest_hosts> }
   <trap_community_string> : "trap-community" "=" alphanumeric_string
   <trap_interest_hosts> : "hosts" "=" <trap_interest_hosts_list>
   <trap_interest_hosts_list> : <trap_interest_hosts_list> ","
   <trap_interest_host_item> | <trap_interest_host_item>
   <trap_interest_host_item> : <hostname> | <ipaddress>
   <hostname> : alphanumeric_string
   <ipaddress> : ###.###.###.###
   <subnet_mask> : ###!###!###!###

Access Control Using an ACL object

For the SNMP adaptor, you can create a class that implements a com.sun.jaw.reference.agent.services.IPAclSrvIf interface. An instance of that class enables you to enable access control in the same way as with an ACL file in applications that do not use a file system.

Access Control for the RMI Adaptor

The Java Dynamic Management Kit does not provide an access control mechanism for the RMI adaptor. To enable the RMI adaptor to provide secure data transfer you have to implement an access control mechanism using a network security application, such as SunScreenTM SKIP.

Implementing an Adaptor

An adaptor is an abstraction of a communications protocol. This means that the communication mechanism between agent and manager is hidden. The adaptors provided by the Java Dynamic Management Kit are implemented as m-beans. This enables them to be managed. The Java Dynamic Management Kit does not require an adaptor to conform to a specific interface definition or implementation. However, an adaptor must be able to access the framework to retrieve and change information in m-beans in an agent.


Copyright 1998 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California 94303 U.S.A.
Copyright in French
Previous Next Contents Index