Skip Headers
Oracle® Enterprise Manager Advanced Configuration
10g Release 2 (10.2)

Part Number B16242-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Feedback

Go to previous page
Previous
Go to next page
Next
View PDF

14 Additional Configuration Tasks

This chapter contains the following sections:

14.1 Understanding Default and Custom Data Collections

When you install the Oracle Management Agent on a host computer, Enterprise Manager automatically begins gathering a default set of metrics that you can use to monitor the performance and availability of each targets on that host. For some of these target metrics, Enterprise Manager provides default threshold settings that determine when you will be notified that there is a problem with the metric.


See Also:

"About Alerts" in the Enterprise Manager online help

For selected metrics, you can customize the default thresholds. When you make these types of customizations, Enterprise Manager saves the new settings in a file on the local disk. The following sections provide more information about how these settings are saved:

14.1.1 How Enterprise Manager Stores Default Collection Information

Enterprise Manager stores the default collection criteria for each target in the following location on each Oracle Management Agent host:

AGENT_HOME/sysman/admin/default_collection/

For some targets, you can use the Oracle Enterprise Manager 10g Grid Control Console to modify the default metric collection settings. For example, you can modify the default thresholds for your host targets. When you make these types of modifications, Enterprise Manager creates a new default collection file in the following directory:

AGENT_HOME/sysman/emd/collection/

This collection file overrides the default collection information stored in the sysman/admin/default_collection directory.

14.1.2 Restoring Default Collection Settings

If you have made modifications to the metric thresholds for a particular target, you can restore the default metric collection settings by deleting the customized collection information in the sysman/emd/collection directory.

For example, if you want to restore the default collections for a particular database target, remove the customized collection file for that target from the sysman/emd/collection directory. Enterprise Manager will begin using the metric collection information stored in the sysman/admin/default_collection directory.

14.2 Enabling Multi-Inventory Support for Configuration Management

Every time you install an Oracle software product on a host computer, Oracle Universal Installer saves information about the software installation on your hard disk. The directories and files that contain this software configuration information are referred to as the Oracle Universal Installer inventory.

When you use Enterprise Manager to monitor your Oracle software installations, Enterprise Manager takes advantage of information saved in the Universal Installer inventory.

As it gathers information about the configuration of your host computer, by default, Enterprise Manager assumes that you have one Oracle Universal Installer inventory on the host. Specifically, Enterprise Manager recognizes the inventory that Oracle Universal Installer uses when you run the Universal Installer on the host.

However, in some cases, you may have more than one inventory. For example, you may have worked with Oracle Support to clone your Oracle software installations. For those cases, you can use the following procedure to be sure that Enterprise Manager can track and manage the software information in multiple inventories on the same host.


Caution:

Enabling support for multiple inventories is optional and available only for advanced users who are familiar with the Oracle Universal Installer inventory architecture and who have previously worked with multiple inventories on a managed host. This procedure is not required for hosts where normal installations have been performed.

To set up Enterprise Manager so it can read multiple inventories on a host:

  1. Locate the OUIinventories.add file in the following directory:

    $ORACLE_HOME/<nodename>_<sid>/sysman/config
    
    

    The Management Agent state listed in this example represents an installation for Database Control. For more information about the Management Agent state to use for other installations, see Section 14.2.1, "AGENT_HOME Versus AGENT_STATE Directories" .

  2. Open OUIinventories.add using a text editor.

    Instructions within the file describe the format to use when identifying multiple inventories, as well other techniques for mapping Oracle Homes.

  3. Carefully review the instructions within the file.

  4. Add entries to the file for each additional inventory on the managed host.

  5. Save your changes and close the file.

During its next collection of host configuration information, Enterprise Manager will start gathering software configuration information from the inventories that you identified in the OUIinventories.add file, in addition to the default inventory that Enterprise Manager normally collects.

Alternatively, to see the data gathered from the additional inventories before the next regularly-scheduled collection, navigate to the Host home page in the Grid Control Console, click the Configuration tab, and click the Refresh Data icon next to the page timestamp.


Note:

If there any irrecoverable problems during the collection of the default inventory (for example, if the inventory file or directory protections prevent Enterprise Manager from reading the inventory), inventories listed in OUIinventories.add file are also not collected.

If the Enterprise Manager is able to read the default inventory, but there is a problem reading an additional inventory listed in the OUIinventories.add file, Enterprise Manager issues a collection warning for those inventories. However, Enterprise Manager does collect the configuration information for the other inventories.


14.2.1 AGENT_HOME Versus AGENT_STATE Directories

The Management Agent recognizes two main directory structures; its installation directory where software binaries and all unchanging metadata are stored, and its configuration/state directory where all customizations and output/log content are stored and/or generated. In a normal Management Agent installation, these two directories are the same. However, they can be different in the following cases:

  • RAC Agent installation ($ORACLE_HOME versus $ORACLE_HOME/<hostname>)

  • Database Control installation ($ORACLE_HOME versus $ORACLE_HOME/<nodename><sid>)

  • State-only Management Agent deployment (using the emctl deploy agent command -- $ORACLE_HOME versus $EMSTATE)

In each of the above cases, there will be multiple instances of the Management Agent running off the same binaries installation. The different instances have different locations to maintain separate configurations but use the same set of binaries. The command emctl agent status provides the values of the Management Agent's binaries and state locations.

14.3 Manually Configuring a Database Target for Complete Monitoring

When you first discover an Oracle Database 10g target, you should check the monitoring credentials to be sure the password for the DBSNMP database user account is set correctly in the database target properties.

Besides setting the monitoring credentials, no other configuration tasks are required to monitor an Oracle Database 10g target.

However, when you monitor an Oracle9i database or an Oracle8i database, there is some additional configuration required if you want to monitor certain types of database performance metrics using the Grid Control Console.

To monitor these additional performance metrics Enterprise Manager requires that Oracle Statspack and some additional Enterprise Manager packages be installed and configured in the database you are monitoring.


See Also:

"Using Statspack" in Oracle Database Performance Tuning Guide and Reference in the Oracle9i Documentation Library

If these additional objects are not available and configured in the database, Enterprise Manager will not be able to gather the data for the complete set of performance metrics. In addition, Enterprise Manager will not be able to gather information that otherwise could be readily available from the Database home page, such as Bad SQL and the Top SQL Report.

You can use the Configure Database wizard in the Grid Control Console to install the required packages into the database, or you can use the following manual procedure.


See Also:

"Modifying Target Properties" in the Enterprise Manager online help for information on configuring managed targets, including database targets

To manually install Statspack and the other required database objects into an Oracle9i database that you are managing with Enterprise Manager, you can use SQL*Plus and the following procedure:

  1. Log in to the database host using an account with privileges that allow you to write to the database home directory and to the Management Agent home directory.

    For each of the commands in this procedure, replace AGENT_HOME with the actual path to the Oracle Management Agent home directory and replace ORACLE_HOME with the path to the database home directory.

  2. Start SQL*Plus and connect to the database using the SYS account with SYSDBA privileges.

    For example:

    $PROMPT> ./sqlplus "connect / as sysdba"
    
    
  3. Enter the following command to run the database dbmon script:

    SQL> @AGENT_HOME/sysman/admin/scripts/db/config/dbmon
    
    

    The script will display the following prompt:

    Enter value for dbm_password:
    
    
  4. When prompted, enter the password for the DBSNMP account.

    The script performs several configuration changes and returns you to the SQL*Plus prompt.

  5. Connect as the DBSNMP user.

    For example:

    SQL> connect DBSNMP
    
    
  6. Enter the following command:

    SQL> @AGENT_HOME/sysman/admin/scripts/db/config/response.plb
    SQL> grant EXECUTE on dbsnmp.mgmt_response to OEM_MONITOR;
    
    
  7. Connect as SYS and enter the following command to create the PERFSTAT user:

    SQL> @ORACLE_HOME/rdbms/admin/spcreate
    

    Note:

    The spcreate script will prompt you for a default tablespace and default temporary tablespace for the PERFSTAT user. Do not specify the SYSTEM tablespace as the default tablespace for the PERFSTAT user. For more information, see "Using Statspack" in the Oracle Database Performance Tuning Guide.

  8. Connect as the PERFSTAT user.

    For example:

    SQL> connect PERFSTAT;
    
    
  9. Enter the following commands from the PERFSTAT user account:

    SQL> define snap_level='6';
    SQL> define cinterval='1';
    SQL> define cjobno='-1';
    SQL> @AGENT_HOME/sysman/admin/scripts/db/config/spset
    
    
  10. Connect as the SYS user and enter the following command:

    SQL> grant OEM_MONITOR to dbsnmp;
    
    
  11. If the database you are modifying is an Oracle8i database, also enter the following commands as the SYS user:

    grant select on sys.ts$ to OEM_MONITOR;grant select on sys.seg$ to OEM_MONITOR;grant select on sys.user$ to OEM_MONITOR;grant select on sys.obj$ to OEM_MONITOR;grant select on sys.sys_objects to OEM_MONITOR;grant select on sys.file$ to OEM_MONITOR;grant select on sys.attrcol$ to OEM_MONITOR;grant select on sys.clu$ to OEM_MONITOR;grant select on sys.col$ to OEM_MONITOR;grant select on sys.ind$ to OEM_MONITOR;grant select on sys.indpart$ to OEM_MONITOR;grant select on sys.indsubpart$ to OEM_MONITOR;grant select on sys.lob$ to OEM_MONITOR;grant select on sys.lobfrag$ to OEM_MONITOR;grant select on sys.partobj$ to OEM_MONITOR;grant select on sys.tab$ to OEM_MONITOR;grant select on sys.tabpart$ to OEM_MONITOR;grant select on sys.tabsubpart$ to OEM_MONITOR;grant select on sys.undo$ to OEM_MONITOR;
    
    
  12. For any supported database version, enter the following command from the SYS account:

    SQL> show parameter job_queue_processes
    
    

    If the output from the show parameter command is zero, then perform the following steps to modify the job_queue_processes initialization parameter:

    If you start the database using an spfile, enter the following command:

    SQL> alter system set job_queue_processes = 2 SCOPE=BOTH;
    
    

    Otherwise, do the following:

    1. Enter the following command:

      SQL> alter system set job_queue_processes = 2;
      
      
    2. Exit SQL*PLUS and update the init.ora database configuration file with the following entry so the parameter will be applied whenever the database is restarted:

      job_queue_processes=2
      
      
  13. Exit SQL*Plus and change directory to the following directory in the home directory of the Management Agent that is monitoring the database:

    AGENT_HOME/bin
    
    
  14. Reload the Management Agent by entering the following command:

    $PROMPT> ./emctl agent reload
    
    
  15. Using the Grid Control Console, return to the Database home page and verify that the Bad SQL and Top SQL Report metrics are now being gathered.

14.4 Modifying the Default Login Timeout Value

To prevent unauthorized access to the Grid Control Console, Enterprise Manager will automatically log you out of the Grid Control Console when there is no activity for a predefined period of time. For example, if you leave your browser open and leave your office, this default behavior prevents unauthorized users from using your Enterprise Manager administrator account.

By default, if the system is inactive for 45 minutes or more, and then you attempt to perform an Enterprise Manager action, you will be asked to log in to the Grid Control Console again.


Caution:

As stated in the previous paragraphs, the timeout value for logging in to the Grid Control Console is defined in order to protect your system from unauthorized logins. If you make changes to the login timeout value, be sure to consider the security implications of leaving your session open for other than the default timeout period.

To increase or decrease the default timeout period:

  1. Change directory to the following location in the Oracle Application Server home directory where the Management Service was deployed:

    IAS_HOME/sysman/config/
    
    
  2. Using your favorite text editor, open the emoms.properties file and add the following entry:

    oracle.sysman.eml.maxInactiveTime=time_in_minutes
    
    
  3. For example, if you want to change the default timeout period to one hour, add the following entry:

    oracle.sysman.eml.maxInactiveTime=60
    
    
  4. Save and close the emoms.properties file.

  5. Restart the Management Service.


    Note:

    The default timeout value does not apply when you restart the Web server or the Oracle Management Service. In both of those cases, you will be asked to log in to the Grid Control Console, regardless of the default timeout value.

14.5 Configuring Clusters and Cluster Databases in Grid Control

This section describes how to configure clusters, cluster databases, and discovering instances.

14.5.1 Configuring Clusters

To add a cluster target that was installed but not discovered as a target automatically during installation, perform the following steps:

  1. Click All Targets from the Targets page.

  2. Select Cluster from the Add menu and click Go. The Add Target: Cluster page appears.

  3. Optional: Specify the cluster name and provide the Clusterware home path if it is installed on the cluster.

  4. To add hosts to the cluster, use the arrow buttons to move items from Available Hosts to Selected Hosts. The hosts you select must not already belong to a cluster.

  5. Click Add to save the cluster target to the targets.xml file on every selected host.


See Also:

The Enterprise Manager online help for more information about configuring clusters

14.5.2 Configuring Cluster Databases

After you have added the cluster target, you can add a cluster database target either from the Databases page or from the All Targets page.

To add a cluster database target, perform the following steps:

  1. In the Enterprise Manager Grid Control Console, select one of the following entry locations:

    • From the Databases page, click Add. The Add Database Instance Target: Specify Host page appears.

    • From the All Targets page, select Database Instance from the Add drop-down menu, then click Go. The Add Database Instance Target: Specify Host page appears.

  2. Specify any host member of the cluster target where the cluster databases reside, then click Continue. The Add Database: Specify Source page appears.

  3. Keep the default option (on all hosts in the cluster) selected and click Continue. This option sends requests to all Management Agents in the cluster to perform discovery.

    After target discovery completes, the newly discovered RAC databases appear in the Targets Discovered on Cluster page. If the databases do not appear, see the Troubleshooting section below.

  4. If the desired targets do not appear in the Cluster Databases table, or if the discovered targets are not configured appropriately, click Manually Add. The Properties page of the Configure Cluster Database wizard appears.

  5. Provide the required values for the Properties table.

  6. You must specify at least one instance in the Instances table. If no instances appear in the table, click Add. The Properties: Add Instance page appears. Provide the required values, then click OK. The Properties page of the Configure Cluster Database wizard reappears.

  7. Click Next. For versions 10.1 and higher, Enterprise Manager bypasses the Install Packages, Credentials, and Parameters steps, and goes directly to the Review page.

  8. Click OK. The Targets Discovered on Cluster page reappears, and displays the newly added cluster database and instances.


See Also:

The Enterprise Manager online help for more information about configuring cluster databases

14.5.3 Discovering Instances Added to the Cluster Database

If you need to configure additional instances, follow these steps:

  1. In Enterprise Manager, click Databases in the Targets page, and navigate to the desired Cluster Database Home page.

  2. Click Monitoring Configuration in the Related Links section. The Properties page of the Configure Cluster Database wizard appears.

  3. Provide the required information in the Properties table at the top of the page.

  4. Examine the Instances table. One or more additional instances may exist, but may not appear in the Instances table. If this is the case, click Add to discover the instance in the cluster database. The Properties: Add Instance page appears.

  5. Provide the required information, then click OK. The wizard Properties page reappears, and displays the added instance view.

  6. Click Check Connection to ensure that the connection is working.


See Also:

The Enterprise Manager online help for more information about discovering instances added to the cluster database

14.5.3.1 Troubleshooting

If you encounter configuration issues, check the following required conditions to ensure that automatic discovery is able to function correctly:

  • The host user running the Management Agent is able to run the SRVCTL utility in the Oracle home and retrieve the database configuration.

  • The host user running the Management Agent is able to connect to the database through SQLPLUS using OS authentication.

  • The Oratab (UNIX) or Registry (Windows) contains information about the database.

If automatic discovery still does not resolve your configuration issues after you have ensured the conditions previously listed, you can manually configure cluster databases (see Section 14.5.2, "Configuring Cluster Databases").

For more information about configurations for Oracle Enterprise Manager Grid Control, see Chapter 3, "Grid Control Common Configurations".

14.6 Collecting Client Configurations

A client is comprised of a host and operating system user. Client configuration data that is collected includes:

14.6.1 Configuring the Client System Analyzer

The Client System Analyzer (CSA) allows Web server administrators to collect and analyze end-user client data. The client data is collected by an applet, diagnosed and sent back to the CSA application. The Oracle Management Agent uploads this data to the Enterprise Manager Management Repository. After the client configuration data has been collected by the client configuration collection applet and written to the Web server directory specified by the CSA applet, the client configuration data is uploaded to the Oracle Management Repository.

You can either use the Client System Analyzer in the Grid Control application pre-installed with Enterprise Manager or you can deploy CSA independently to your Web server.

14.6.1.1 Client System Analyzer in Oracle Grid Control

Client System Analyzer in Grid Control - An instance of CSA is pre-installed with Enterprise Manager. If you use this option, you can collect client data without setting up a separate Web server. To activate the pre-installed CSA application in Enterprise Manager, click Deployments. Then click Client System Analyzer in Grid Control and use the button provided to activate the application. Once CSA is activated, end-users can use the URL provided to run the CSA applet. The CSA applet can collect base client configuration information from client systems and Oracle Collaboration Suite client information from Oracle Collaboration Suite client systems.

  • To download the CSA applet and have it collect base client configuration information, a client should use the Client System Analyzer URL in this format: http[s]://management-service-host:port/em/public/ecm/csa/CSA

  • To download the CSA applet and have it collect Oracle Collaboration Suite client configuration information, a client should use the Client System Analyzer URL in this format: http[s]://management-service-host:port/em/public/ecm/csa/CSA?application=OCS

14.6.1.2 Deploying Client System Analyzer Independently

The Client System Analyzer Application can be deployed independently to any J2EE-capable Web server. Click the Deployments tab. Then click Getting Started with Client System Analyzer and click Deploy Client System Analyzer Application. Follow these steps to deploy the CSA applet and collect the client configuration data.

    1. Download the CSA Application:

      The CSA application includes the CSA directory along with the necessary JSP applet files. The application is packaged as an EAR file. To download this default EAR file, click Download Client System Analyzer Application. You can customize the default CSA EAR file by modifying the following:

      • Rules - This file contains a default set of rules against which the client data is evaluated. You can customize and add rules before deploying CSA.

      • Context parameters - You can customize the context parameters in the web.xml file.

      • Custom classes - You can provide customized applet classes that can be used to perform tasks like collecting additional data, changing the behavior of the applet, and performing certain operations on the client.

    2. Deploy CSA to any J2EE Web server.

      The CSA application is deployed on an Application Server as a regular J2EE application. Once the CSA application is deployed, context parameters can be changed similar to other web applications.

    3. Direct users to the CSA.

      In order for the client data to be collected, the user must access the CSA application. Users can access the CSA JSP page directly or by using a link from another application. Users can be automatically redirected to CSA using the following methods:

      • HTTP Server (Apache's mod_rewrite) - This option does not require changes in the Web application.

      • Servlet Filter - A servlet filter is a program that filters requests to and from the server. The CSA_filter.jar file contains the servlet filter classes. The servlet filter and the filter mapping need to be added to the Web application.

      • CSA Redirection JSP - The CSA Redirection JSP (CSARedirect.jsp) page can be included into the Web application.

    4. Configure Enterprise Manager.

      Collected client data is recorded in the Receive File Directory on the Web server. To upload the collected client data into Enterprise Manager, you need to do the following:

      • Add a CSA Collector Target to the Enterprise Manager Management Agent. To do so, click Add Collector and choose a target from the list.

      • Specify the absolute path to the Receive File Directory. The path specified must be the same as the path specified in the outputDir parameter of the CSA application. By default, the client data is stored in the Receive File Directory "csa_results" under the context root of the Client System Analyzer Web application, but this can be configured by changing the applications's "outputDir" context parameter.

    5. Test the CSA Deployment.

      To verify the CSA deployment, click the URL of the CSA page and check if the client data is collected.

14.6.2 Configuration Parameters

The Client System Analyzer (CSA) can be further configured by modifying the context parameters in the CSA application's WAR file.

Table 14-1 Configuration Parameters

Parameter Description Default Value

alertWhenDone

If set to true, a message indicating that the applet has been executed is displayed.

false

appletJAR

The name of the JAR file.

CSA.jar

application

The name of the application associated with this CSA instance. If the application parameter value is not specified, then the Collection Tag has a value of Default.

none

autoRedir

If set to "true", this causes the CSA JSP page to automatically use the Sun JVM if JVM was set to JInitiator and the client does not have the appropriate version of JInitiator installed.

false

bwTestFile

The name of the file that is downloaded from the server during the bandwidth test.

CSA.mb (included with CSA)

bwTestMsec

The amount of time the applet should spend on the bandwidth test. The applet computes bandwidth by counting the number of bytes it can download in this interval.

200 ms

classid

The "classid" field for the OBJECT tag. Applicable only if JVM is set to "JInitiator." The classid for Sun is "clsid:8AD9C840-044E-11D1-B3E9-00805F499D93"codebase - the "codebase" field for the OBJECT tag. Applicable only if JVM is set to "JInitiator."

None – this field MUST be set if JVM is set to "JInitiator," and is ignored otherwise

codebase

The codebase field for the OBJECT tag. Applicable only if the JVM is set to "JInitator".

The default for Sun is http://java.sun.com/products/plugin/autodl/jinstall-1_4_2-windows-i586.cab#Version=1,4,0,0

collectCookie

The list of the names of cookies to be collected. This parameter is a comma-separated list of cookie names. Only cookies for the current OS user in the current browser will be collected. The Administrator can specify asterisk (*) to collect all of the current user's cookies for the current browser.

If this field is not present, no cookies will be collected.

cookieDomain

The domain of the CSA cookie.

If either the domain or path of the cookie is not set, cookies are disabled

cookieMaxAge

The maximum duration, in seconds, of the cookie on the client machine.

1 year

cookiePath

The path of the CSA cookie

If either the domain or path is not specified, cookies are disabled.

customClass

The name of the class used to collect custom data.

none – the default behavior is for no custom code to be executed

customKey1customKey2customKey3

The values of the three custom keys. All client collections done by a CSA JSP page that uses this deployment descriptor will have these values for the custom keys. These values can be overridden by custom code.

If no custom key values are specified, none will be collected (unless they are collected by custom code)

descriptionFile

The full path of a text file containing the description that will be displayed on the deployment page. The contents of the file should be HTML-formatted text.

None

destURL

Specifies the destination URL. This is the URL to which the "Proceed" button on the CSA JSP page is linked.

If no destURL is specified, the "Proceed" button will take the user to the referring page; if there is no referring page, the "Proceed" button will not be displayed.

destURLResultsParam

Specifies the name of the URL parameter that will be added to the "destination URL" to indicate the client's compliance level. For example, if the value was "compliance", and the client's overall compliance level was critical, then the parameter "compliance=critical" would be added to the destination URL.

Sun

JVM

This determines the type of JVM that is to be used. If the value is ""Sun," the JSP page will direct the browser to use the Sun JVM. If the value is "Oracle," the page will direct the browser to use Oracle Jinitiator. If the value is "any," the JSP will write out the standard "applet" tag, which causes the client to use whichever JVM is plugged into the browser.

Sun

maxExecInterval

Parameter that is added to CSA cookie payload. When the redirection logic reads the cookie, if the timestamp of the cookie differs from the current time by more than this value, the applet is deployed again. This parameter can be overridden by the "csa execInterval" context parameter in the redirection JSP filter.

90 days

maxFileSize

Maximum amount of data, in KB, that can be posted back to the receiver in a single request. If the size of the posted data exceeds this limit, the request is rejected and any data already written to the hard drive is deleted.

100

maxOutputFiles

Maximum number of output files that can be present in XML OutputDir.

100

outputDir

Directory to which CSA configuration xml files will be written. Both the applet page and the receiver page must read this parameter, and this parameter must be identical for both pages.

By default, the output files are written into the "csa_results" subdirectory of the application root directory (if the application root directory exists, and if the subdirectory exists or can be created). Using the default value for this parameter is not recommended.

outputEnabled

Enables or disables creation of output XML files. Applicable to both applet and receiver pages.

By default, the XML files are created and stored in the XMLOutputDir.

pluginspage

Used to direct the user to the JVM installer under Netscape, since Netscape does not support automatic installation. Applicable only if JVM is Jinitiator. Default for Sun is http://java.sun.com/products/plugin/index.html#download

none - This field must be set if JVM is set to "JInitiator" and is ignored otherwise.

receiver

The URL to which the applet should post the collected data.

Note: When setting this parameter, the administrator must ensure that the version of the receiver is the same as the version of the applet.

Default is to look for "CSAr.jsp" in the same path as the CSA JSP page

ruleFile

Specifies the path on the server, relative to the web application root, of the file that contains the rules to be evaluated.

rules.xml

script

Specifies a script, provided by the administrator, which can be run on the CSA XML file before it is marked for upload by the agent.

none - If no script is specified, no script will be run.

type

The type field for the OBJECT tag rendered by the CSA JSP page to deploy the applet. This is only applicable if the JVM is set to JInitiator. If the JVM is set to Sun, the type is application/x-java-applet.

none - this field must be set if JVM is set to "JInitiator," and is ignored otherwise

viewData

If set to true, this parameters allows the end-user to view the collected data after it is posted to the server.

false


In addition to these parameters, the CSA redirection parameters can also be configured. Redirection can be enabled either by using a servlet filter or by including a CSA redirection JSP file in some other page. The following context parameters must be available for the redirection to work.

Table 14-2 Configuration Parameters

Parameter Name Description Default Value

csaURL

The URL of the CSA JSP page to which the user should be redirected.

No default: This value must be set or redirection cannot work.

execInterval

The interval, in seconds, between executions of CSA. If the difference between the cookie's age and the current server time is greater than execInterval, the user is re-directed.

None. If the execInterval is not set, then the user is only redirected if there is a CSA cookie.

redirectURL

The URL to which the user should be directed after CSA has executed

None.

If this parameter is not set, the user is directed back to the originally requested page

UIMode

0 - synchronous (in the current browser window)

1 - asynchronous visible

2 - asynchronous invisible

synchronous


14.6.2.1 Associating the Parameters with an Application

In certain cases, different sets of parameters may be required for different applications. For example, two different applications may have different rule sets and custom code, and the administrator may want to associate them with different CSA Collector Targets. In this scenario, the administrator can specify the ruleFile, appletJar, script, and outputDir parameters for a particular application by using the context parameters <application name> ruleFile, <application name> appletJar, and so on. If an application is specified, either as a context parameter or through the URL, then CSA is executed using the parameter values specific to the application. If no application is specified, or if one of the parameters for an application is not overridden, the default parameters are used.

14.6.3 Rules

Custom rules can be supplied to the CSA application so that the users receive immediate feedback as to whether their systems satisfy certain constraints. A sample RULES file is shown in Example 14-1 followed by a description of each tag contained in the file.

Example 14-1 Sample RULES

<RULES>
<RULE>
<NAME>Client has sufficient memory</NAME>
<DESCRIPTION>Checks to see if the client has enough memory to run the application</DESCRIPTION>
<VIOLATION> //ROWSET[@TABLE='MGMT_ECM_HW']/ROW/AVAIL_MEMORY_SIZE_IN_MB[number() &lt; $arg=SIZE$] </VIOLATION>
<SEVERITY level="CRITICAL">
<PARAM id='SIZE'>100</PARAM>
<MOREINFO>
<TEXT>Application cannot run with less than 100 MB. </TEXT>
</MOREINFO>
</SEVERITY>
<SEVERITY level="WARNING">
<PARAM id='SIZE'>150</PARAM>
<MOREINFO>
<TEXT>Approaching minimum memory level</TEXT>
</MOREINFO>
</SEVERITY>
</RULE>
</RULES>

Example 14-1 demonstrates a rule that can be used to check whether or not the client has sufficient memory to run the application. The <VIOLATION> is an XPATH expression that the applet will evaluate against an XML file that contains all of the data it has collected. Since the violation is an XPATH expression embedded in an XML file, certain characters in the XPATH, such as '<', '>', and '&', must be replaced with entities. If the XPATH expression returns a non-null node set, the rule has failed. In this case, the rule will fail if the client's available memory is less than a certain amount. The actual amount that triggers a violation can be configured by using different severity levels.

In Table 14-3, the applet will first replace the substring "$arg=SIZE$" in the VIOLATION expression with "100" and then evaluate the expression. If the client's available memory is less than 100 MB, then the rule will fail with critical status. The applet will indicate the status along with the message "Application cannot run with less than 100 MB of memory". If the rule passes through successfully, the applet will then replace "$arg=SIZE$" with 150 and try again; if the rule fails, the applet will display the message "Approaching minimum memory level." If the applet goes through all specified severity levels and does not find a violation, the rule is successful.

Table 14-3 Tags in the RULES File

Tag Name Description

RULES

This is the top-level tag for the XML file

BUNDLE

This tag specifies the resource bundles used for translation. The value of the tag is either the name of a file or a Java class name. The rule engine reads this string and first attempts to find a file in the applet JAR that has this name. This file is expected to contain a mapping of resource IDs to strings in various languages. If such a file does not exist, then the string is treated as the name of a Java resource bundle class. Strings in a resource bundle are referenced using the syntax <resource id>@<bundle id>.

PRECONDITION

This tag is used to specify an XPATH expression that must return a non-null node set in order for a rule to be evaluated. The "id" attribute specified the ID of the precondition. A rule can specify a list of preconditions that should be evaluated by listing their IDs.

RULE

This tag represents an individual node that is to be evaluated. The rule's severity is specified using a <SEVERITY> tag. At least one severity tag must be specified for a rule. The tag has an optional "precondition" attribute, which is used to specify a list of precondition IDs separated by commas. Before the rule is evaluated, all of the preconditions must be met. If the pre-conditions are not met, the rule has a status of "Not Applicable" and is not displayed in the client UI at all. The children of a RULE tag are NAME, DESCRIPTION, VIOLATION, SEVERITY, and MOREINFO.

NAME

This tag specifies the name of the rule and identifies the tag in the repository.

Note: This tag must contain a value and cannot be blank.

DESCRIPTION

This is the description of the rule.

VIOLATION

This tag lists the violations that are to be checked for a given rule. The violation is specified in the CSA Condition Language.

SEVERITY

A rule can have three severity levels: INFO, WARNING, and CRITICAL. The SEVERITY node must contain a number of ARG children equal to the number of arguments that can be accepted by the expression in the VIOLATION node. When the rule engine evaluates a rule, it evaluates the condition in VIOLATION for each of the sets of arguments specified in the severity levels, starting with CRITICAL and moving down in order of severity. As soon as the engine encounters a condition that fails, the rule is declared a failure, with a severity level equal to the severity level of the argument that caused the failure. If the conditions for all specified levels are met, the rule passes.

PARAM

This tag specifies the value of an argument that should be substituted into an expression. The 'id' attribute of the tag must match the name of one of the arguments in the expression.

MOREINFO

This tag specifies the information that is displayed if the user clicks the "more information" button that is displayed next to a failed rule. The children of MOREINFO are TEXT and ARG.

Note: The MOREINFO node can be a child either of the severity node (in the case where multiple severities are specified) or of the rule itself.

TEXT

This tag specifies the text to be displayed when the "More Info" button is clicked. The "resource" attribute specifies a string in a resource bundle – if this string is not present, the value of the node is displayed instead. The text (either in the resource bundle or in the node itself) can specify a location for arguments to be inserted by using "{0}", "{1}", and so on. In this case, the expressions in the ARG nodes are evaluated and inserted into the text in the order in which they are specified. If there are more ARG nodes specified than there are slots in the string, the extra nodes are ignored.

ARG

This tag specifies an expression in the CSA Condition Language that can be evaluated and inserted into the MOREINFO text.



See Also:

Enterprise Manager online help associated with the Getting Started with CSA page

14.6.4 Customization

In addition to writing custom classes to collect custom properties, the administrator can also specify custom properties in the deployment descriptor. Custom property names are specified by including a context parameter of the form csa value_<name>. The <name> field of the context parameter name is treated by the Client System Analyzer (CSA) as the custom property name, and the value of the parameter is treated as the custom property value. Similarly, administrators can specify the type, type_ui, name_ui, display_ui, and history_tracking fields for a custom property by using csa_type_<name>, csa_type_ui_<name>, csa_name_ui_<name>, csa_display_ui_<name>, and csa_history_tracking_<name> parameters, respectively. Custom properties can also be specified on the CSA Applet URL, using the same naming convention.

14.6.5 CSA Deployment Examples

The following sections outline sample use cases for client configurations.

14.6.5.1 Using Multiple Collection Tags

An administrator can check the compatibility of users with two distinct Web applications. The first is an online teaching website that delivers content using a number of various plug-ins, allowing an administrator to be sure that all users have the required installed plug-ins. The second is a software distribution portal that allows an administrator to ensure that all users downloading software from the portal have the required hardware and operating system. In this case, though both applications require their own set of rules, the administrator can use a single CSA instance for both applications through the use of collection tags displayed in the following list:

  1. Choose a collection tag for each application, such as "teaching" and "distribution".

  2. Create two separate rule files, one for each application.

  3. Use context parameters to map each rule file to the corresponding application, as shown in Example 14-2.

  4. Create the appropriate links from each application to CSA. The links from the teaching and distribution applications should have "application=teaching" and "application=distribution", respectively, in the query string. This ensures that users of each application have the correct collection tags when running CSA.

Example 14-2 Using Collection Tags for Selecting a Rule File

<context-param>
  <param-name>csa teaching ruleFile</param-name>
  <param-value>teaching_rules.xml</param-value>
</context-param>
 
<context-param>
  <param-name>csa distribution ruleFile</param-name>
  <param-value>distribution_rules.xml</param-value>
</context-param>

Example 14-2 shows only the use of collection tags for selecting a rule file. However, collection tags can be used for any of the CSA context parameters.

Collection tags also affect how client configurations are stored in the Enterprise Manager Management Repository. If the user comes to CSA using the link from the teaching application in Example 14-2, then in addition to running the rules for the "teaching" collection tag, CSA also causes this tag to be stored with the client configuration data in the Management Repository. The collection tag forms part of the unique identifier for the client configuration, which makes it possible for a single client to have multiple configurations in the Management Repository, each with its own tag. Collection tags can be associated with Enterprise Manager targets in order to restrict access to client data; an Enterprise Manager user can only view a client configuration if he or she has view privileges on a target that is associated with the collection tag for that client configuration.

In Example 14-2, suppose that host H1, application server A1, and database D1 are used to host the teaching application, while host H2, application server A2, and database D2 are used for the distribution application. All 6 targets are monitored by Enterprise Manager, with user X having access to A1, H1, and D1 and user Y having access to A2, H2, and D2. Since each of the two Enterprise Manager users is monitoring the resources used for one of the applications, it may also make sense to have each user also monitor the application's clients. In that case, an Enterprise Manager super user would associate the "teaching" tag with A1, D1, or H1 and associate the "distribution" tag with A2, D2, or H2. This allows user X to see all client configurations with the "teaching" tag and user Y to see all configurations with the "distribution" tag.

14.6.5.2 Privilege Model for Viewing Client Configurations

Collection Tags are used to restrict access to client data in Enterprise Manager. A client configuration is visible to the user only if the Collection Tag for that configuration is associated with a target on which the user has View privileges. For example, if collection tag C is associated with target T1, then only those users that can view target T1 will be able to see client configurations that have tag X. In Example 14-2, user X will be able to see client configurations with the "teaching" tag because user X has view privileges on targets that are associated with the "teaching" tag. However, user X will not be able to see any client configurations with the "distribution" tag because that tag is not associated with any targets that user X can see. Super users can associate collection tags with targets by using the Collection Tag Associations page, which can be accessed from the Deployments tab or from the Client System Analyzer in Grid Control link on the Setup page. Super users can view all client configurations regardless of any collection tag associations.

14.6.5.3 Using the Customization API Example

If the administrator is interested in the user's settings for an e-mail client in addition to the normal CSA data, the administrator can add this information to the other data collected by CSA through the use of the customization API, as shown in Example 14-3.

  1. Create the Java classes required to gather the information. The administrator can create as many classes as necessary, but there must be at least one class that implements oracle.symsan.eml.ecm.csa.CSAResultInterface and one that implements oracle.sysman.eml.ecm.csa.CSACustomInteface, both of which are shown in Example 14-3. Assume that the former is acme.csa.custom and the latter is acme.csa.result.

  2. Set the value of the "customClass" parameter in CSA to "acme.csa.custom"

    Example 14-3 Customization API

    public interface CSACustomInterface {
     
        /**
         * requires: none
         * effects: returns a CSAResultInterface object that may contain custom
         * properties. Other effects are determined by the customActions method
         * in the implementing class
         * modifies: unknown - dependent on implementing class.
         * @param inputData contains client config data collected by default, plus
         * applet parameters, etc.None of the data in the inputData is guaranteed
         * to be there as there could have been collection errors. 
         * @return a data structure that may contain custom properties
         */
        CSAResultInterface customActions(CSAInputInterface inputData);
    }
     
    public interface CSAResultInterface {
     
        /**
         * requires: none
         * effects: returns an array of custom properties
         * modifies:none
         * @return String[][7] where ...
         *
         * String[i][0] is a name 
         * String[i][1] is a value of the i-th row. (Type and name must be unique.)
         * String[i][2] is a type/category of data (could be null),
         * String[i][3] is the displayed value of the name of the property
         * String[i][4] is the displayed value of the type of the property
         * String[i][5] indicates data item (ie "Y") whose history should be computed
         * String[i][6] indicates data item (ie "Y") should be displayed in default UI
         */
        String[][] getResultsData();
    }
     
    public interface CSAInputInterface {
     
        /**
        * Get data value for given name
        * requires: name is not null
        * effects: returns the data value associated with the name
        * modifies: none
        * @param name the name of the key whose value is to be returned
        * @return the value assocaited with name
        *
        */
        String getDataValue(String name);
     
        /**
        * Get table-formatted data.
        * requires: name is not null
        * effects: returns the table with this name
        * modifies: none
        * @param name the name of the table
        * @return the rows of the child tables
        *
        */
        CSAInputInterface[] getDataTable(String name);
    }
    

    The additional data collected by the custom code will be stored in the table MGMT_ECM_CSA_CUSTOM. To add data to this table, the custom code returns it in an object that implements CSAResultInterface. The custom code can also manipulate the normal data collected by CSA by modifying the CSAInputInterface object passed to the customActions method by the applet.

    Since the custom code is executed before rules are evaluated, the administrator can also write rules based on the custom data. For example, if the administrator wants to write a rule that raises a critical error if the user does not have the correct IMAP server set up his or her e-mail client, the administrator would write custom code that retrieves the IMAP server settings and stores in them in the MGMT_ECM_CSA_CUSTOM table and then writes a rule that checks these values.

14.6.5.4 Using the CSA Servlet Filter Example

Since CSA does not involve the use of a Management Agent on the user's machine, there is no way to keep the data in the Management Repository up to date unless end users run CSA periodically. One way to ensure that they do is to check whether or not users have run CSA recently, and if they have not, to inform them to run CSA again. This check can be accomplished using the CSA servlet filter provided by Oracle.

The CSA servlet filter works by checking the cookie that CSA sets in the user's browser whenever it runs. The payload of this cookie indicates the time at which CSA was last run. To use the filter, the administrator places it in front of some frequently accessed application, such as an employee portal. The administrator then sets the interval at which he or she wants users to run CSA. Whenever a user tries to connect to the portal application, the filter intercepts the request and checks the CSA cookie. If the cookie is not present or if it is older than the execution interval specified by the administrator, the user is directed to the CSA page; if not, the user is allowed to proceed to the application.

Assume that Acme Corporation has a CSA instance deployed at www.acme.com/csa/CSA.jsp. Assume also that the company has a portal at www.acme.com/portal that can be used by employees to check e-mail, access their personal information, or display news about the company. Because the portal is accessed frequently by employees, the administrator at Acme decides that the portal can be used to keep CSA data up to date. The administrator would take the following steps:

  1. Download the CSA servlet filter classes. These classes are contained in a JAR file, CSA_filter.jar, which can be downloaded from the "Deploy Client System Analyzer" page in the Enterprise Manager Grid Control Console.

  2. Place the JAR file in the WEB-INF/lib directory of the application to which the filter will be applied.

  3. Specify context parameters for the filter. In this case, the administrator wants users to run CSA every 30 days and return to the portal homepage after CSA has finished.

    <context-param>
      <param-name>csa csaURL</param-name>
     <param-value>www.acme.com/csa/CSA.jsp</param-value>
    </context-param>
     
    <context-param>
      <param-name>csa execInterval</param-name>
      <param-value>2592000</param-value>
    </context-param>
    
    

An alternative is to have CSA run in a separate browser window in the background. This can be set up by using the csa_uiMode parameter. If the parameter is set to 1, the filter will open a new browser window that is the same size as the original window and go to the CSA page. If the parameter is set to 2, CSA will run in "invisible" mode; in this case, the filter will open a new browser window and immediately minimize it, and it will close the window as soon as CSA has completed.

14.6.5.5 Sample Deployments

In the following sample deployment examples, there are three primary actors. The first is the CSA administrator, who is responsible for setting up CSA. The second is the Enterprise Manager user, who will be viewing the client data in Enterprise Manager. The third is the end user, whose data is being collected by CSA.

14.6.5.5.1 Example 1: Helpdesk

In this example, the CSA administrator is using CSA to support the operations of a helpdesk. End users who have problems running a particular application can call customer support, and the customer support technician can, if necessary, instruct the user to go to a particular URL and run CSA. The Enterprise Manager users are the support personnel who will use the data collected by CSA to assist the end user. To speed up the process of diagnosing the customer's problem, the CSA administrator creates some rules in a file called "rules.xml" so that the helpdesk personnel can quickly identify potential problems. In the simplest case, suppose that the helpdesk is being set up to provide support for a single application. The application is running on an application server on host application.acme.com, which has an Enterprise Manager Management Agent installed on it that sends data back to the Management Service at oms.acme.com/em. The helpdesk personnel who will be looking at client data can log into Enterprise Manager as the user "helpdesk," which does not have super user privileges.

  1. The CSA administrator adds rules.xml to the CSA.war file contained in CSA.ear.

  2. Deploy the EAR file to the application server using the Application Services Control Console.

  3. Use the Application Services Control Console to set the necessary context parameters, such as ruleFile and outputDir.

  4. Optionally, the administrator can choose a collection tag for the CSA data by specifying a value for the "application" context parameter. If no tag is chosen, the tag "Default" will be used.

  5. An Enterprise Manager user with super user privileges adds a CSA Collector Target to the Management Agent on application.acme.com and sets its receive file directory to the directory specified in the "outputDir" parameter of CSA.

  6. An Enterprise Manager superuser creates the collection tag associations needed to allow the helpdesk users to look at the data. For example, the superuser could associate the tag "Default" with host application.acme.com and then give the "helpdesk" Enterprise Manager user view privileges on the host.

With the setup previously described, when a user calls the helpdesk to ask for support with the application, the helpdesk technician can instruct the user to run CSA from the appropriate URL on application.acme.com. The Management Agent collects the data after a certain interval and loads it into the Management Repository. The helpdesk technician can then log into Enterprise Manager as "helpdesk" and find the customer's information by searching for an identifying field such as the customer's operating system user name or host name. By default, the Management Agent will check the output directory for new data every two minutes, but this interval can be shortened by editing the file $ORACLE_HOME/sysman/admin/default_collection/oracle_csa_collector.xml.

14.6.5.5.2 Example 2: Inventory

In Example 14-4, a system administrator is in charge of keeping track of the hardware and software used by employees in two different departments, Human Resources (HR) and Sales. This administrator serves as both the Enterprise Manager user and the CSA administrator. The setup for this case is similar to the one described in the example on using servlet filters, but in this case, each department has its own portal application, at hr.acme.com/portal and sales.acme.com/portal, respectively. The administrator sets up an application server on host server1.acme.com and deploys CSA with the URL http://server1.acme.com/csa/CSA.jsp. A Management Agent on server1.acme.com collects data and sends to a Management Server at oms.acme.com/em. The administrator would like to collect data once every 30 days and to have CSA run in invisible mode. The administrator would also like to distinguish data from the two different departments by using two separate collection tags, "hr" and "sales." The administrator can log into Enterprise Manager as sysman and will thus be able to see clients with both tags.

The administrator arranges to have users directed to CSA by deploying the CSA servlet filter on both applications. Most of the filter context parameters for the two applications will be identical. However, because each application corresponds to a different tag, the values of the "csa csaURL" parameter will be slightly different. For the HR portal, the value would be http://server1.acme.com/csa/CSA.jsp?application=hr, and for the sales portal, the value would be http://server1.acme.com/csa/CSA.jsp?application=sales.

Example 14-4 Inventory Code

<context-param>
  <param-name>csa csaURL</param-name>
 <param-value>www.acme.com/csa/CSA.jsp?application=sales</param-value>
</context-param>
 
<context-param>
  <param-name>csa execInterval</param-name>
  <param-value>2592000</param-value>
</context-param>
 
<context-param>
  <param-name>csa uiMode</param-name>
  <param-value>2</param-value>
</context-param>

Under this setup, users in the HR department who are directed to CSA from the HR portal will have the tag "hr," and users from the sales department will have the tag "sales". Thus, if the administrator wants to see information about only hardware on machines in the HR department, he or she can simply use the "Collection Tag" filter on the Client Configurations page in Enterprise Manager and set it to "hr".

14.6.5.5.3 Example 3: Problem Detection

In this example, the goal is to use CSA to inform end users of potential problems they may experience while running an application. The setup is similar to the one used in Example 2. In this example, however, the CSA administrator creates rules for each application. In addition, the administrator wants CSA to run in the original browser window to ensure that end users are aware of any potential problems.

Example 14-5 displays the context parameter values for the CSA servlet filter on the sales portal.

Example 14-5 Context Parameter Values for CSA Servlet Filter

<context-param>
  <param-name>csa csaURL</param-name>
 <param-value>www.acme.com/csa/CSA.jsp?application=sales</param-value>
</context-param>
 
<context-param>
  <param-name>csa execInterval</param-name>
  <param-value>2592000</param-value>
</context-param>
 
<context-param>
  <param-name>csa uiMode</param-name>
  <param-value>0</param-value>
</context-param>

Example 14-6 represents the context parameter definitions to map rules to collection tags.

Example 14-6 Context Parameter Definitions Mapping Rules to Collection Tags

<context-param>
  <param-name>csa sales ruleFile</param-name>
  <param-value>sales_rules.xml</param-value>
</context-param>
 
<context-param>
  <param-name>csa distribution ruleFile</param-name>
  <param-value>hr_rules.xml</param-value>
</context-param>