18 Additional Configuration Tasks

18.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 18.5.2, "Configuring Cluster Databases").

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

18.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

18.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.

18.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.

18.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 18-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.

<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 18-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 18-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 18-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.

18.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 18-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.

18.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 18-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 18-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 18-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.

18.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.

18.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.

<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>

<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>

<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>