This chapter covers the following topics:
This chapter contains instructions and examples for integrating the Sun Management Center Console with other applications. Two significant aspects of integration are considered:
- enabling the Console to launch user-specific applications
- enabling other management tools to utilize features provided by the Console
This chapter covers the following topics:
The Sun Management Center Console can be extended to include additional functionality as users deem necessary. Support for the integration of applications providing such functionality is through two configuration files
(console-tools.cfg and console-host-apps.cfg) and two utility scripts (es-tool and es-apps) that update the environment based on the content of the configuration files. Integration levels and syntax for entries in the configuration files are discussed in this section.
The general process for extending the Console is as follows:
- Place the Java class files or the .jar files for the user applications in the standard Sun Management Center location:
/opt/SUNWsymon/apps/classes/
- If there are any auxiliary files, such as, property files or images, they should also be placed in either this directory or a .jar file.
- Select the appropriate integration level to determine the appropriate configuration file and utility.
- Modify the appropriate configuration file to describe the desired extension.
- Run the appropriate update utility.
- Restart the Console. Depending upon your site's configuration, it may be necessary to restart the Server as well.
Integration Levels
Sun Management Center supports the following levels of application integration:
- External Java application with no API or access to the current host selection: This level applies to external, stand-alone applications written in Java that the user wishes to launch from the Console. The application must be written in Java; non-Java applications are accommodated by the SMSystemCommand Java wrapper class that executes other programs or shell scripts in a separate process. For a description of SMSystemCommand, refer to the section on "es-tool: Syntax for console-tools.cfg Entries".
The application does not require any host selection context or Client API handle. The application has no further interaction with Sun Management Center once it has been launched. The name of the application (as specified in the console-tools.cfg file) will be appended to the Tools Menu in the Console below the standard menu items provided by the Sun Management Center. Support for this integration level is provided through the console-tools.cfg file and the
es-tool update utility.
- External Java application with API and host selection context: This level applies to custom Java applications that the user wishes to launch from the Console. The application runs under the same JVM as the Console. The application requires a pre-authenticated Client API handle and additional global user information. The application may also require access to the host selection context. The name of the application (as specified in the console-tools.cfg file) will be appended to the Tools Menu in the Console below the standard menu items provided by the Sun Management Center. The GUI for the application is displayed in a separate window. Support for this integration level is provided through the console-tools.cfg file and the es-tool update utility.
- Internal Java application utilizing the host details context: This level applies to custom Java applications that the user wishes to launch for a particular host that has been selected in the Browser tab or the Topology display. The application requires access to the Host selection context. The name of the application (as specified in the console-host-apps.cfg file) will be added to the tree list displayed in the Applications tab in the Host Details window. The application may or may not have an associated GUI; if it does have a GUI, the GUI will be displayed within the Display portion of the Host Details window when the application is launched. Support for this integration level is provided through the console-host-apps.cfg file and the es-apps update utility.
Note - User applications may wish to implement the SMApp interface or extend the SmAppBase class in order to obtain access to the agent information. Refer to the javadocs for specific information.
Configuration Files
The console-tools.cfg and console-host-apps.cfg files are plain text files that can be edited with any standard text editor. The files reside on the host on which the Server is running. The files may be modified at any time (including while the Console is running), but changes introduced by editing the files will not take effect until the appropriate update utility is run on the server host and the Console is restarted (depending upon site configuration, it may be necessary to restart the Server as well). Each file consists of a series of lines, each of which describes an application; blank lines and lines beginning with the pound sign `#' are ignored. Fields within each line are separated by commas `,'.
es-tool: Syntax for console-tools.cfg Entries
Applications listed in the /var/opt/SUNWsymon/cfg/console-tools.cfg file are launched from the Tools menu in the Console main window. Each application is defined by a line with the following format:
Entry fields are as follows:
- menu label -- the string that will appear in the Tools menu. The string can be either unlocalized or localized text. Unlocalized text can contain embedded spaces. Localized text must be specified as a property_file:key pair, where property_file is the name of the file containing the localizable messages for a particular locale, and key is the identifier used to locate the string that will appear in the Tools menu in the property file. Note that spaces are not allowed in the key. Refer to chapter 17 for a discussion of the syntax for the property file.
- class -- the fully qualified Java class name.
- args -- the list of arguments to the class.
The example file below shows entries for three applications to be listed on the Tools menu: Example GUI, telnet, and ftp:
# Format:
# menu_label,class arguments
Example GUI,exampleApp.ExampleGUITool
Telnet,com.sun.symon.base.client.console.SMSystemCommand \
"/usr/openwin/bin/xterm -e telnet $host" "start telnet $host"
exampleApp.ExampleSystemCommand:ftp,exampleApp.ExampleSystemCommand \
"/usr/openwin/bin/xterm -e ftp $host" "start ftp $host"
|
A special built-in Java wrapper class SystemCommand is provided to enable the user to execute an arbitrary shell command. This class takes two arguments. The first argument is the shell command to execute. If a program name is specified, a full path should be given. If there are embedded spaces, the entire shell command should be enclosed in double quotes. The second argument is the command to run if on a Microsoft Windows client, in which case the first argument is ignored.
com.sun.symon.base.client.console.SystemCommand \
shell_command windows_command
|
Variable substitution is performed on the arguments if special variable references are present. The allowed variables are given below:
$host
replaced with currently selected agent host name
$port
replaced with currently selected agent port number
|
es-apps: Syntax for console-host-apps.cfg Entries
Applications listed in the /var/opt/SUNWsymon/cfg/console-host-apps.cfg file are launched from the Applications tab in the Host Details window. Each application is defined by a line with the following format:
menu_label,class,[args],[help]
|
Entry fields are as follows:
- menu label -- the string that will appear in the Applications tab. The string can be either unlocalized or localized text. Unlocalized text can contain embedded spaces. Localized text must be specified as a property_file:key pair, where property_file is the name of the file containing the localizable messages for a particular locale, and key is the identifier used to locate the string that will appear in the Applications tab in the property file. Note that spaces are not allowed in the key. Refer to chapter 17 for a discussion of the syntax for the property file.
- class -- the fully qualified Java class name.
- args (optional) -- the list of arguments to the class.
- help (optional) --the help key.
This is specified in one of the forms described in the "Help Key Usage".
Help Key Usage
- The help key is specified in one of the following forms.
- :file pair
The first form is a key:file pair, where key is a unique string that associates the help file with the application, and file is the name of the HTML file containing the help for the application. (Note that this is only the file name, not the full path of the HTML file, and that this HTML help file must be installed on the Sun Management Center server.) The directory where you need to install this file is:
/opt/SUNWsymon/lib/locale/<lang>/help
|
This means that file must be based on this root directory. For example, if you specify a file called, /mysubdir/myhelf.html, the file needs to be placed in:
/opt/SUNWsymon/lib/locale/<lang>/help/mysubdir/myhelp.html
|
- :url
The second form is :url, where url is any URL specification.
- :file
The third form is :file, where file is a fully qualified pathname to a file
(/mydirectory/myfile.html). This will load the specified file from the specified location. The file must be installed on the console machine.
Note - In the case where there are no arguments to the class but you wish to specify a help file, you must still indicate the (empty) arguments field with a command.
Note also that the Help files are installed on the Help Server machine. This machine may or may not be the same machine that the Sun Management Center server is installed upon, depending on how you set up your network and Sun Management Center. Even though the help files themselves are installed on the Help Server, you still execute the es-chelp, es-apps, and other applicable commands on the Sun Management Center server.
The example file below lists two hypothetical applications. The first application has arguments but no help file; the second application has a help file but no arguments.
# example 1: arguments but no help file
example.ExampleModuleApp1:ExampleApp1, example.ExampleApp1, arg1 arg2 arg3
#
# example 2: help file but no arguments
example.ExampleModuleApp2:ExampleApp2, example.ExampleApp2, key:file
|
Update Utilities
The integration configuration files can be edited at any time; however, in order for the changes specified in the file to be propagated to the Server, the appropriate update utility must be run on the Server host. For each configuration file, there is a corresponding update utility: for the console-tools.cfg file, the update utility is /opt/SUNWsymon/sbin/es-tool; for the console-host-apps.cfg file, the update utility is /opt/SUNW/symon/sbin/es-apps. If you wish to use an alternative configuration file, you can specify the name as an argument to the utility
The list of user applications is generated from these configuration files each time these scripts are run. Removing an entry from a configuration file will cause it to be also removed from the list.
Sun Management Center software is an enterprise-wide management solution for managing Sun platforms. Any other management solution that wants to use Sun Management Center software for management of a Sun platform can achieve this using a utility Bean that is provided as a part of the Sun Management Center Sun Management Center Developer Environment Manual . This Bean is a Sun Management Center Object Details window that can display details without requiring the user to navigate in the topology view in the Sun Management Center main console.
The class specification of this Bean is:
package name: com.sun.symon.apps.details.hostdetailsBean
Class HostdetailsBean
java.lang.Object
|
+--com.sun.symon.tools.hostdetailsBean.HostdetailsBean
public class HostdetailsBean extends java.lang.Object
|
HostdetailsBean is a Bean that launches an Sun Management Center Host Details window for a given Sun Management Center agent system monitored by a specified Sun Management Center server. This Bean uses classes and configuration files that are part of the Sun Management Center installation and therefore work only when the Sun Management Center console and server installation exists. Note that the Bean must be started in a separate thread.
|
To Invoke the HostDetailsBean
|
|
1. |
Instantiate a HostdetailsBean object:
HostdetailsBean theBean = new HostdetailsBean();
|
|
|
2. |
Initialize Bean parameters:
theBean.init(String,String,String,String,String,null);
|
|
|
3. |
Optionally, subscribe for PropertyChangeEvents from the Bean :
theBean.addPropertyChangeListener(this);
|
|
|
4. |
Optionally, set the exit() method of the Bean:
theBean.setExitAction(Object, String, Object[])
|
|
|
5. |
Launch hostdetails:
theBean.doLaunchHostdetails();
|
|
PropertyChangeEvent events are fired when exceptions from the Sun Management Center client API are caught. It is the responsibility of the Bean user to listen for these events and take appropriate action. Also, PropertyChangeEvents are fired to relay informational (status) messages that could be reflected in a GUI or used to control the Bean environment.
Field Summary
static java.lang.String ERROR_NO_TARGET
Bounded property value indicating target system not found
static java.lang.String HOSTDETAILS_ERROR
Bounded property-name for notification of Exception conditions
static java.lang.String HOSTDETAILS_STATUS
Bounded property-name for notification of status conditions
static java.lang.String SECURITY_SCHEME
security scheme
static java.lang.String STATUS_AUTHENTICATION_OK
Bounded property value indicating hostdetails is exiting without error
static java.lang.String STATUS_CONNECTION_OK
Bounded property value indicating hostdetails is exiting without error
static java.lang.String STATUS_EXITING_OK
Bounded property value indicating hostdetails is exiting without error
static java.lang.String STATUS_STARTUP_OK
Bounded property value indicating hostdetails started okay
|
Constructor Summary
Method Summary
void
addPropertyChangeListener(java.Beans.PropertyChangeListener listener)
|
Convenience method for subscribing an object to PropertyChangeEvents. This must be done after init() is called.
Bean exit method.
void doLaunchHostdetails()
|
This method communicates with the Sun Management Center server and launches the Hostdetails window.
void init(java.lang.String sName, int sPort,
java.lang.StringtargetHost, java.lang.String user,
java.lang.String pass, java.lang.String key)
|
This method initializes values needed for proper operation of the Bean.
void propertyChange(java.Beans.PropertyChangeEvent evt)
|
This method is responsible for notifying subscribers of property changes within the Bean.
void
removePropertyChangeListener(java.Beans.PropertyChangeListener
listener)
|
Convenience class for removing an object subscription to PropertyChangeEvents. This must be done after init() is called.
void setExitAction(java.lang.Object target, java.lang.String
method, java.lang.Object[] myArgs)
|
This method allows specification of an alternate method to execute when the hostdetails window is closed.
void setHostname(java.lang.String host)
|
Mutator method for setting the Sun Management Center server hostname.
void setHostport(int port)
|
Mutator method for setting the Sun Management Center server port.
void setPassword(java.lang.String pass)
|
Mutator method for setting the Sun Management Center server password.
void setPublicKey(java.lang.String key)
|
Mutator for Sun Management Center server public crypto key. If set to null, defaults to an internal value.
void setTarget(java.lang.String targ)
|
Mutator method for setting the target system.
void setUser(java.lang.String user)
|
Mutator method for setting the Sun Management Center server login username.
Field Detail
public static final java.lang.String HOSTDETAILS_ERROR
|
Bounded property-name for notification of exception conditions
public static final java.lang.String HOSTDETAILS_STATUS
|
Bounded property-name for notification of status conditions
public static final java.lang.String STATUS_STARTUP_OK
|
Bounded property value indicating hostdetails started okay
public static final java.lang.String STATUS_EXITING_OK
|
Bounded property value indicating hostdetails is exiting without error
public static final java.lang.String STATUS_CONNECTION_OK
|
Bounded property value indicating hostdetails is exiting without error.
public static final java.lang.String STATUS_AUTHENTICATION_OK
|
Bounded property value indicating hostdetails is exiting without an error.
public static final java.lang.String ERROR_NO_TARGET
|
Bounded property value indicating target system not found
public static final java.lang.String SECURITY_SCHEME
|
Security scheme.
public static final boolean WANT_ENCRYPTION
|
Encryption
Constructor Detail
Empty constructor for Bean compliance
Method Detail
public void init(java.lang.String sName, int sPort,
java.lang.String targetHost, java.lang.String user,
java.lang.String pass, java.lang.String key)
|
This method initializes values needed for proper operation of the Bean. Mutators are available for these fields in addition to this method.
Parameters:
- sName - Hostname of the Sun Management Center server
- sPort - Port number used by the Sun Management Center server
- targetHost - Sun Management Center "label name" of the system to be displayed
- user - Sun Management Center server login name
- pass - Sun Management Center server password for above user
- key - Sun Management Center server public key (defaults if null)
public void setHostname(java.lang.String host)
|
Mutator method for setting the Sun Management Center server hostname.
Parameters:
- host - Sun Management Center server hostname
public void setHostport(int port)
|
Mutator method for setting the Sun Management Center server port.Parameters:
- port - Sun Management Center server port number (probably 2099)
public void setTarget(java.lang.String targ)
|
Mutator method for setting the target system; that is, the system for which you would like hostdetails displayed.
Parameters:
- targ - target system name, as known to Sun Management Center as "label name"
This is not the same as hostname. It is the Sun Management Center label name.
public void setUser(java.lang.String user)
|
Mutator method for setting the Sun Management Center server login username.
Parameters:
- user - username for login to Sun Management Center server
public void setPassword(java.lang.String pass)
|
Mutator method for setting the Sun Management Center server password.
Parameters:
- pass - password for login to Sun Management Center server
public void setPublicKey(java.lang.String key)
|
Mutator for Sun Management Center server public crypto key If set null, this will
default to an internal value.
Parameters:
- key - Sun Management Center server public key.
public void propertyChange(java.Beans.PropertyChangeEvent evt)
|
This method is responsible for notifying subscribers of property changes within the Bean.
Parameters:
- evt - PropertyChangeEvent to be fired
public void
addPropertyChangeListener(java.Beans.PropertyChangeListener
listener)
|
Convenience method for subscribing an object to PropertyChangeEvents. This must be done after init() is called.
Parameters:
- listener - a PropertyChangeListener to subscribe for events
public void removePropertyChangeListener(java.Beans.PropertyChangeListener listener)
|
Convenience class for removing an object subscription to PropertyChangeEvents. This must be done after init() is called.
Parameters:
- listener - PropertyChangeListener to remove from subscription list
public void doExitAction()
|
Convenience method to do exit actions.
public void setExitAction(java.lang.Object
target,java.lang.String method, java.lang.Object[] myArgs)
|
Throws
java.lang.IllegalArgumentException
|
- This method allows specification of an alternate method to execute when the hostdetails window is closed. By default the Bean will call System.exit(0).
Parameters:
- target - Object which contains the method to be called
- method - Method name to be called
- argv - String array containing method arguments
Throws:
java.lang.IllegalArgumentException
|
if introspection/invocation would fail.
public void doLaunchHostdetails()
|
Throws:
java.lang.IllegalStateException
|
This method communicates with the Sun Management Center server and launches the Hostdetails window. If you did not initialize all fields correctly through init(), you may receive an IllegalStateException.
Throws:
java.lang.IllegalStateException - if any required fields are null.
|
For compilation of JavaBeansTM, the Java CLASSPATH must be set. Typically the CLASSPATH should be set to the following:
ESROOT = /opt/SUNWsymon
CLASSPATH = \
$(ESROOT)/jclass/chart/lib/jcchart362J.jar:\
$(ESROOT)/classes/essrv.jar:\
$(ESROOT)/classes/esclt.jar:\
$(ESROOT)/classes/escon.jar:\
$(ESROOT)/classes/escom.jar:\
$(CLASSPATH)
|
For an example of makefile, refer one the console examples under
/opt/SUNWsymon/sdk/examples/console
|
Copyright © 2000 Sun Microsystems, Inc. All Rights Reserved.