20 Additional Configuration Tasks

This chapter contains the following sections:

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 section provides more information about how these settings are saved.

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

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, follow these steps:

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

    $ORACLE_HOMEsysman/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 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.

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 status agent provides the values of the Management Agent's binaries and state locations.

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;
    

    Note:

    The above script should not be run on an Oracle database of version 8.1.7 or prior. Oracle does not support SQL Response Time for 8.1.7 databases or prior.
  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 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.

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 Fusion Middleware 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.

Configuring Clusters and Cluster Databases in Grid Control

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

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

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

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

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 Configuring Cluster Databases).

Collecting Client Configurations

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

  • Hardware for the client.

  • Operating system (includes information such as operating system properties, file systems, and patches) for the client.

  • Operating system-registered software.

  • Network data, which includes:

    • Latency to the Web server

    • Bandwidth to the Web server

  • Client-specific data items that describe the configuration of the browser used to access the client configuration collection applet, which includes:

    • Browser type (vendor)

    • Browser version

    • JVM vendor (of the JVM used to run the client configuration collection applet)

    • JVM version (of the JVM used to run the client configuration collection applet)

    • Proxy server (if specified)

    • Proxy server exceptions

    • Browser cache size (MB)

    • Browser cache update frequency

    • Supported HTTP version

  • Other client-oriented data items, including: 

    • Client configuration collection applet identifier (version, defined in the applet code)

    • Application URL (from which the client configuration collection applet was accessed)

    • Boot drive serial number (not available from diskless systems)

    • Collection timestamp (from the client configuration collection applet JSP)

    • Collection durations, in milliseconds

    • Client IP address

    • Effective client IP address - if a network proxy server is being used between the client and the Web server providing the client configuration collection applet, the effective client IP address will be the IP address of the proxy server.

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.

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

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.

Configuration Parameters

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

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


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.

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 20-1 followed by a description of each tag contained in the file.

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

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.

CSA Deployment Examples

The following sections outline sample use cases for client configurations.

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

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

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

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.

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.

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.

Example 2: Inventory

In Example 20-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 20-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.

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 20-5 displays the context parameter values for the CSA servlet filter on the sales portal.

Example 20-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 20-6 represents the context parameter definitions to map rules to collection tags.

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

Configuring Privilege Delegation Providers

A privilege delegation provider is defined as a program that allows a logged in user to perform an activity with the privileges of another user. Typically, the privileges that are granted to a specific user are administered centrally.

Enterprise Manager preferred credentials allow you to use two types of privilege delegation providers:

  • Sudo

    Sudo allows a permitted user to execute a command as the super user or another user, as specified in the sudo user administration file (sudoers). If the invoking user is root or if the target user is the same as the invoking user, no password is required. Otherwise, sudo requires that users authenticate themselves with a password by default.

    Note:

    (In the default configuration, this is the user's password, not the root password.

    Sudo determines who is an authorized user by consulting the file /etc/sudoers file. Once a user has been authenticated, a timestamp is updated and the user may then use sudo without a password for a short period of time (5 minutes unless overridden in the sudoers file).

  • PowerBroker

    Symark PowerBroker enables UNIX system administrators to specify the circumstances under which other users may run certain programs such as root (or other important accounts). The result is that responsibility for such actions as adding user accounts, fixing line printer queues, and so on, can be safely assigned to the appropriate people, without disclosing the root password. The full power of root is thus protected from potential misuse or abuse. For example, modifying databases or file permissions, or erasing disks.

    Symark PowerBroker can access existing programs as well as its own set of utilities that execute common system administration tasks. Utilities being developed to run on top of Symark PowerBroker can manage passwords, accounts, backups, line printers, file ownership or removal, rebooting, logging people out, killing their programs, deciding who can log in to where from where, and so on. They can also provide TCP/IP, Load Balancer, cron, NIS, NFS, FTP, rlogin, and accounting subsystem management. Users can work from within a restricted shell or editor to access certain programs or files as root.

    For additional information about Sudo or PowerBroker, see their respective product documentation.

Using Enterprise Manager's command line interface (EMCLI), you can set/edit privilege delegation provider properties for a host. See the Oracle Enterprise Manager Command Line Interface guide for more information. See your privilege delegation provider documentation for detailed setup and configuration information.

Creating a Privilege Delegation Setting

A privilege delegation setting can be created using the EM CLI command line interface's create_privilege_delegation_setting verb.

You can also configure a host with a Privilege Delegation setting, apply a Privilege Delegation setting template or unconfigure the Privilege Delegation setting by clicking Setup on the Enterprise Manager home page and then choosing Manage Privilege Delegation Settings from the left menu panel.

Creating a Sudo Setting Using EMCLI

Use the create_privilege_delegation_setting EMCLI verb to create a sudo privilege delegation setting. For explicit syntax and examples, see EMCLI command line help or the Oracle Enterprise Manager Command Line Interface guide.

Variables

You can used the following variables when using EMCLI to set the privilege delegation settings. Variables are case-sensitive.

Variable Definition
%RUNAS% Run the command as this user.
%USERNAME% Name of the user running the command.
%COMMAND% Sudo Command

Syntax

emcli create_privilege_delegation_setting -setting_name=sudo_setting_1 -setting_type=SUDO -settings="SETTINGS:<command to be used with all the options>"

The following example illustrates using EMCLI to create a sudo setting. Here, sudo is installed in /opt/sudo/bin.

Example 20-7 Using EMCLI to Create a Sudo Setting

>emcli create_privilege_delegation_setting -setting_name=sudo_setting_1 -setting_type=SUDO -settings="SETTINGS:/opt/sudo/bin/sudo –S –u %RUNAS% %command%"

Creating a PowerBroker Setting Using EMCLI

Use the create_privilege_delegation_setting EM CLI verb to create a PowerBroker privilege delegation setting.

Variables

You can used the following variables when using EMCLI to set the privilege delegation settings. Variables are case-sensitive.

Variable Definition
%RUNAS% Run the command as this user.
%USERNAME% Name of the user running the command.
%COMMAND% Sudo Command
%PROFILE% Use this profile to run the command

Syntax

>emcli create_privilege_delegation_setting -setting_name=powerbroker_setting_1 -setting_type=POWERBROKER -settings="SETTINGS:<command to be used with all the options>;[PASSWORD_PROMPT_STRING,<password prompt for PowerBroker>]"

Example 20-8 Using EMCLI to Create a Sudo Setting

./emcli create_privilege_delegation_setting -setting_name=sudo_setting_1 -setting_type=SUDO -settings="SETTINGS: /opt/powerbroker/bin/pbrun –u %RUNAS% %command%"

Note:

In this example, PowerBroker is installed in /opt/powerbroker directory and its password prompt is "Password:".

Applying Privilege Delegation Settings

Once you have created a privilege delegation setting, you must apply this setting to selected targets. As with the setting creation process, you use EMCLI to apply the privilege delegation setting to specified targets. The setting can be applied to one or more hosts or to a composite (Group) target (the group must contain at least one host target).

You can also apply a Privilege Delegation setting using the Grid Control console by clicking Setup on the Enterprise Manager Home page and then choosing Manage Privilege Delegation Settings from the left menu panel.

Applying Settings to Host Targets Using EMCLI

Use the apply_privilege_delegation_setting EMCLI verb to apply privilege delegation settings to a host target.

Syntax

emcli apply_privilege_delegation_setting -setting_name=<setting name> -target_type=host -target_names="host1;host2;..." -input_file="FILE:hosts.txt" -force="yes/no"

To apply privilege delegation properties to a large number of hosts, you can specify a file containing all hosts by using the -input_file option in place of the -target_names option, as shown in the following example.

Example 20-9 Using EMCLI to Apply Privilege Delegation Settings to a Host Target

./emcli apply_privilege_delegation_setting -setting_name=<setting name> -target_type=host -input_file="FILE: /mydirectory/file.txt" -force=yes

Applying Settings to a Composite Target

Use the apply_privilege_delegation_setting EMCLI verb to apply privilege delegation settings to a composite (group) target.

Syntax

emcli apply_privilege_delegation_setting -setting_name=<setting name> -target_type=composite -target_names="group" -force="yes/no"

Example 20-10 Using EMCLI to Apply Privilege Delegation Settings to a Composite Target

./emcli apply_privilege_delegation_setting -setting_name=<setting name> -target_type=composite -input_file="FILE: /mydirectory/file.txt" -force=yes

Once the setting has been applied successfully to host targets, you can set their preferred credentials using EMCLI or through the Grid Control console.

Disabling Host Privilege Delegation Provider Settings Using EMCLI

To disable a privilege delegation setting, an administrator can create a new setting with disabled status and can apply it to the targets. This disabled setting can be applied to any privilege delegation provider (Sudo/PowerBroker). It will remove the setting from the host.

  1. Create a new privilege delegation setting.

    ./emcli create_privilege_delegation_setting -setting_name= disabled_setting -setting_type=SUDO –disabled=yes
    
  2. Apply the new setting to one or more targets.

    ./emcli apply_privilege_delegation_setting -setting_name= disabled_setting -target_type=host  -target_names="host1;host2;..."  -force=yes
    

Sudo Configuration: Sudoers File

Enterprise Manager uses a trust-based model that permits specification of responsibilities with a high degree of granularity. Administrators can set up sudo or pbrun configuration entries to assign specific Enterprise Manager functional privileges to their OS users. A new executable has been introduced in the Management Agent called nmosudo. Administrators will be able to configure sudo/pbrun such that a less privileged user can run nmosudo as a more privileged user.

In the following example, if an administrator wants user 'joe' to run any Enterprise Manager job as user 'oracle', the corresponding entry in the /etc/sudoers file would be:

(JOB_USERS) ALL : (RUNAS_USERS) AGENT_HOME /bin/nmosudo *

Where 'joe' would be in the JOB_BACKUP_USERS list and 'oracle' would be in the RUNAS_USERS list.

Enterprise Manager will guarantee that the nmosudo executable will only honor requests to run remote operation requests from the OMS via the Agent. nmosudo will not run the remote operation if it cannot validate that the request came from the Agent. Thus, as shown in the example above, it will not be possible for user 'joe' to invoke nmosudo directly from the command line and run a Perl script as user 'oracle'.

Note:

To ensure system security, the administrator must provide the full path to the nmosudo executable.

Configuring Privilege Delegation Providers Using Grid Control Console

Enterprise Manager Grid Control allows you to configure Privilege Delegation Providers through functionality provided through its user interface. Using Grid Control, you can avoid the command line interface while performing essentially the same functions.

The following sections describe the functions you can perform using the Grid Control interface.

Configuring Sudo Settings For a Host Using Enterprise Manager Grid Control Console

You can use Enterprise Manager to create a Sudo setting by using the Grid Control console. You can create privilege delegation settings either by creating the setting directly on a host target, or by creating a PDP setting template that you can apply to multiple hosts.

To create a privilege delegation Sudo setting directly on a host, follow these steps:

  1. Navigate to the Manage Privilege Delegation Settings page. Setup-->Manage Privilege Delegation Settings

  2. For any host target appearing in the table, click Edit. Enterprise Manager takes you to the Host Privilege Delegation Setting page

  3. Select the Sudo privilege delegation type

  4. Enter the privilege delegation command to be used

  5. Click Update to apply the settings to the host

Figure 20-1 shows the Host Privilege Delegation Setting window that you can use to create a Sudo setting.

Figure 20-1 Host Privilege Delegation Setting for Sudo

Host Privilege Delegation Setting for Sudo

Note:

If the host has been configured with either the Sudo or Powerbroker setting, choosing None on this page will remove (or disable) the setting.

Configuring PowerBroker Settings For a Host Using the Grid Control Console

You can create privilege delegation settings either by creating the setting directly on a host target, or by creating a PDP setting template that you can apply to multiple hosts.

To create a privilege delegation PowerBroker setting directly on a host, follow these steps:

  1. Navigate to the Manage Privilege Delegation Settings page. Setup-->Manage Privilege Delegation Settings

  2. For any host target appearing in the table, click Edit. Enterprise Manager takes you to the Host Privilege Delegation Setting page

  3. Select the PowerBroker privilege delegation type

  4. Enter the privilege delegation command to be used and the optional Password Prompt

  5. Click Update to apply the settings to the host

Figure 20-2 shows the Host Privilege Delegation Setting window that you can use to create a PowerBroker setting.

Figure 20-2 Host Privilege Delegation Setting for PowerBroker

Host Privilege Delegation Setting for PowerBroker

Note:

If the host has been configured with either the Sudo or Powerbroker setting, choosing None on this page will remove (or disable) the setting.

Applying Settings to Multiple Host Targets Using the Grid Control Console

You apply Privilege Delegation settings to a target using Privilege Delegation setting templates. If no template with the desired Privilege Delegation settings exists, you must first create the template on the Manage Privilege Delegation Settings Template page as seen in Figure 20-3.

To create a template, follow these steps:

  1. Navigate to the Manage Privilege Delegation Settings page. Setup-->Manage Privilege Delegation Settings

  2. From the Related Links section, click Manage Privilege Delegation Setting Templates

  3. Select a privilege delegation type (Sudo or PowerBroker) and click Go

  4. Fill in the requisite privilege delegation setting information

  5. Click Save

If the desired privilege delegation settings template already exists, you need only apply the template to the desired host(s). To apply the template to the hosts, follow these steps:

  1. Navigate to the Manage Privilege Delegation Settings page. Setup-->Manage Privilege Delegation Settings

  2. Select the desired privilege delegation settings template from the Apply drop-down menu

  3. Click Go to access the Apply Settings page

  4. Add the targets (hosts) to which you want to apply the privilege delegation settings template

  5. Click Apply. Enterprise Manager displays the Past Apply Operations page where you can view the queue of scheduled apply operations along with those that are scheduled/pending. From this page, you can Stop or Delete apply operations

You can also apply privilege delegation settings from the Manage Privilege Delegation Setting Templates page as seen in Figure 20-3.

Figure 20-3 Manage Privilege Delegation Settings Template Window

Manage Privilege Delegation Settings Template Window

Disabling Host Privilege Delegation Provider Settings For One or More Hosts Using Grid Control Console

You can disable a Privilege Delegation setting using the Grid Control console. To disable a privilege delegation setting using this method, follow these steps:

  1. Click Setup to access the Enterprise Manager Configuration page

  2. From the left menu, click Manage Privilege Delegation Settings

    Grid Control displays the Manage Privilege Delegation Settings Page seen in Figure 20-4.

    Figure 20-4 Manage Privilege Delegation Settings Page

    Surrounding text describes Figure 20-4 .
  3. Select the host(s) from which to clear the privilege delegation settings

  4. Click Clear. Enterprise Manager asks you whether to proceed with the privilege setting disable operation

  5. Click Yes