Skip Headers
Oracle® Enterprise Manager Lifecycle Management Administrator's Guide
12c Release 4 (12.1.0.4)

E27046-25
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

35 Managing Configuration Information

This chapter explains how Oracle Enterprise Manager Cloud Control (Cloud Control) simplifies the monitoring and management of the deployments in your enterprise.

This chapter covers the following:

35.1 Overview of Configuration Management

Cloud Control collects configuration information for all managed targets across the enterprise. Collected configuration information is periodically sent to the Management Repository over HTTP or HTTPS, allowing you to access up-to-date configuration information for your entire enterprise through Cloud Control.

Cloud Control enables you to view, save, track, compare, search, and customize collected configuration information for all managed targets known to Enterprise Manager. Additionally, the Configuration Topology Viewer provides a visual layout of a target's relationships with other targets; for example, you can determine a system's structure by viewing the members of a system and their interrelationships.

Table 35-1 provides a snippet of configuration information collected for a small sampling of target types as an example.

Table 35-1 Collected Configurations for Various Targets

Target Type Collected Configuration Information

HostFoot 1 

  • Hardware (includes memory, CPU, I/O device, and network information)

  • Operating system (includes installed patches and patch sets)

  • Oracle software (includes installed products and their components, patch sets, and interim patches applied using OPatch)

  • Other software (includes all software registered with the operating system)

DatabaseFoot 2 

  • Database and instance properties

  • Initialization and System Global Area parameters

  • Tablespace, datafile, and control file information

  • Redo logs, rollback segments, and high availability information

  • Licensing information

Middleware such as WebLogic Server

  • Node Manager, machine, Web service, and Web service port configurations

  • Resource Adapter, including outbound

  • Web and EJB modules

  • Server information

  • JDBC Datasource and Multi Datasource

  • Resource usage

  • Virtual hosts

  • Startup Shutdown classes

  • Jolt Connection Pool

  • Work Manager

  • JMS Topic, Queue and Connection Factory

  • Network channels

Elastic Cloud Infrastructure

  • Switch details

  • Storage appliance details

  • Compute node details (including associated "Host" target GUID)

  • Switch ports configuration

  • Network topology (switch port - device association metric)

VM Server Pool

  • Server Pool configuration details (total disk space and memory available, for example)

  • VM Guest member details

VM Server member details

ClientFoot 3 

  • Hardware

  • Operating system (includes properties, file systems, patches)

  • Software registered with the operating system

  • Network data (includes latency and bandwidth to the Web server)

  • Client-specific data that describes configuration for the browser used to access the client configuration collection applet

  • Other client-oriented data items

Non-Oracle Systems

  • Hardware details including vendor, architecture, CPU, and I/O device information.

  • Operating system details including name, version, software and package lists, kernel parameters, and file system information.

  • OS Registered software including product name, vendor, location, and installation time.


Footnote 1 The default collection period for host configuration information is 24 hours.

Footnote 2 The default collection period for database configuration information is 12 hours.

Footnote 3 Refer to Section 35.8 in this chapter for more information.

Use Cloud Control to manage enterprise configurations:

  • Search collected configuration data

  • Compare configurations

  • View latest and saved configurations as well as inventory and usage details

  • Monitor configuration history for changes

  • Build configuration extensions and introduce custom target types

  • Collect and analyze external client configurations

  • Perform root cause analysis and impact analysis

Note:

To view a visual demonstration on configuration management, watch the video Oracle Enterprise Manager 12c: Database Lifecycle - Manage Configuration, using the following URL:
https://apex.oracle.com/pls/apex/f?p=44785:24:0::NO:24:P24_CONTENT_ID,P24_PREV_PAGE:5775,1

35.2 Overview of Configuration Searches

Use configuration search to search configuration data across the enterprise. Cloud Control ships with a set of out-of-box configuration searches, which you can use as a starting point to explore the volume of configuration data collected. As you work with a provided search, you can tailor the search criteria to refine or broaden the results, and save the altered search under a new name.

Perform powerful searches across the enterprise using sophisticated combinations of search filters, options, and relationships. Consider these search examples:

  • Show all hosts with dual core CPUs

  • Show all tablespaces having at least one 100 MB datafile

  • Show all Oracle Homes installed on Linux 5.6 hosts

  • Find all database instances with initialization parameters p1 and p2 having values v1 and v2, respectively

Enhance the search filtering criteria by adding your own SQL query statements. Save interesting search results by printing a report or exporting to a file.

To access the search capability, from the Enterprise menu select Configuration, then select Search. See the Cloud Control online help for information on setting up and executing configuration searches.

This section covers the following topics:

Note:

To view a visual demonstration on configuration search, watch the video Oracle Enterprise Manager 12c: Configuration Search, using the following URL:
https://apex.oracle.com/pls/apex/f?p=44785:24:0::NO:24:P24_CONTENT_ID,P24_PREV_PAGE:6047,1

35.2.1 Managing Configuration Searches

The Configuration Search library contains Oracle-supplied and user-created configuration searches that you can use as-is or as the basis for similarly conceived searches. Or, you can elect to create searches from scratch.

To access the Configuration Search library, From the Enterprise menu, select Configuration, then select Search.

Search for any existing configuration searches for all target types, or use the criteria to narrow the search. The search name and owner fields recognize containment, so you can specify a text string as a partial name to find all searches whose name or owner contains the string. When you click Search, the results appear in a table at the bottom of the page.

Select a configuration search in the library and click Run to execute the search. A new page appears that reflects the search parameters applied in the search execution, with the results, if any, displayed at the bottom of the page.

Perform these additional tasks:

  • To edit an existing configuration search, select a search in the table and click Edit. A new page appears displaying the search parameters that constitute the search. Change the search criteria to achieve the desired results. When you are satisfied, save the search. Save overwrites the existing search. Save As enables you to save the edited search under a new name. If you are working with an Oracle-provided search, use save as.

  • To create a new search based on an existing search, select a search in the table and click Create Like. Specify a name for the copied search in the dialog that opens. Select the new row in the table and click Edit. Make the desired changes to the search parameters and save under the new name.

  • To delete an existing search, select a search in the table and click Delete. In the dialog that opens, confirm the operation. You must be owner or an administrator to delete a search. A search in use cannot be deleted. Oracle recommends that you not delete an out-of-box search.

35.2.2 Setting Up a Search

Use these instructions to create, create-like, or edit a configuration search.

  1. Specify basic criteria; you may have to expand the Commonly Used Search Criteria to do so. When you select a target type, your selection drives the list of values for the other criteria; for example, available configuration items for the target type you have chosen.

    Select a system or group if you want to search target types that are members. Or search for all target types on a specific host.

  2. Click Relationships to associate the target type with other targets. For example, you may want to know the Management Agent that is monitoring a host you have selected.

  3. Use built-in flexibility to add property filtering criteria:

    • You can select a configuration item from the drop-down list. This populates the page with field entries for all properties within the item.

    • Click Properties on the right. This opens a dialog where you can drill down within a given configuration item and select specific properties to include as filtering criteria.

    So, for example, for target type host you could select the File Systems configuration item from the drop-down list and get property filters for all six properties. Or, you could click Properties and drill down in the dialog (File Systems under Operating System) to select specific filtering properties, for example, Resource Name and Mount Location.

  4. For each property filter you add, create an expression by choosing an operator and specifying a value. For example, the configuration item hardware has a core CPU count property. You choose the > operator and specify 2 to filter the search on a core CPU count greater than 2. Operators can take wildcards. Specify % to match on anything. Note that the contains operator has an implied wildcard; specify contains with no value to match on anything.

    The check mark next to each property filter specifies to include the property in the search results. Sometimes, you merely want to take a property value into consideration when searching, but don't want to clutter the results with unnecessary columns. Deselect the properties you don't want to see in the results.

  5. Click Advanced Options for a selected configuration item type to specify whether to match on all or any one of the filters specified for the item, and to further refine what you want to see in the search results.

  6. As you add criteria, click Search to see the results. Continue to revise the search by adding and removing filters until the results are satisfactory.

    Notice in the search results table that the column names are a concatenation of the filters you specify and elect to display. So, for example, If you filter on hardware vendor name for target type host, the column name in the search results table reads Host Hardware Vendor Name.

  7. Save the search with a meaningful name; that is, a name that reflects the nature of the configuration search.

Still Not Seeing Expected Results?

Sometimes, despite all the filtering criteria, search results still fall short. To refine the search even further, click Search Using SQL. In the dialog that opens, you can edit the SQL Query statement to extend search expressions and rerun the search. Note that you use views in this case; you cannot access the underlying tables. Your SQL edits apply only to the current search execution, so if you want to preserve the edited statement, copy and paste it into a text file for future use.

Advanced Options

In addition to setting an AND/OR condition on filtering, use the Advanced Options dialog to indicate what you want to see in terms of results. The dialog title reflects the context where you invoked the dialog; that is, the configuration item type and items for which you are setting the filters.

  • Set Matching Criteria appropriately; that is, indicate whether any one or all criteria must be met to constitute a match on the configuration item properties.

  • Set the EXISTS condition as follows:

    • None–There is no EXISTS condition. Display results for all targets that satisfy search criteria; include property values.

    • EXISTS–Display results for all targets that contain the specified property value; for example, all database instances where patch 13343438 has been applied. The search results do not include the patch property value, as it is implied in the search criteria.

    • NOT EXISTS–Display results for all targets that do not contain the specified property value; for example, all database instances where patch 13343438 has not been applied. The search results do not include the patch property value, as it is implied in the search criteria.

    The first selection option returns not only matching entities but also actual property values. The rest return only the matching entities.

Advanced Options settings appear appended in parentheses at the respective level. So, for example, you might see (Advanced Options - Match : Any Property Filter; Condition : NOT_EXISTS) after Hardware, if you set the filter to any and the selection to no hardware meets the search criteria. Note that the order of precedence is top down; that is, settings at the top override settings at lower levels.

Dealing with Search Results

If the search results are interesting and worth preserving, you can optionally export and print the results as follows:

  • Click Export and follow instructions in the export dialog to save the results in a CSV file.

  • Click Print and select where to print the results.

35.2.3 Reviewing Search Scenarios

A few simple searches are provided below as an exercise in using the interface. The examples assume that you have opened the Configuration Search library and clicked the Create button. Explore the out-of-box searches for best practices in setting up a search.

Find WebLogic Server Targets Running on a Specific Host

  1. Select Oracle WebLogic Server as the target type.

  2. In the common criteria region, click the On Host search icon and locate the specific host.

  3. Click the Search button to execute the search.

    Results appear at the bottom of the page.

Find Database Instances Running on Hosts with More Than Two Core CPUs

  1. Select Database Instance as the target type.

  2. Click Relationships and in the dialog that opens, select Hosted By. Click OK.

  3. Click Properties at the host criteria level.

  4. In the dialog that opens, expand Hardware, select Core CPU Count, and click OK.

  5. Constrain Core CPU Count as: > 2. You may have to scroll down to find the property.

  6. Click the Search button to execute the search.

    Results appear at the bottom of the page.

Find Datafiles Greater Than 100 MB Whose Tablespace Status Is ONLINE

  1. Select Database Instance as the target type.

  2. Click Properties.

  3. In the dialog that opens:

    1. Expand Tablespaces and select Status.

    2. Scroll down, expand Datafiles, and select Size (Cntrl-click to multiselect).

    3. Click OK.

  4. Constrain tablespace status as: is ONLINE.

  5. Constrain datafiles size as: > 104857600.

  6. Ensure that the option to match all conditions is set, then click the Search button to execute the search.

    Results appear at the bottom of the page.

35.3 Overview of Configuration Browser

Use the Configuration Browser to view configuration data in the context of a single managed entity. Configuration data can include:

  • Configuration items and properties

  • System configuration data as well as all system members and their configuration data

  • System and target relationships (immediate, member of, uses, used by, and so forth)

  • Configuration extension collection data

The browser window consists of left and right panes. The left pane is a tree hierarchy. The right pane consists of tabs that display information in tables. As you navigate in the tree, your selection dictates the contents in the right pane. Depending on the selection, tabs appear containing data such as properties and values, relationships, a hierarchical structure of a system and its members, and file contents in both a parsed and raw text format.

You can take any of several actions as you view a configuration in the browser. These actions are available from the Actions menu above the tabs. The tree hierarchy in the left pane also has context menus available.

This section covers the following topics:

35.3.1 Viewing Configuration Data

The Configuration Browser enables you to view a target's latest or saved configuration data. While viewing configuration data, you can access configuration features such as compare and history.

  1. From the Targets menu, select All Targets.

  2. In the table of returned targets, right-click in the row of the desired target.

  3. In the popup menu, select Configuration, then select Last Collected or Saved. In the case of saved configurations, select in the table of saved configurations the one you want to browse, then click View. The browser opens to display the (latest or saved) configuration data for the selected target.

    Note that these same selections (Last Collected and Saved) are available in the Configuration menu on a target's home page that appears in the top-left corner and typically takes the name of the target type, for example, Host or Web Cache.

  4. The browser display differs depending on the target type

    • For standard targets, the tree hierarchy on the left shows the target node at the top, beneath which appear configuration item categories and nested configuration items. Select the target node and the tabs on the right show target properties and various relationships (immediate, member of, uses, used by). Immediate relationships indicate direction: source and destination. Thus, for example, a source target type of database has an immediate relationship (hosted by) with a destination target type of host.

      As you traverse the tree on the left, the tab on the right becomes the tree selection and displays the properties and values for the selection in table rows. So, for example, if the target type is host and you select Hardware in the tree on the left, the tab on the right becomes Hardware, and the table row displays values for Host Name, Domain, Vendor Name, and so forth. As the table view changes, look to the lower-right corner to see the number of rows the table contains. For multirow tables, use the search filter to drill down to specific properties and values. Add additional search filters as needed.

    • When target type is a system, the tree hierarchy on the left shows the following:

      • The root target at the top level

      • A nested node one level down for each configuration item associated with the root target

      • A folder at the same level as the nested node for each member type

      • A node for each member within the member type beneath the member folder

      Select the root target and the tabs on the right show target properties, a system topology table, and various relationships (immediate, member of, uses, used by). Select a configuration item in the tree on the left, and the tab on the right displays the item's properties and values. Note that this applies only to configuration items associated with the root target. Select a member target on the left and the tab on the right displays the member target properties. Note, however, that configuration data for the target does not display.

      To see the member target's configuration data, you have to right click on the member, and then select Latest Configuration.The browser display then becomes the same as for a standard target. There is a bread crumb above the tree hierarchy on the left that enables you to return to the system view. If you subsequently save the member configuration, the link to the configuration data changes to Saved Configuration.

    • Select a configuration extension file in the tree on the left; separate tabs for a parsed view and a raw text view of the file appear in the tables on the right.

  5. To view the configuration details of all the members of the target, click Configuration Report. This exports all the configuration details into a zip file which gets downloaded. Extract the XLS file to view all the configuration details of the members.

  6. (Optional) If you want to save this configuration snapshot, select Save Latest in the Actions drop-down menu above the tabs. In the dialog that opens, enter a description by which to distinguish the configuration, then click Submit Job. Click OK to exit the dialog. The save action is also available on the right-click menu while selecting a target tree node. Saving a configuration saves all the configuration and relationship data for the selected target. It also saves the relationship and configuration data for all member targets.

  7. Other options in the Actions menu include:

    • Go to Homepage–returns to selected target home page.

    • Export–opens a dialog where you can browse to a file location and save the configuration as a CSV file.

    • Topology–opens the Configuration Topology Viewer showing the viewed target's relationships.

    • Compare–displays the comparison workflow page, where the viewed target's configuration is preselected as the one against which to compare other configurations.

    • Search–displays the configuration search page where the viewed target is the search object.

    • History–displays the history page for the viewed target's configuration.

    • Refresh–triggers a collection of the viewed target's configuration data and subsequent refresh of the browser's tree hierarchy. Applicable only when viewing a latest configuration (last collected). Note that a manual refresh on a composite target applies only to the target itself, not to its members.

35.3.2 Working with Saved Configurations

Saved configurations are snapshots in time of collected data preserved for future reference. You may simply want to view the saved data, or you may want to use it as the basis of a comparison.

You can save standard as well as composite configurations. Saving a configuration saves all configuration item and relationship data for the selected target and for all member targets.

Note that there are various ways to save a configuration:

  • While viewing a table of all targets, right-click a target and select Configuration, then select Save.

  • While viewing a target's last collected configuration in the Configuration Browser, select Save Latest from the Actions drop-down menu.

A save, particularly one that involves systems or groups, can take several minutes. So, for performance reasons, a save action submits a job that occurs asynchronously. To check job status, do the following:

  1. From the Enterprise menu, select Job, then select Activity.

  2. Click Advanced Search and set the following criteria:

    • Set Job Type to ECM Save (or Save Latest).

    • Set Target Type to Targetless.

  3. Click Go.

  4. Drill down in the search results for save details.

To view a saved configuration:

  1. From the Enterprise menu, select Configuration, then select Saved.

  2. In the table of saved configurations, select the configuration you want to browse, then click View.

  3. Navigate the tree hierarchy to expose the following categories of data:

    • Managed entities, configuration items, their properties, and relationships

    • System structures

    • Configuration extension collections

You can also view a saved configuration in the Configuration Browser: right-click a target tree node and select Configuration, then select Saved.

To compare a saved configuration:

  1. From the Enterprise menu, select Configuration, then select Saved.

  2. In the table of saved configurations, select the configuration you want to compare against, then click Compare.

  3. The selected configuration becomes the first configuration in the comparison workflow. Continue the process of setting up the comparison.

To import a previously exported configuration:

  1. From the Enterprise menu, select Configuration, then select Saved.

  2. Click the Import button.

  3. In the dialog that opens, browse to the location of the exported configuration data and click Import.

    Upon refreshing, the imported configuration appears in the table of saved configurations.

35.3.3 Working with Inventory and Usage Details

In the Inventory and Usage Details page you can:

  • View inventory summaries for deployments such as hosts, database installations, and fusion middleware installations on an enterprise basis or for specific targets.

  • View inventory summary information in the context of different dimensions. For example, for host inventory summary, you can view by platform, vendor, or OS version.

  • Drill down multiple levels of inventory details.

  • See trends in inventory counts charted across a time line. Chart bars are color-coded to match the view selection.

  • Switch to a pie chart to break down the inventory data for the rollup option by color-coded percentages.

  • For Hosts (OS Patches) and Databases (Patches Applied), click a patch indicator to link to patch details.

  • Repeatedly revise selections to refresh chart and details based on new selections.

  • Export deployment and details tables to CSV files.

To view inventory and usage details:

  1. From the Enterprise menu, select Configuration, then select Inventory and Usage Details.

    Alternatively, you can click See Details in the Inventory and Usage region of the Grid Summary page.

  2. Select the entity you want to examine and choose a rollup option. For example, show all deployed hosts rolled up by platform. Note that the page refreshes automatically upon selection.

  3. For patch updates, click Yes to view patch details.

  4. Select the radio button to specify how to display the inventory chart.

    • The trend chart shows inventory counts across a time line. Use the magnifier icon to zoom the view. You can adjust the date range by sliding the horizontal scroll bar under the chart.

    • The pie chart breaks down the inventory data for the selected rollup option by percentages in an appealing color-coded visual.

  5. Click Table View to convert the trend chart to table format. Close the table to return to the chart view.

  6. Select one or more rows in the deployments table and click the View Details button to refresh the chart and details table based on the selected rows.

  7. In any given row in the top table there is a count bar next to the count that represents a percentage of the maximum count. For example, if the maximum number of hosts by platform is four, the bar for hosts represented on two platforms would be half as long. Click the bar to refresh the details table and chart for the row.

Note that you can export either the master (deployments) table or the details table. In either case, click the Export button to open a dialog where you can browse to a file location and save the table as a CSV file.

35.4 Overview of Configuration History

Configuration history is a log of changes to a managed entity (target) recorded over a period of one year. The recorded history includes changes both to configurations and to relationships. Relationships are the associations that exist among managed entities.

Configuration history is a powerful tool for monitoring change activity across the enterprise. Consider these use cases:

  • You have noticed that an Oracle RAC system has been underperforming for the past month. As an administrator it would be useful to know what changes have occurred during that time. Have members been added or removed? Have there been configuration changes to the system itself?

  • The daytime administrator notices that detected changes are the result of a patch having been applied and adds an annotation to that effect. The overnight administrator is alerted to the changes and sees the annotation upon follow-up.

  • A hardware memory change to production hosts has been detected. The administrator wants to keep the IT group posted on any future changes in this area. The administrator schedules a recurring job to check history specifically for changes to hardware memory on production hosts and to notify the IT group of such changes.

While viewing a configuration history, you can:

  • Track changes to targets over time by specifying and refining search criteria.

  • View change history and manipulate how the information is presented.

  • Annotate change records with comments that become part of the change history. Annotations have a timestamp and an owner.

  • Schedule a history search to capture future changes based on the same criteria.

  • View the status of scheduled history jobs.

  • Notify others of future change detection.

  • Save change history details to a file.

This section covers the following topics:

35.4.1 Accessing Configuration History

Use any of the following methods to access configuration history:

  • From the Enterprise menu, select Configuration, then select History. Proceed with a configuration history search.

  • Perform a search of all targets. Right-click in a row of returned targets and select Configuration, then select History in the popup menu. View the results for the selected target, identified by type and name in the respective search criteria fields; change the filtering criteria to see a different result. Select a specific configuration item, for example, or change the date range.

  • On a target home page, select Configuration, then select History in the target type-specific menu (top left corner). View the results for the target, identified by type and name in the respective search criteria fields; change the filtering criteria to see a different result. Select a specific configuration item, for example, or change the date range.

35.4.2 Working with Configuration History

Perform the following tasks within configuration history:

  • Drill down within configuration change history

  • Enter annotations and comments

  • Schedule a recurring history search and send the results

  • Save a change history to a file

35.4.2.1 Searching History

Uses various filters to tailor your search of configuration change history.

  1. Specify basic search criteria, starting with target type:

    • The Include Member Target Changes check box is active only if you select a composite target type (system or group).

    • Click a lookup icon to open a dialog of choices for the respective field. Configuration Item is inactive until you select a target type.

    • The Configuration Item selector contains separate tabs for configuration items and relationships. They are mutually exclusive.

    • Select a time offset from the current date or specify a date range. Default is the last 7 days.

    • Limit the scope of the search to a specific type of change; find only configurations with deleted items, for example.

    • Choose whether to view all criteria-based history records or group them by timestamp and target. The latter is the default.

  2. Specify advanced search criteria by selecting from the Add Filters drop-down list.

    • The top three selections (Member of, On Host, Annotation) are constant. Enter partial text of an annotation, for example, to limit the search to changes commented with the specified text.

    • The rest of the drop-down list depends on the configuration item selected for the target type. Selecting Hardware Network Interface Cards for Host populates the rest of the list with properties appropriate to a NIC.

    • Icons denote key fields in the list. NIC Name is a key field, for example. In general, key fields should remain unchanged over time; that is, the search constraint does not take the form old value new value as nonkey fields do.

    Each item you select from the Add Filters list adds a row to the search criteria.

  3. Click Search to trigger the operation. A progress indicator verifies ongoing search activity. Results appear in the table at the bottom.

Note:

One search strategy to consider is perform a gross-level search to see the volume of changes, then go back and refine the search by adding filters.

Working with History Search Results

Each row represents a target satisfying the search criteria in which a change was detected, where a change constitutes something that was added, deleted, or modified. Numbers in parentheses on the tabs reflect the number of respective configuration and relationship changes detected. A search on target name for relationships returns matches on all source targets, destination targets, and targets that contain the target name.

In the changed targets table, select a table row and do any of the following:

  • Click See Real-Time Observations to search actions monitored by compliance rules. Observations are the actions that users have taken on a host or target that were configured to be monitored through real-time monitoring rules.

  • Click Export to save the search results to a CSV file such as a spreadsheet. The value in each column represents a comma-separated value.

  • Click the number in the History Records column to display the changes detected for the selected target.

In the change details table, select a table row and do any of the following:

  • Click Details to see the change details in a pop-up window, including old and new values, and the specifics of any annotations. The Change link in the Type of Change column pops up the same window.

  • Click See Real-Time Observations to search actions monitored by compliance rules. Observations are the actions that users have taken on a host or target that were configured to be monitored through real-time monitoring rules.

  • Click Add Annotation to enter a comment about the change.

  • Click Export to save the search results to a CSV file such as a spreadsheet. The value in each column represents a comma-separated value.

35.4.2.2 Annotating Configuration Changes

To annotate configuration changes:

  1. Select the change row in the results table. To add the same annotation to multiple lines, use the multiselect feature (Ctrl+click or Shift+click).

  2. Click the Add Annotation button.

  3. In the window that pops up, type your comment and click OK. Your comment appears in the designated column. Your login name and a timestamp are associated with your comment and available in the pop-up window that opens when you view the change details.

Note that you can also remove an annotation, provided you are the one who entered the comment (or have super administrator privileges). Select the row that contains the annotation and click the Remove Annotation button. Confirm the removal in the popup message that opens.

35.4.2.3 Scheduling a History Search and Creating a Notification List

You can schedule the change history search to run as a background job (click the Schedule and Notify button). The search can be run once-only or on a recurring basis. Run the search immediately or at some later date. You also can supply e-mail addresses to which to send a link to the search results.

Use a scheduled history search as a tracking mechanism to generate alerts when changes occur.

  1. Specify the job schedule:

    • If not now, when. Click Later to activate the calendar widget where you can select a date and time.

    • How often. Select report frequency in the drop-down list. Default is once-only.

    • Wait how long. If the job fails to run as scheduled, cancel within a specified time frame.

    • Keep going. Maintain the job schedule for the specified period.

  2. Enter the e-mail addresses of those to be directed to the change history search results. Use a comma to separate addresses.

  3. Click OK to schedule the job.

35.4.2.4 Saving History to a File

You can capture the snapshot of change history you have culled for further review and to share with a wider audience, by saving the change details to a CSV file. Click Export and follow instructions in the export dialog.

35.4.3 Viewing History Job Activity

View a list of all current and past history searches. Use search criteria to filter the list of history jobs (click the History Job Activity button). For example, show all scheduled history searches started over the past 24 hours; or, show all successful history searches involving hosts started over the past 31 days. The jobs engine purges history jobs older than 31 days

The history jobs you can view beyond your own depend on your role and access level granted.

Select a table row and click View Result to go to the Jobs page that reports the history search. From there you can drill down to the changes the history search detected. The job name is a hyperlink that takes you to the same place. Use the bread crumb on the Jobs page to navigate back to the list.

If you are the job owner or otherwise have the proper access level, you can perform list maintenance by deleting history jobs that no longer have relevance.

35.5 Overview of Comparisons and Templates

This section describes the template creation process and the use of rules in the process. It also provides information on setting up comparisons and managing comparison templates.

This section covers the following topics:

35.5.1 About Comparison Templates

A comparison template is an exemplar for fine-tuning a comparison of like configurations. A template is associated with a specific target type, which determines the configuration item types, items, and properties to be compared. A set of default templates ships out of box to support certain target types. A template enables you to establish specific settings to take into account when comparing configurations of the given target type; for example, which property differences to ignore, and which property differences trigger an alert. You also can use constraints to establish acceptable values for specific properties. A configuration being compared that does not comply with the constraint constitutes a difference.

A template can invoke rules, or expressions, to be evaluated in determining when there is a match for comparison purposes, and when to disregard differences detected in a comparison.

Templates can be used as is, or as a guideline. So, for example, you might decide that an existing comparison template, with just a few tweaks, can meet your requirements. Perhaps the template ignores property differences that you are concerned about. In this case, use the create-like feature to make the adjustments to an existing template and save it under another name.

For systems, you design a system template that references member templates, based on the target types that make up the system. Create the member templates before you create the system template.

35.5.2 Working with Comparison Templates

This section describes how to create, edit, and otherwise manage comparison templates.

35.5.2.1 Creating or Editing a Comparison Template

Use these instructions when creating a new template or editing an existing template; this includes create-like.

  1. From the Enterprise menu, select Configuration, then select Comparison Templates.

  2. To search for a template, click Search. You can search for multiple target types from the target type list. Select the target types that you want to search for. You can also specify the Template Name, the name of the Owner, and specify if the template is a default template or an Oracle provided template. Click Search.

  3. Each template has a lock beside the template name. A closed lock represents an Oracle provided template. These templates cannot be edited. The templates that have an open lock are user defined comparison templates, and can be edited.

  4. For a new template, click Create and provide a name and target type. To base a template on an existing one, select the template row, click Create Like, and provide a name. In either case, the action creates a new template row.

  5. Select the appropriate template row in the table and click the Edit button. The Template Settings tab appears.

    The compared configurations' target type drives the hierarchy of configuration item types and configuration items on the left. The settings in play for the respective properties on the right derive from the selected template, unless you are creating a new template from scratch, in which case there are no settings.

  6. To create or edit the comparison template for each member, select the Member Settings tab.

    You can choose to view the mapping display in a tree or table format. If you set the Mapping Display to Tree, the View mapping and Comparison results will display the system members in a hierarchical tree format. If you set the Mapping Display to Table, the View mapping and Comparison results will display the system members in a table format. You can edit the following:

    • Optionally select the member template to use for each system member type.

    • For any given member type, you can elect not to compare configurations by clearing the check box.

      Note:

      When you clear a check box for a system member, the children instances of the system member will automatically be ignored during the comparison that uses this template.
    • For member types that you are comparing, select a target property to use as a matching key. The default is target name, but typically you would want to use a distinguishable property to align comparison entities, such as department or location.

  7. In the Template Settings tab, select a configuration item type or item in the left pane to expose its properties in the right pane. A key icon denotes a property that is defined as a key column in the configuration item type's metadata.

    Tip:

    Notice the Compare check box column on the Template Settings tab. This is a powerful feature that enables you to streamline the comparison by selecting only the configuration items that you want to compare. When you select the check box, the comparison engine regards only the corresponding configuration item type when comparing configurations. The child items are independent from the parent items. You can select a child item without selecting the parent.

    So, for example, in comparing host configurations, you may decide to compare only the differences in CPU properties. Simply expand the Hardware configuration item type and select the CPUs check box to compare all properties associated with the item.

  8. Click the Property Settings tab and check boxes for property differences to be compared and notified if different. They are mutually exclusive. When you compare differences in a property value in this fashion, you are doing so unconditionally for all differences detected in the property value for the configuration item type.

    Use a value constraint rule to filter the property value. In this case, the comparison engine compares the property value in the configurations being compared (the second through n configurations) to the constrained value. A property value that fails to satisfy the constraint constitutes a difference. For example, test for a version equal to or greater than 6. Any instance in the compared configurations of a version property value under 6 constitutes a difference. Clearly, you would not set a value constraint if you checked ignore differences. See Section 35.5.3 for details.

  9. Repeat the preceding steps to set additional property settings on other configuration items.

  10. Optionally, select an item in the left pane and click the Rules for Matching Configuration Items tab. For a given property, specify a rule expression to be evaluated to determine when a match exists between configuration instances. In other words, if the expression resolves to true, compare the instances. See Section 35.5.3 for details.

    Match rules are column-based; they apply an AND logical operator. If you specify rules for multiple properties, they must all resolve to true to constitute a match.

  11. Optionally, select an item in the left pane and click the Rules for Including or Excluding Configuration Items tab. You can identify which configuration items should be compared. You can choose to compare all, exclude those that satisfy the rules, or include only those that satisfy rules. See Section 35.5.3 for details.

    Include and Exclude rules are row-based; they apply an AND logical operator within a subset of rules and an OR logical operator between rule subsets. So, if you specify two rules for property A and two rules for property B, either both rules set on property A OR both rules set on property B must resolve to true to constitute a match.

35.5.2.2 Managing Comparison Templates

In addition to creating and editing comparison templates, you manage them by doing the following:

  • View a template's settings and composition; this is read-only

  • Delete a template (requires the proper permissions)

  • Share templates by exporting them in XML file format and importing them into other Cloud Control systems

View a Comparison Template

You can view out-of-box templates and other users' templates to which you have access. Viewing a template is read-only: you see its makeup, but you cannot change anything, even temporarily.

  1. Select a template in the Comparison Templates manager and click the View button.

  2. Expand items in the tree on the left and peruse the settings and rules on the various tabs.

  3. Notice that the Save button is disabled. Click Return to return to the Comparison Templates manager.

Delete a Comparison Template

Deleting a template is subject to the following constraints:

  • You cannot delete an Oracle provided (out-of-box) template. An Oracle provided template is represented by a closed lock beside the template name.

  • You cannot delete a comparison template unless you have the proper permissions.

  • You cannot delete a default comparison template.

  • You cannot delete a comparison template currently in use.

To delete a template, select it in the Comparison Templates manager, click Delete, and confirm the operation.

Export a Comparison Template

Use the export feature to save a template as an external file that can be imported into another Cloud Control system.

  1. Select a template in the Comparison Templates manager, select the Actions menu and click the Export button.

    A platform-specific file dialog opens. For example, if you are using Firefox, the dialog notes that you have chosen to open the named template, which it identifies as an XML file. The dialog asks what you want Firefox to do, open the file in an XML editor or save the file.

  2. Select the save radio button and click OK.

  3. Browse to the desired location in the file system and save the file, changing the name if applicable. You cannot change the name of a default (out-of-box) template on export.

Import a Comparison Template

Any comparison template import must comply with the comparison template .xsd. So, for all intents and purposes, the import should be a previously exported template to ensure compliance.

  1. In the Comparison Templates manager, select the Actions menu, and click the Import button.

  2. Browse to the template file location and click Import.

    The imported template appears as a new row in the template table.

An exported template is associated with its owner. A template whose owner is not the same as the login ID of the person importing the template retains its original ownership. If you want to be the owner of the imported template, you have to edit the owner attribute in the template XML file prior to import, changing the value to your login ID. Or, you can simply remove the attribute, in which case the default owner will be set to the ID of the person initiating the import operation.

The Template Manager disallows import of a default and Oracle provided (out-of-box) templates of the same name. Similarly, you could change the name attribute in the template XML file prior to import to allow the import to occur.

35.5.3 Specifying Rules

Specify rules in the context of creating or editing a comparison template (see Section 35.5.2.1).

Rules enable you to parse configuration data in order to fine-tune comparisons. In terms of the comparison, a rule applies the expression to the value of the selected item in the configuration instance that is being compared to the benchmark configuration. Matching rules are intended to devise a comparison key that aligns the instances being compared. Ignore rules are intended to establish a basis for disregarding any differences detected between instances being compared.

35.5.3.1 Creating a Value Constraint Rule

Specify value constraint rules as follows:

  1. Select a configuration item in the left pane.

  2. Click the Property Settings tab in the right pane and select the property on which you want to set a value constraint.

  3. Click the Edit Rule button in the toolbar. In the dialog that opens:

    1. Select an operator from the drop-down list.

    2. Type an operands expression, then click OK.

    To clear a rule, select the table row and click the Remove Rule button in the toolbar.

    See Section 35.5.4 for details on the formation of a rules expression.

35.5.3.2 Creating a Matching Rule

Specify matching rules as follows:

  1. Select a configuration item in the left pane.

  2. Click the Rules for Matching Configuration Items tab in the right pane, then click New.

    Click Show Key Properties to see which properties are defined as key columns in the selected configuration item type's metadata.

  3. Select a property in the drop-down list that appears under Property Name.

  4. To create the rule, select the table row and click the Edit Rule button in the toolbar. In the dialog that opens:

    1. Select an operator from the drop-down list.

    2. Type an operands expression, then click OK.

    3. To specify additional rules, click New and repeat Steps a and b

    To clear a rule, select the table row and click the Remove Rule button in the toolbar.

    See Section 35.5.4 for details on the formation of a rules expression.

    You can enter additional rules for the same or for a different configuration item. When there are multiple rules, they resolve in the order specified. Matching rules take an AND logical operator, which means all conditions must resolve to true to constitute a match.

35.5.3.3 Creating an Include or Exclude Rule

Specify ignore rules as follows:

  1. Select a configuration item in the left pane.

  2. Click the Rules for Including or Excluding Configuration Items tab in the right pane, then click New.

    Click Show Key Properties to see which properties are defined as key columns in the selected configuration item type's metadata.

  3. Select a property in the drop-down list that appears under Property Name.

  4. To create the rule, select the table row and click the Edit Rule button in the toolbar. In the dialog that opens:

    1. Select an operator from the drop-down list.

    2. Type an operands expression, then click OK.

    3. To specify additional rules, click New and repeat Steps a and b

    To clear a rule, select the table row and click the Remove Rule button in the toolbar.

    See Section 35.5.4 for details on the formation of a rules expression.

    You can enter additional rules for the same or for a different configuration item. When there are multiple rules, they resolve in the order specified. Ignore rules take an AND logical operator for rules within a subset, and an OR logical operator between subsets. So, for two subsets, each with multiple rules, all rules in the first subset OR all rules in the second subset must resolve to true to constitute a match.

  5. Select New Or to indicate the end of one rule subset and the beginning of another.

35.5.4 About Rules Expression and Syntax

A rule consists of an operator and operands. Taken together, they form an expression that resolves to a value that is then compared to the value of the selected item. A true condition satisfies the rule.

Operands can be literals (string literals are enclosed in single quotes), legal numbers, or dates of the form YYYY-MM-DD HH24:MI:SS.FF. Operands that directly reference the value of a configuration item must be of the same date type as that value. Operands in square brackets in the syntax are optional.

Operator Operands
is equal to* An optional literal value to match; string values are case-sensitive; if unspecified, expression evaluates value of the property to which the rule applies

Note that a matching rule compares the values of the configuration items in the respective configuration to one another, not to a third specified value, so the operator does not take an operand in this case.

[match-literal]
is case-insensitive equal to* An optional case-insensitive string literal; if unspecified, expression evaluates value of the property to which the rule applies

Note that a matching rule compares the values of the configuration items in the respective configuration to one another, not to a third specified value, so the operator does not take an operand in this case.

['match-literal']
is greater than or equal† A literal value to match; required
match-literal
is greater than † A literal value to match; required
match-literal
is less than or equal to† A literal value to match; required
match-literal
is less than† A literal value to match; required
match-literal
is one of† A comma-separated list of literal values, at least one of which must be specified, but only one of which need match
match-literal-1[,match-literal-n,...]
is between† A range specified as start and end literal values; both must be specified; range is inclusive
start-range-literal , end-range-literal
contains† A string literal on which to perform pattern matching; required
[FALSE|TRUE,] 'pattern-literal'

FALSE (default) means string must comply with Oracle LIKE operator syntax; TRUE means string must comply with Posix regular expression syntax

replace‡ A string literal to match and replace with a second string literal
[FALSE|TRUE,]'pattern-literal'[,'replacement-literal'][,position-integer][,occurrence-integer] 

FALSE (default) means string must comply with Oracle LIKE operator syntax; TRUE means string must comply with Posix regular expression syntax

TRUE enables optional positional integer argument to indicate where within the column value to extract the string, and optional occurrence integer argument to indicate the position count to replace

Mandatory pattern literal represents the string value to match

If the replacement string literal is unspecified, replace the matched string literal with nothing

substring‡ Extract specified segment of string value
[FALSE|TRUE,]position-integer[,length-integer][,'pattern-literal'[,occurrence-integer]]

FALSE (default) means string must comply with Oracle LIKE operator syntax; TRUE means string must comply with Posix regular expression syntax

Mandatory positional integer argument indicates where to begin string extraction:

  • If 0 or 1, returns all characters

  • If positive integer, starts extraction from beginning

  • If negative integer, starts extraction counting backwards from end

Optional length integer argument indicates character count starting at position integer

pattern literal represents the value to match; optional if the first argument is FALSE; required if TRUE

occurrence integer argument indicates character count to match; valid only if pattern literal is specified


Notations are as follows:


*–Enabled for value constraints, matching rules, and ignore rules
†–Enabled for value constraints and ignore rules only
‡–Enabled for matching rules only

35.5.5 Understanding Rules by Example

These rule examples assume that you are in the process of creating or editing a template and are at the point where you have selected the configuration item in the tree on the left.

35.5.5.1 Matching Rule Examples

Suppose, when comparing the hardware of host configurations, you want, for matching purposes, to ignore case in respective vendor names. Here's a simple rule to make the comparison case-insensitive.

  1. In the Rules for Matching tab, click New.

  2. Select Vendor Name in the drop-down list.

  3. Select the table row and click the Edit Rule button in the toolbar to open the rule dialog.

    • Set Operator to is-case-insensitive-equal-to. As this operator takes no operands for a matching rule, you are done.

    • Click OK.

You want to compare WebLogic Servers, aligning on server name, where the names are different: ManagedServer1 and ManagedServer2, for example. To ensure the comparison occurs, you need to fashion a match on server name.

  1. In the Rules for Matching Configuration Items tab, click New.

  2. Select Machine Name in the drop-down list.

  3. Select the table row and click the Edit Rule button in the toolbar to open the rule dialog.

    • Set Operator to substring.

    • Set Operands to 1, 13.

    • Click OK.

    Effectively, the rule says use the first 13 characters of the name (ManagedServer), thus excluding the qualifying integer.

  4. Another way to achieve the same result:

    • Set Operator to replace.

    • Set Operands to true, '(*)(\d*)', '\1'.

    • Click OK.

    This example uses a regular expression (TRUE) to resolve all characters prior to the qualifying integer.

For a more advanced example, consider a database instance comparison that requires a match on Datafiles filenames within a Tablespace, where filenames are of the form:

/u01/jblack_abc2d/oracle/dbs/dabc2/mgmt_ad4j.dbf
  1. In the Rules for Matching Configuration Items tab, click New.

  2. Select File Name in the drop-down list.

  3. Select the table row and click the Edit Rule button in the toolbar to open the rule dialog.

    • Set Operator to replace.

    • Set Operands to true, '(/u01/)(.*)(oracle.*/dabc[0-9]+.*/)(.*)', '\2\4'.

    • Click OK.

Effectively, the rule says use a regular expression (TRUE) to construct a matching key from the value between /u01/ and oracle, combined with what remains of the original filename after dabc2 /, or jblack_abc2d/mgmt_ad4j.dbf.

35.5.5.2 Including or Excluding Rule Examples

Generally, you use include rules or excludes rules to include or exclude differences in collections that are row-oriented, as opposed to column-oriented. Configuration extension snapshots, for example, are row-oriented data collections.

Say, for example, you wanted to ignore in configuration extension parsed data, any row where the property Attribute identifies an internal ID or checksum.

  1. In the Rules for Including or Excluding Configuration Items tab, click New.

  2. Select Attribute in the drop-down list.

  3. Select the table row and click the Edit Rule button in the toolbar to open the rule dialog.

    • Set Operator to is one of.

    • Set Operands to 'id', 'checksum'.

    • Click OK.

The rule ensures that the comparison ignores any row in the collection data that contains either of the specified values.

Now consider an ignore rule that demonstrates how the comparison engine applies the logical operators AND and OR against the same configuration item type. In this example the objective is to ignore rows in configuration extension parsed data when any of three rule sets satisfies the following conditions:


Data Source = ’sqlnet.ora' AND Attribute = ’ADR_BASE'
OR
Data Source = ’tnsnames.ora' AND Attribute = ’HOST'
OR
Data Source = ’resources.xml' AND Attribute = ’authMechanismPreference'

Notice that the comparison engine applies the AND operator to rules within a set and the OR operator between rule sets. Rules for ignoring instances support inheritance; thus, in this case, the Data Source property is available in rules creation, as demonstrated in the example.

  1. In the Rules for Including or Excluding Configuration Items tab, click New.

  2. Select Data Source in the drop-down list.

  3. Select the table row and click the Edit Rule button in the toolbar to open the rule dialog.

    • Set Operator to is equal to.

    • Set Operands to 'sqlnet.ora'.

    • Click OK.

  4. Click New and select Attribute in the drop-down list.

  5. Select the table row and click the Edit Rule button in the toolbar to open the rule dialog.

    • Set Operator to is equal to.

    • Set Operands to 'ADR_BASE'.

    • Click OK.

  6. Click New Or to insert a logical OR operator to signal the end of the first rule set.

  7. Add two new rules where Data Source is equal to 'tnsnames.ora' and Attribute is equal to 'HOST'.

  8. Click New Or to insert a logical OR operator to signal the end of the second rule set.

  9. Add two new rules where Data Source is equal to 'resources.xml' and Attribute is equal to 'authMechanismPreference'.

The comparison ignores any row in the collection data that satisfies any of the three rule sets.

35.5.6 About Comparisons

Enterprise Configuration Management deals with the collection, storage, and monitoring of configuration data tied to managed entities within the enterprise. A host, for example, has configuration item types related to its hardware and software components—number of CPUs, memory, IO devices, OS platform and version, installed software products, and so forth.

Changes to configuration data invariably happen, typically because of common events like patches and upgrades. At some point a change to one component can affect the overall system in a negative way. Detecting the root cause becomes paramount.

The comparison tool enables you to compare configurations of a target with configurations of another target of the same type. The comparisons can be done on the current configuration or configurations previously saved (perhaps, for example, just before applying a patch or doing an upgrade).

Comparisons allow you to do the following:

  • Ignore certain attributes during a comparison

  • Notify key personnel when differences are detected

  • Design and share comparison templates with other administrators

  • Schedule a comparison to run on a recurring basis

  • Compare complete target systems; match target system members automatically or manually

  • Compare configuration file data as raw file content or in a parsed format

35.5.7 Understanding the Comparison Wizard

Comparisons are an important factor in managing the enterprise. The comparison wizard walks you through the process of setting up a comparison. Setting up a comparison involves five steps, six if you are comparing systems:

  • Select the first configuration in the comparison (the one to compare against)

  • Select additional configurations (the one or more configurations to compare to the first configuration)

  • Select a comparison template to frame the comparison (or no template)

  • When comparing systems, map system members in the first configuration to members of the other configurations

  • Schedule the comparison job and set up e-mail notifications

  • Review your work and submit the job

A follow-on step would be to review the results and drill down to differences details.

35.5.7.1 Selecting a Configuration to Compare Against

The first step in setting up a comparison is to select a configuration against which to compare one or more other configurations. When you open the Comparison Wizard (from the Enterprise menu, select Configuration, then select Compare), available configuration collections appear in a table at the bottom.

  1. Choose between the latest and a saved configuration. You can "mix and match" in that you can compare latest to saved and vice versa. When you choose saved, filtering criteria on the right become active so that you can enter dates and a description.

  2. Specify filtering criteria to narrow the search. Minimally, you would probably want to select a target type, and for a saved configuration, a before or after date. Click Search.

  3. In the list of matching configurations that appears at the bottom of the page, select the one to be the benchmark and click Next or Comparison Configurations on the workflow train.

35.5.7.2 Selecting Configurations to Compare

The next step is to select one or more configurations to compare to the first configuration you selected.

  1. Click Add Configurations to open the Search and Select Configurations dialog.

  2. As for the first configuration, choose between latest and saved, and enter filtering criteria to narrow the search. Click Search.

  3. In the results list, select one or more configurations (you can multiselect), then click OK.

  4. Click Next or Comparison Template on the workflow train.

35.5.7.3 Selecting a Template to Use in the Comparison

Optionally, you can elect not to use a template (the default), in which case you can skip this step. You must use a template you select as is; that is, you cannot alter any settings for this particular comparison. If you want to change certain settings in a template, use the create-like feature to create a new template, based on an existing one.

Depending on the comparison target type, there may be a default template available. When done selecting a template, click Next or Schedule and Notify or Mapping, as appropriate, on the workflow train.

35.5.7.4 Mapping Members in a System Comparison

Mapping pertains exclusively to systems. It's a way to selectively indicate how members of respective systems should match up in a comparison.

If you have already selected a template in the template setup, the mapping display set in the template definition, either tree or table, will also be used as the display format in the mapping step. However, if you selected No template in the template step, then the mapping page will display a Mapping Display option. By default the Tree view is selected. On completion of a system comparison, the system compare results are in the mapping display format that was selected.

Note:

To view a visual demonstration on setting up a system comparison, watch the video Oracle Enterprise Manager 12c: Manage Application Stack Configuration with System Comparisons, using the following URL:
https://apex.oracle.com/pls/apex/f?p=44785:24::::24:P24_CONTENT_ID,P24_PREV_PAGE:5449,1

Select a table row and the Mapping Overview displays the system target type hierarchy and the mappings that exist between the first and second target. These mappings are determined either by the target-matching rules defined for the template selected in the previous step, or by system-defined target-matching rules, if no template was chosen. If you are comparing multiple systems, select a different system target to see the mappings for that system.

Tip:

The mapping display provides feedback on left-only and right-only match-ups in advance of actually running the comparison, giving you the opportunity to create matching rules in the template to address the issue.

You can choose to disregard members from the comparison by selecting the Ignore check box next to those member targets. This selection automatically ignores any child members as well. If you select the check box in the table header, all members are ignored.

Template- or system-based mappings may not account for all situations. Click the Create Mapping button to manually map members in the first system to members in the second system.

The pop-up dialog displays tree hierarchies of the respective system targets. When you select a member in the first system, check boxes designate suitable target members in the second system. Select one or more members to which to map the member in the first system. Note that the mapping automatically includes children of a mapped member. When you select another member in the first system, the mappings you just set disappear from view, but persist. When you are done, click OK to confirm the manual mappings and close the dialog.

The Mapping Overview hierarchy now includes the manual mappings you just created, as denoted by the manually mapped icon in the Status column. Other icons denote system mapped, which covers both system- and template-based mappings; ignored members, and left- or right-only members. Hover the mouse pointer over the icon in the Status column to interpret the icon.

To remove any mappings that were manually created, click the Remove Mapping button. The pop-up dialog displays tree hierarchies of the respective system targets, showing any manual mappings that were created. Select the check box in the Remove column for any manual mapping you want to undo. Note that removal of a member mapping automatically removes all child mappings.

When you are done with mapping, click Next or Schedule and Notify on the workflow train.

35.5.7.5 Scheduling the Comparison and Creating a Notification List

On the Schedule and Notify page, you schedule the comparison to run as a background job. The comparison can be one-time-only or run on a recurring basis. You can run the comparison immediately or at some later date. This also is where you supply e-mail addresses to which to send differences alerts.

Note:

If you schedule a recurring job, you can subsequently change the job-related settings when viewing the results on the Jobs page. Click the Edit button, then go to the Schedule tab.
  1. The comparison job must have a name. Although the system supplies a default name that identifies it by date and time as a configuration comparison, you may want to enter a meaningful name for the job.

  2. Specify the job schedule:

    • If not now, when. Click Later to activate the calendar widget where you can select a date and time.

    • How often. Select report frequency in the drop-down list. Default is one-time-only.

    • Wait how long. If the job fails to run as scheduled, cancel within a specified time frame.

    • Keep going. Maintain the job schedule for the specified period.

  3. Enter the e-mail addresses of those who are to be notified when the comparison detects a difference. Use a comma to separate addresses. Remember that the properties for which differences are alerted were specifically selected in the comparison template.

    As logged-in user and originator of the comparison, you must have properly set up your account for sending notifications via the Enterprise Manager Notification System (from the Setup menu, select Notifications, then select Notification Methods on the console home page). The settings for Identify Sender As and Sender's E-mail Address will appear on e-mail generated as a result of differences detected by the comparison job.

    Note:

    The e-mail notification displays the following:
    • For a simple non system target, the e-mail notification contains a Total Differences Count link that is displayed for each second configuration. Click on this link to navigate to 1:1 compare results page. From this page, you can export the configuration differences to an XMS file. The e-mail notification also displays a table of configuration items that have at least one notify differences count.

      If a second configuration does not have any notification enabled attribute differences, it will not be included in the e-mail.

    • For a system target, the e-mail notification displays for each second system configuration, the total differences and notify differences for the member level pair compared.

      The table total differences count is displayed on top of the table. Click the link to view the system compare results page. You can export the system results into an XLS file, from this page.

      The second configuration section will be included in the e-mail, only if the member pair has at least one notify difference.

      The system total differences is the sum of all member differences, not just the members with notifications.

  4. Click Next or Review and Submit on the workflow train.

35.5.7.6 Reviewing the Comparison Parameters and Submitting the Job

Review the comparison parameters before submitting the job:

  • Is the benchmark configuration, that is, the first one, correct?

  • Are the configurations you are comparing against the benchmark correct?

  • Are you using the template you want?

  • Is the job name suitable?

  • Is the job scheduling as intended?

  • Have you entered properly formatted e-mail addresses for differences alerts?

If you need to change anything, go back to the appropriate page; otherwise, click Submit to schedule the comparison job.

For the comparison of one target against another target, a progress window opens. After the comparison progress has completed, the Comparison Results page opens. You can also close the progress window. This takes you the Comparison Job Activity page.

For the comparison of one target against multiple targets, submitting the job takes you the Comparison Job Activity page.

The Comparison Results page displays a summary of the submitted job. The Comparison Job Activity page reveals the results of the comparison; that is, whether the comparison detected differences or found the configurations to be the same. In either case (different or the same), the reported result is a link to the details of the comparison, although presumably different is the more interesting result. A separate entry appears for each compared configuration. In other words, if configurations B and C are being compared to A, there is a result for A compared to B, and a result for A compared to C.

The Comparison Job Activity page also displays the target type, first target, second target (target compared against first target), the owner of the target, the status of the comparison, the scheduled start, and the comparison run date.

35.5.8 Working with Comparison Results

This section covers comparison results from the following perspectives:

35.5.8.1 About Comparisons and Job Activity

Comparisons run as scheduled jobs. Part of the process of setting up a comparison is to define the schedule: run once-only or on a recurring basis; run immediately or at some later time; retry after failure; and so forth. Given the permutations, you can have many jobs to keep track of.

To view comparison job activity, from the Enterprise menu, select Configuration, then select Comparison Job Activity.

Note that the comparison job activity page also affords the opportunity to resubmit comparisons already run; that is, you do not have to go through the entire comparison workflow to run a subsequent execution of the same comparison.

When you compare one target against numerous targets, the Compare Job Activity page displays data in a form of a tree table. The root node of the tree table displays the overall result of the comparison. Expanding the node will display all the rows containing individual target combinations.

When you compare one target against another single target, only one row containing the comparison results will be displayed.

The Comparison Name is a hyperlink that takes you to the job status page.

To view the comparison result, click on the Comparison Result column link. This will take you to the compare results page.

In the case of comparing one target with numerous two or more targets, the Comparison Result link is enabled in the leaf nodes which corresponds to each target configuration combination.

In the case of comparing one target against another single target, the Comparison Result link is enabled in the root node.

Select a table row and click Resubmit Comparison Now to run a new submission of a previously executed comparison, characterized by the following.

As this is a new job, a date and time stamp distinguishes it from its predecessor.

The job is scheduled to execute immediately.

The job will execute only once.

An informational message confirms the job, which appears as a new row in the table.

If you are the job owner or otherwise have the proper access level, you can perform list maintenance by deleting comparison jobs that no longer have relevance. This has the effect of purging the comparison results as well.

35.5.8.2 About System Comparison Results

Results of a system comparison appear when the scheduled comparison job completes and you click the Different link on the Jobs page. You can of course view results by clicking the Same link, but viewing and resolving differences is typically the objective of comparisons.

The region at the top summarizes the comparison and job details. The region at the bottom displays a system comparison results summary table. As system comparison results can span a large number of rows, you can filter the results to curtail the display. Click the Search down arrow to expose the filtering criteria. The search results highlight the members that satisfy the criteria and show ancestors up to the root.

The table displays a hierarchy of system and member target types where:

  • The Target Type column displays the system and member tree hierarchy.

  • The Result column shows comparison results based on the mappings established as part of comparison setup. A boxed 1 (left only) or 2 (right only) means there was nothing to compare to the first or second member target, respectively. Note that if the parent target configurations are the same, but one or the other parent has child members marked as left only or right only, the parents are marked as different.

  • To resolve unmatched members, rerun the comparison in the wizard, this time ensuring in the mapping step that the left and right member pairs appear in the mapped members table. Select an appropriate system comparison template with target matching rules defined, such that these members are mapped, or map the pairs manually.

  • If, for the purposes of a system comparison, you prefer not to compare members of a given target type (for example, trying to diagnose a system setup issue where differences at the member level would be irrelevant), select the Ignore check box in the mapping step to bypass a given member type.

  • Click the Different link to see the differences between member targets, as displayed on the standard comparison results page. Use the bread crumb link at the top of the details page to return to the system comparison results page.

    When the Results column displays both an equal and a not equal icon, it indicates equality at the parent level, but a difference in some member.

  • To view a summary of all the differences found when comparing the system target and any member targets, click Export All Differences, located at the top of the table that displays the system members. An XLS report will be downloaded. The resulting report opens in Excel and displays the following three tables:

    • Table 1 displays all non- Configuration Extension item differences.

    • Table 2 displays a list of all Configuration Extension data source that were compared and their associated data source attributes, and an indicator if the data source attributes are different. The data source attributes include size, collection errors, parse errors, and generated by.

      If the difference for an attribute is First Only, it indicates that the entire data source is located only on the first target and is missing from the second target.

      If the difference for an attribute is Second Only, it indicates that the entire data source is located only on the second target and is missing from the first target.

      If the data source attributes are Same, it indicates that the data source is on both targets and all the attributes are the same, though the file content could still be different.

      If the data source attributes are Different, it indicates that the data source is on both targets, and the value of the attribute is different on each target. The value is shown as part of the results.

    • Table 3 displays Configuration Extension Data Source Parsed Data. If a Configuration Extension data source has parsed data, in other words, the content of the file can be parsed, and the data source is present on both the first and second target, then if the parsed data has any differences they will be shown in this table.

      Note:

      Data sources that are only on the first or second target are not reported in Table 3. First or second data sources are displayed in Table 2. If you want to view which data sources are first or second only, you should use the results of the second table.

35.5.8.3 About Standard Target Comparison Results

Difference details display when you click the Different link in the comparison results view on the Jobs page. The details view summarizes the comparison and job details. You may want to collapse these regions to provide more page real estate for the difference details.

Difference details break down as follows:

  • The left pane displays a hierarchy of configuration items for the target type being compared, and, if applicable, configuration extensions. Refine the scope comparison results as follows:

    • Select the Show Differences Only check box to eliminate the "noise" of same and ignored results.

    • Select the Show Ignored check box to display properties the comparison template ignores. Key properties and properties that are the same or different display be default. This option is disabled if you selected Show Differences Only in the left pane.

    • To view a summary of all the differences found when comparing the system target and any member targets, click Export All Differences, located at the top of the table that displays the system members. An XLS report will be downloaded.

  • The display on the right depends on the selection on the left.

    • Should the selection on the left have up to six key properties, but only one value property, the table on the right displays all key columns first, and then the value column, where the respective value appears for the first and second configuration. The key columns do not appear twice as the values have to be the same for the rows to be compared in the first place.

      Use the filter feature above the right table to search for configuration items where the key or value columns match.

    • If the selection on the left has more than one value property, the display on the right shows a top table that contains rows of select (key) configuration properties and a bottom table that contains rows of all configuration properties, including both key and value properties.

      Select a row in the top table to move its configuration property to the top row of the bottom table.

    • For single-row configuration item types, that is, item types that have no key properties, but many attribute properties, the right pane displays the compared property values of the first and second configurations in a single table, where the first column of the table lists the property names.

    • Select a configuration specification on the left to display tables on the right where the top table contains the configuration files with differences and the bottom table contains rows of configuration properties and values. Notice in this view that you can synchronize the file differences (Enable File Synchronization). For details on file synchronization, see Section 35.5.8.4.

    • Select a configuration extension file on the left to display file contents on the right. File contents that include property values for the compared configurations display both in raw and parsed form on separate tabs.

The icons that appear in this view are mostly intuitive: equal–same, not equal–different. The key icon denotes the key properties of the configuration item type. An indication of Out of Range means that the property value failed a value constraint set on the property. A boxed 1 (left only) or 2 (right only) means that the comparison did not find a matching item to compare to the first or second configuration, respectively. When this is the case, use the link that appears below the Comparison Details label to open the template in edit mode so that you can invoke a rule to create a match, and then rerun the comparison.

Configuration Key Properties

You might wonder about the column names that appear in the top table on the right. These columns represent configuration item type key properties. If the configuration item type does not have declared key properties, the comparison engine takes the top four properties in the CI type database table to serve as key stand-ins for purposes of matching up configurations. The comparison engine upholds the same precedence (top four properties in the database table) if for some reason the comparison is set up to ignore key properties (not recommended).

35.5.8.4 Synchronizing Configuration Files

Use this feature to perform on-demand file synchronization when a comparison of file-based configurations returns differences. Often, this involves configuration extensions that users create. See Section 35.6, "Overview of Configuration Extensions and Collections," for information on configuration extensions.

Note:

This feature is available only for file-based configurations. Differences resulting from comparisons of command-based or SQL query-based configuration extensions cannot be synchronized.
  1. When viewing comparison results differences, select the configuration specification in the tree on the left.

  2. The Enable File Synchronization check box now appears. Select it.

  3. A drop-down list now appears next to the check box. Select the direction of the update; that is, change the second configuration to match the first, or vice versa.

  4. In the new Synchronize File column that appears, select which files to update. You can select multiple files, indicating that you'll be updating all of them in the same direction.

  5. Optionally, use the Preview feature to view the effect of the update on a file-by-file basis. Click the eyeglasses icon to view the file before and after the update in raw format.

  6. When satisfied with the results, click the Synchronize Files button.

  7. Complete the dialog that opens as follows:

    • Specify the login credentials as necessary. You must have login access to the target destination and write permission on the directory or directories to be updated.

    • Select the appropriate radio button to indicate a destination directory. In either case (original or alternate), you must have write permission on the directory.

    • Select the appropriate radio button for how to proceed on conflict. The comparison is performed using data from the repository. A conflict arises when the file to be updated has changed on the target and is different from the data used for the comparison. Indicate what you want to do in this case—proceed or stop.

    • Note that irrespective of the selection for destination directory (original or alternate), the conflict check is always performed against files in the original directory.

    • Indicate the desired backup options (both are selected by default when the update target is the original directory):

      • Mark the appropriate check box if you want to save a snapshot of the configuration to be updated prior to synchronizing (give it a descriptive name so you can easily retrieve the file from saved configurations; defaults to a generic name—CCS Synchronization Saved Snapshot—which applies even if you blank the field).

      • Mark the appropriate check box if you want to make a backup copy of the configuration file before it's updated. Browse to a directory on which you have write permission.

      These are not mutually exclusive options. With the former, you are saving time-stamped collection data in the OMS repository; whereas, with the latter, you are storing a copy of a file in a file system.

    • If desired, perform an on-demand collection refresh of the destination target's configuration data immediately after file synchronization. This way, if you rerun the comparison or view the configuration in the Configuration Browser, the effects of the update will be visible. You can also run a manual refresh at any time, or wait for the next scheduled collection.

      The check box is selected by default when the original destination directory is the update target. The check box is disabled if you specified an alternate directory, as there would be nothing to refresh in this case.

    • Click OK.

    • Click Yes to confirm the file update.

Use the link in the Confirmation area to track the synchronization job. When the job completes, you can rerun the comparison to verify the update, assuming you requested a refresh. You can also open the configuration extension in the Configuration Browser and confirm the update there.

Not All Configuration Files Can Be Synchronized

You may notice in the comparison results differences view that some files, though different, cannot be selected for synchronization (their check boxes are disabled). There are several possible reasons, including:

  • The destination file is nonwritable.

  • There is no source file.

  • During the configuration extension definition, the file was associated with a parser that does not support a process called reverse transform, which is, effectively, the ability to return the parsed form of a file to a syntax tree structure that can then be rendered back into a physical representation. Not all parsers support reverse transform.

35.6 Overview of Configuration Extensions and Collections

Configuration extensions provide a way to identify files and other configuration data that Cloud Control does not already collect. These customized configurations can be collected on well-known target types or on a target type introduced as part of the configuration extension definition. A set of configuration extensions called blueprints are available for download from Oracle. They are called blueprints because they lay out precisely the files and data to collect for a given platform such as Apache Tomcat.

A typical life cycle of a configuration extension might be as follows:

  • Create a configuration extension and deploy it to several targets.

  • Assess its effectiveness over time.

  • Modify and fine-tune the specification and redeploy, perhaps across a wider spectrum.

  • Undeploy and delete the specification if no longer pertinent.

This section covers the following topics:

35.6.1 Working with Configuration Extensions

This section describes how to create, edit, and otherwise manage configuration extensions. If you want to create a configuration extension that uses a custom target type, the suggested workflow is to first create the custom target type. Concurrent with that activity, you can also add a complementary new target to serve as a sample target instance.

35.6.1.1 Creating a Custom Target Type

If no existing target type satisfies your configuration extension requirements, you can create a custom target type.

Before createing a new target type, ensure that the administrator has installed the Software Library (from the Setup menu, select Provisioning and Patching, then select Software Library). This must be done once, after Cloud Control installation.

  1. In the Configuration Extensions library, select Create Custom Target Type from the Actions menu.

  2. In the dialog that opens, provide a name for the custom target type, then click OK. As noted, it may take a while to complete the process.

  3. When done, a message confirms target type creation and asks if you want to add a sample target instance. A sample target provides the basis for collecting configuration data. Click Yes.

  4. A dialog opens associated with the custom target type you just added. Click the search icon to select a Management Agent to monitor the target you are adding, then click Add Target.

  5. In the dialog that opens, provide target properties appropriate to the instance target type. In particular, the pertinent target property is the path to install home, as this is the likely location of configuration files relevant to the custom target type. Optionally, provide global properties such as cost center and lifecycle status. Click OK.

    The target is now available as a sample target when you create a configuration extension for the custom target type.

It's not imperative that you add a new target instance during custom target type creation.You can do so subsequently by selecting Add New Custom Target from the Actions menu and following Steps 4 and 5 in the process above, this time selecting a custom target type from the drop-down list.

35.6.1.2 Creating or Editing a Configuration Extension

Use the instructions below to create, create like, or edit a configuration extension.

Given appropriate privileges, you can edit a configuration extension and save the edited version, in which case, the version number increases. You might also edit and save as a draft, or edit a draft for publishing. Note that when you edit a configuration extension, you cannot change the target type, as this would cause the underlying metadata to be incompatible with existing deployments of the configuration extension.

See Section 35.6.1.9 for information on privileges required to perform various actions on configuration extensions.

Note:

When you edit a deployed configuration extension, it is automatically redeployed upon saving. This does not apply to saving as draft.
  1. In the Configuration Extensions library, click the Create button; or, select an existing specification in the library and click Create Like or Edit.

  2. On the Create Configuration Extension page, enter a name for the configuration extension and an optional description. The create like action requires minimally that you rename the specification.

  3. Select a target type from the drop-down menu.

  4. Optionally, set up a sample target. A sample target resides on the host from which you intend to collect configuration data. If you do not set up a sample target, you cannot browse the file system or use the preview feature in entering your specifications.

    Click the search icon. A dialog opens containing known instances of the target type. Use the filtering criteria as necessary to locate the instance you want, then click Select.

  5. See Section 35.6.1.3 for instructions on how to complete the Files & Commands tab.

  6. See Section 35.6.1.4 for instructions on how to complete the SQL tab.

  7. After you complete the specification definition and have mapped credentials to the target type, use the preview feature to validate your entries, in particular, to ensure the parsed view is what you expect.

  8. Save the new or edited specification. Remember that configuration extensions are in the public domain. Use the save-as-draft feature to keep the specification private while you test and refine it. See Section 35.6.1.8 for more information on the ramifications of save actions.

    If you are editing a draft, the buttons change as follows:

    • Publish implies that you are making the draft public.

    • Save implies that you are creating the next version of the draft.

When done, you can begin collecting configuration data by deploying the configuration extension to target instances. See Section 35.6.2 for more information.

35.6.1.3 Using the Files & Commands Tab

Create file and command specifications as follows:

  1. Click the search icon to browse to a default base directory location. This is where the configuration files reside, or where the commands you specify are to execute.

    Click the Use Property button to open a dialog where you can select a target property to include as part of the directory path. These properties serve as variables, denoted by curly braces, to be substituted with actual values at runtime. You can type additional text in the box to supplement your selection. So, for example, you might select OracleHome and append a directory–{OracleHome}/config–to collect files on the target located in the config subdirectory under the Oracle Home path. Note that the target type definition determines available target properties. User-defined properties do not appear in the list, as they are not available at the Management Agent.

  2. Click Advanced Settings to specify the following:

    • An alternate base directory for the sample target.

    • The encoding to use in collecting the data at the Management Agent. Configuration data is stored in UTF-8 format in the repository. Oracle Default means use UTF-8 for XML files and the locale encoding of the target for all other file types; Target Locale means store all file types including XML in the locale encoding of the target; otherwise, select an encoding from the drop-down list. Selecting directly from the list automatically selects the accompanying radio button.

    • Whether to use the Management Agent credentials (file specification only) or some other predefined credential set to access data on the target. If the customized credential set does not appear in the drop-down list, click Create to identify the credential set to use. Note that you must then specify the credentials that map to the credential set name you create. If you don't know a mapped name, you can specify a credential set when you open the Remote File Browser to add files as described in Step 3. See Section 35.6.1.5 for more information.

  3. Click Add and select file or command as the specification type.

    For a file specification, enter a file name in the space provided or browse the base directory to select a file on the target. Use of wildcards (* and **) is allowed, where ** indicates 0 or more subdirectories. In using wildcards (and as a general caveat), ensure that collections do not result in too many (or too large) files, and that the files collected be configuration-related, that is, files under administrative control that change relatively rarely, so as not to overload Cloud Control.

    For a command specification, enter command syntax in the space provided or browse the base directory to a script. You must assign a unique alias to the command. The alias you assign appears in the Configuration Browser as a link when viewing the configuration extension hierarchy. When you click the link, it opens the command specification in the tab on the right. The same caveats as mentioned for files apply to command output; that is, that their results are constrained in number and size, and to configuration-related data.

    Select a parser to convert the configuration file or command output into a standard format for storing in the repository. There is no default. If you do not specify a parser, only the raw data format is stored and available for viewing. See Section 35.7.1 for more information.

    Optional. Specify post-parser rules to align tree nodes. See Section 35.6.1.6 for information on entering rules.

  4. Repeat Step 3 to specify additional files or commands.

Return to Section 35.6.1.2 and resume with 7.

35.6.1.4 Using the SQL Tab

Create SQL query specifications as follows:

  1. Select credentials to use to connect to the database. If the customized credential set does not appear in the drop-down list, click Create to identify the credential set to use. Note that you must then specify the credentials that map to the credential set name you create (see Section 35.6.1.5). Configuration extensions only support database credentials with NORMAL roles, not those with SYSDBA, SYSOPER, or other roles.

  2. Specify a JDBC connection to an Oracle database from which to extract data via an SQL query. The connection string can be either a URL or an abstraction of database target properties. It cannot be a combination of the two; that is, partial URL and some target properties.

    The URL must contain the name of the target database host, applicable port number, and the Oracle Service name (SID); for example, mydatabase.us.oracle.com:1521:ORCL.

    If you want to use target properties, leave the field blank. At runtime the application will substitute values for these target properties— {MachineName}{Port}{SID}—to make the connection.

  3. Click Add and type or paste a SQL query in the provided text box. Ensure that the query is sufficiently selective to return only pertinent configuration-related data of manageable size and scope.

    You must assign a unique alias to the query. The alias you assign appears in the Configuration Browser as a link when viewing the configuration extension hierarchy. When you click the link, it opens the SQL query in the tab on the right.

    Database Query Parser should be preselected in the drop-down list.

    Optional. Specify post-parser rules to align tree nodes. See Section 35.6.1.6 for information on entering rules.

  4. Repeat Step 3 to specify additional SQL queries.

Return to Section 35.6.1.2 and resume with Step 7.

35.6.1.5 Setting Up Credentials

If you create a credential set while creating a configuration extension, you have to specify the credentials that make up the credential set. To do this, you have to return to the Configuration Extensions library and proceed as follows:

  1. From the Setup menu (top right of the page next to the Help menu), select Security, then select Monitoring Credentials.

  2. Select the applicable target type in the table and click Manage Monitoring Credentials.

  3. Select the row with the credential set name you created during the configuration extension definition for the given target type and click Set Credentials.

  4. Enter the username and password for the credential set and click Save (or Test and Save for database credentials).

  5. Return to the Files & Commands tab (Section 35.6.1.3) or SQL tab (Section 35.6.1.4) description.

35.6.1.6 Setting Up Rules

Use rules to differentiate nodes in the parsed representation that have the same name. This is particularly important in comparisons and change history when trying to match nodes in the parsed tree, or when expressing SQL queries to verify compliance. Rules resolve to an identifier that is appended in square brackets to node text in the tree as a way of uniquely identifying the node. An operation such as a comparison will then use the combination of node text and bracketed identifier for evaluation purposes.

A rule consists of a condition and an expression, both of which must be valid XPath expressions. The condition resolves to a node that requires the identifier. The expression resolves to a string computation for the identifier. You can use a special case SKIP expression to bypass the node specified in the condition; this is a convenient way to eliminate "noise." In other words, for purposes of comparison, ignore the node the condition resolves to.

Some parsers have default parser rules already defined. They execute automatically on the parsed representation. You can elect to use a subset of default rules, edit them, or override them with custom rules that you define.

The number in the Rules column is significant. Initially, the number is zero (0). A whole number greater than zero indicates the number of custom rules defined. Zero also appears for a parser that has default parser rules. So the appearance of a whole number in the column stipulates an override of default parser rules, if any, with the custom rules the number represents.

Set up rules as follows:

  1. Click the Parser Rules button. The Edit Parser Rules page displays.

  2. To define a custom rule, click Add. In the table row that appears, enter a condition and an expression as valid XPath expressions.

    You can define multiple rules; they are applied to the parsed content in the order specified. Click Return when you are done.

    Select a table row to delete a custom rule.

  3. To manipulate default rules, click Add Default Rules.

    Rules appear in table rows, provided the parser you selected has default parser rules. Edit and delete default rules as appropriate to your purposes. Remember that you are working with a copy of these rules; the originals remain safely intact.

    Note that if you delete all rules, you are merely removing the copies you imported. Default parser rules will still fire unless overridden by custom rules.

For examples of rules, see Section 35.7.6.

Return to the Files & Commands tab (Section 35.6.1.3) or SQL tab (Section 35.6.1.4) description.

35.6.1.7 Managing Configuration Extensions

In addition to creating and editing configuration extensions, you manage them by doing the following:

  • View the selected specification (read-only)

  • Synchronize the selected specification with facets in the Compliance Library for real-time facet monitoring

  • Share configuration extensions by exporting them in XML file format and importing them from the local file system

  • Delete the selected specification (requires the proper permissions)

Viewing a Configuration Extension

You can view a configuration extension in read-only mode to get an idea of the make-up of a specification. Perhaps, for example, to see if it is a likely candidate on which to base a new specification.

  1. In the Configuration Extensions library, select the specification table row and click View Details.

  2. Peruse the settings and rules on the various tabs.

Enabling Facet Synchronization

You can synchronize a configuration extension specification with real-time monitoring facets to monitor real-time changes to the configuration files and queries that make up the configuration extension. Real-time monitoring enables you to know such things as when files and database settings change, who made the change, whether observations were automatically reconciled, whether the actions observed were authorized, and so forth.

When you synchronize configuration extensions with real-time monitoring facets, future changes to configuration extensions automatically propagate to corresponding facets, which means configurations are not only collected, compared, tracked, and so forth, but also are monitored for authorized real-time changes. Note that to associate a configuration extension with a facet and to subsequently edit a configuration extension synchronized with a facet requires the additional role of EM_COMPLIANCE_DESIGNER.

  1. In the Configuration Extensions library, select the specification table row, then select Enable Facet Synchronization from the Actions menu.

  2. The Facet Synchronization column displays a Use Facet link in the configuration extension table row. Click the link to go to the Real-time Monitoring Facets tab in the Compliance Library where you can manage the synchronization of facets with the configuration extension.

Exporting a Configuration Extension

You can export a configuration extension as an XML file that can subsequently be imported into the same or another system.

  1. In the Configuration Extensions library, select the specification table row, then select Export from the Actions menu.

  2. Browse to a file system location where you want to save the specification as an XML file. The saved file takes the name of the configuration extension by default.

Importing a Configuration Extension

Given appropriate privileges, you can import a configuration extension that was previously exported as an XML file.

  1. In the Configuration Extensions library, select the specification table row, then select Import from the Actions menu..

  2. Browse to the file location. Select the file and click the Import button on the dialog.

    The imported specification appears in the Configuration Extensions library.

Deleting a Configuration Extension

You must be the owner or otherwise have sufficient privileges to delete a configuration extension. Note that there are dependencies that potentially impact deletion, including deployments, job schedules, existing collections, and so forth.

  1. In the Configuration Extensions library, select the specification table row and click Delete.

  2. The system validates permissions and otherwise checks for dependencies that might prevent the deletion, although some dependencies cannot be verified until a job submission involving the configuration extension.

35.6.1.8 About Configuration Extensions and Versioning

When you create a configuration extension, you have options to save or save as draft. A normal save action makes the specification publicly available to the general user community. A save as draft action keeps the specification private to you. How you use these actions when creating and editing specifications influences the mechanics of versioning. Consider the following scenarios:

  • You create and save a configuration extension; this is public version 1. You subsequently edit public1 and save as a draft; this becomes draft1. Public1 is still generally available. You edit draft1 and publish; this becomes public2. Note that in parallel, someone else with the proper permissions can also edit public1 and save as a draft to create version 1 of draft2.

  • You create and save a configuration extension as a draft; this is version1 of draft1. You edit and save again; this becomes version 2 of draft1. Repeat the edit-and-save operation; this becomes version 3 of draft1. Edit version 3 of draft1 and publish; this becomes public version 1.

35.6.1.9 About Configuration Extensions and Privileges

Working with configuration extensions requires privileges specific to the given operation you want to perform.

Operation Required Privilege (Role)
Create new target type EM_PLUGIN_OMS_ADMIN

To create a new target type, ensure that the administrator has installed a software library (from the Setup menu, select Provisioning and Patching, then select Software Library). This must be done once, after Cloud Control installation.

Create new target instance EM_PLUGIN_AGENT_ADMIN
Create or import configuration extension "Manage configuration extensions owned by user" (or the more powerful "Manage configuration extensions owned by any user")
Associate configuration extension with an auto-synchronized real-time monitoring facet EM_COMPLIANCE_DESIGNER
Edit or delete configuration extension Differs, depending on the specific activity within the realm of editing:
  • Configuration extension owner requires "Manage configuration extensions owned by user"; nonowner requires "Manage configuration extensions owned by any user"

  • Schedule redeployment jobs for already deployed targets requires "Create" privilege for Job System resource type

  • For configuration extensions associated with real-time monitoring facet, EM_COMPLIANCE_DESIGNER

Deploy or undeploy configuration extension on a target "Manage target metrics" privilege on the target instance; "Create" privilege for Job System resource type (to schedule deployment/undeployment;) EM_PLUGIN_AGENT_ADMIN (to deploy a plug-in to a Management Agent)
Create a new credential set Superuser
View configuration extension definition None
View configuration extension collected data Regular "target instance view" privilege

Note that editing an imported configuration extension may be restricted to edits that do not change the version, depending on options set during export. One such permissible edit would be to credential set information.

35.6.2 About Configuration Extensions and Deployment

Deployment of a configuration extension means to direct the specification to a target where a monitoring Management Agent will collect configuration data based on the specification's definition. A configuration extension can be deployed to multiple targets. You must have sufficient privileges to deploy and undeploy configuration extensions.

Manage deployments by performing the following actions:

35.6.2.1 Deploying and Undeploying Configuration Extensions

Deployment of a configuration extension means to direct the specification to a target where a monitoring Management Agent will collect configuration data based on the specification's definition. A configuration extension can be deployed to multiple targets. You must have sufficient privileges to deploy and undeploy configuration extensions.

To deploy a configuration extension:

  1. In the Configuration Extensions library, select the specification table row and click Manage Deployments.

  2. On the Deployments page, click Add. In the dialog that opens, search for and select targets of the specified target type where you want to deploy the configuration extension.

  3. When you close the dialog (click Select), a new column appears denoting a pending action of Deploy and the status becomes Selected for Deployment.

  4. Proceed as follows:

    • Click Apply to confirm the action while remaining on the Deployments page. The action column disappears, and the status becomes Deployment job in progress.

    • Click OK to schedule the deployment and return to the library.

    • Click Cancel to void the request and return to the library.

  5. Click Refresh Status on the Deployments page to confirm a successful outcome.

If you update a deployed configuration extension, redeployment occurs automatically.

To undeploy a configuration extension:

  1. On the Deployments page, select the deployment in the table.

  2. Click Remove. A new column appears denoting a pending action of Undeploy; status remains Deployed.

  3. Proceed as follows:

    • Click Apply to confirm the action while remaining on the Deployments page. The action column disappears, and the status becomes Undeployment job in progress.

    • Click OK to schedule the undeployment and return to the library.

    • Click Cancel to void the request and return to the library.

  4. Click Refresh Status on the Deployments page to confirm a successful outcome.

When viewing configuration extensions in the library, a green check mark in the Deployments column denotes a currently deployed configuration extension. Click the check mark to open the Deployments page.

35.6.2.2 Editing a Deployment

To edit a deployment:

  1. In the Configuration Extensions library, locate the appropriate table row and click the deployments link.

  2. On the Deployments page, select the deployment in the table and click Edit.

  3. The type of configuration extension, that is, file/command-based or SQL-based, determines the make-up of the dialog that opens. Specify a base directory to override the default base directory currently in effect, or change the JDBC URL, as appropriate.

  4. Proceed as follows:

    • Click Apply to confirm the action while remaining on the Deployments page. The action column disappears, and the status becomes Redeployment job in progress.

    • Click OK to schedule the redeployment and return to the library.

    • Click Cancel to void the request and return to the library.

  5. Click Refresh Status on the Deployments page to confirm a successful outcome.

Note that the edit applies to the deployment of the specification; it does change the configuration extension definition.

35.6.2.3 Viewing a Configuration Collection

You must have sufficient privileges to view a configuration extension's collected data.

  1. In the Configuration Extensions library, locate the appropriate table row and click the deployments link.

  2. On the Deployments page, select the deployment in the table and click View Configuration.

  3. In the Configuration Browser popup window, peruse details of the configuration extension by selecting nodes in the tree hierarchy on the left:

    • The root node represents the target instance being monitored. The right pane displays target properties and immediate relationships.

    • The next level down in the tree represents a template for the specification. The right pane displays specification details such as configurations being collected and the base directory from which they are collected.

    • The remaining leaf nodes in the tree represent the configuration data collected. The right pane displays the configuration data in both parsed and raw format.

You can also view the collected data from the target home page: from the target type menu, select Configuration, then select Last Collected.

35.6.3 Extending Configuration Data Collections

There are two options available to extend configuration data collections using a configuration extension specification:

  • Add additional collection items to an existing target type

  • Add a custom target type with new collection items

35.6.3.1 Extending Existing Target Collections

The instructions below describe how to extend the configuration data Cloud Control collects for an existing target type. The listener target type, for example, does not collect the sqlnet.ora file out of box. To extend the listener data collection to include this item, take the following steps:

  1. From the Enterprise menu, select Configuration, then select Configuration Extensions.

  2. In the Configuration Extensions library, click the Create button.

  3. Give the configuration extension an appropriate name and select Listener as the target type.

  4. Click Select Target Instance to choose a listener instance that is already deployed, so you can browse to the file location.

  5. Set the Default Base Directory to OracleHome.

  6. You are now ready to build the collection data specifications. Click Add, then click the search icon to log in to the remote file browser. Set the credentials appropriately.

  7. In the Oracle home directory of the listener instance, browse to the network/admin subdirectory and select the sqlnet.ora file. Add it to the selection table and click OK.

  8. With the file added to the Files & Commands tab, select an appropriate parser from the drop-down list, in this case, the Oracle ORA parser. Click Preview if you want to see the file attributes in parsed and raw form as it will appear in the collected data.

    Click Save to complete creation of the configuration extension.

  9. In the Configuration Extension library, select the new configuration extension and click Manage Deployments.

  10. On the Manage Deployments page, click Add. In the dialog that opens, select the targets where you want to deploy the configuration extension.

  11. When the status displays submitted, click Apply. Refresh the view until status is successful, then click Save.

  12. To verify the added data collection, go to the target instance home page. From the Oracle Listener menu, select Configuration, then select Latest Collected.

    The Configuration Browser should display the configuration extension in the tree structure on the left, where you can drill down the directory structure to display the parsed and raw forms of the sqlnet.ora attributes and values on the right.

Use this description as a template for extending existing configuration data collections.

35.6.3.2 Adding New Target Data Collections

The instructions below describe how to extend the configuration data Cloud Control collects by adding a new target type. The example assumes to collect data for a custom Apache web server target type.

First, create a custom target type.

  1. From the Enterprise menu, select Configuration, then select Configuration Extensions.

  2. From the Actions menu, select Create Custom Target Type.

  3. In the dialog that opens, enter a target type name, MyApache, for example. Click OK.

  4. After a while, a message confirms target type creation. Click Yes to add a sample target instance.

  5. Click the search icon to select a Management Agent on a host where the application (Apache Tomcat) already resides. Choose the Management Agent and click Select to close the dialog, then click Add Target.

  6. In the target properties dialog that opens, enter the name (MyApache) and set the install home path to the start location of the application (Apache Tomcat) on the Management Agent. Click OK.

  7. In the Configuration Extensions library, click the Create button.

    • Enter a name (MyApache, for example).

    • Select the custom target type MyApache from the drop-down menu.

    • Click Select Target to select the MyApache sample target instance.

  8. You are now ready to build the collection data specifications. . Note that the {INSTALL_LOCATION} variable populates the Default Base Directory field. Click Add, then click the search icon to log in to the remote file browser. Set the credentials appropriately.

  9. In the Apache install home on the Management Agent, browse to the conf directory and select the httpd1.conf file. Add it to the selection table and click OK.

  10. With the file added to the Files & Commands tab, select an appropriate parser from the drop-down list, in this case, the Apache HTTPD parser. Click Preview if you want to see the file attributes in parsed and raw form as it will appear in the collected data.

    Click Save to complete creation of the configuration extension.

  11. In the Configuration Extensions library, select the new configuration extension and click Manage Deployments.

  12. On the Manage Deployments page, click Add. In the dialog that opens, select the targets where you want to deploy the configuration extension, for example, the host on which the configuration extension was based.

  13. When the status displays submitted, click Apply. Refresh the view until status is successful, then click Save.

  14. To verify the new data collection, do an all targets search and locate the custom target type under the Others category on the left and click it to display all deployments of that type on the right.

  15. Click a target instance (MyApache) in the deployments list on the right. The Configuration Browser should display the configuration extension in the tree structure on the left, where you can drill down the directory structure to display the parsed and raw forms of the httpd1.conf attributes and values on the right.

Use this description as a template for extending configuration data collections through custom target types.

35.6.4 Using Configuration Extensions as Blueprints

Specially formed configuration extensions called blueprints are available for download from Oracle. They are called blueprints because they lay out precisely the files and data to collect for a given platform. Platform support currently includes:

  • Apache Tomcat

  • Apache Web Server

  • GlassFish

  • iPlanet

  • JBoss

  • JRun

  • Tuxedo

You can download these blueprints, also called configuration extensions, from the Configuration Management Best Practice Center, where you can also check for new platform support.

35.7 Overview of Parsers

A Parser takes raw configuration data and parses it into a nested attribute structure. This structure is a tree hierarchy where nodes are containers and leaves are name value pairs of attributes, or properties.

Configuration extensions include a host of out-of-box parsers. Each parser consists of a base parser and parser parameters. Some parsers also contain post-parsing rules. A base parser essentially is a category of parser capable of parsing data of a particular format. Parser parameters provide a way to tailor the base format to accommodate variations in data formatting. Post-parsing rules are a mechanism for aligning nodes in the tree that otherwise have no distinct identity. This is important when comparing configurations and tracking change history to avoid flagging "false positive" differences. It also aids in specifying search criteria and crafting SQL queries used in compliance rules.

There are four varieties of base parser:

  • XML

  • Format-specific

  • Columnar

  • Properties

Some parsers have out-of-box default rules. These rules address well-known instances where nodes need to be aligned. Specifically, the WebLogic and WebSphere parsers contain default rules to address such instances. You can leave these rules as is, execute a subset of them, or replace them with your own custom rules.

This section covers the following topics:

35.7.1 Managing Parsers

While creating, editing, or viewing configuration extensions, you can peruse the list of available parers, their default parameters, and post-parser rules, if applicable. Parser parameters dictate formatting such as comment character, delimiters, start and end characters, and so forth. You cannot edit these parameters, but you can export a parser as an XML file, edit the file, and import it back into the application under a new name. Some parsers also have default rules that serve to align nodes in the parsed tree for purposes of comparison, for example.

  1. In the Configuration Extensions library, select Manage Parsers from the Actions menu. A list of available parsers appears in a table. The column on the right (Base Parsers) denotes a general parser category, Properties for example, which implies file types that contain name/value pairs.

  2. Select a parser and click Details. This dialog also shows default rules, if any.

    • Click the Parameters tab to see the parameter defaults in effect. You can then judge if you need to edit the parser to conform with your file format conventions.

    • Click the Default Rules tab to see the post-parsing rules that ship with certain parsers. This is a good way to get exposure to rules formation.

  3. Assume you want to change the delimiter character in a given parser.

    1. With the parser selected in the table, click Export.

    2. In the dialog that opens click Save and navigate to a file system location. Save the XML file with an appropriate name.

    3. In making your edits, be sure to change the parser ID and parser name in the XML, as you are creating a customized version of an out-of-box parser.

  4. Assume you now want to import the new parser you saved for use in creating configuration extensions.

    1. With the Parsers table open, click Import.

    2. In the dialog that opens, browse to the file location where you saved the exported parser file. Select it and click Import on the dialog.

    The new parser now appears in the Parsers table where it can be used in configuration extension creation.

Note that you can also manage parsers while working with a configuration extension, by clicking the Manage Parsers link below the Files & Commands tab.

35.7.2 About XML Parsers

Cloud Control has two XML parsers: a default (attribute-keyed) XML parser and a generic XML parser.

35.7.2.1 About the Default XML Parser

Parsing occurs as follows:

  • XML elements with no XML attributes or child elements become parsed attributes; all other elements become containers.

  • XML attributes become parsed attributes.

  • Element text content becomes a parsed attribute, with its name dependent on whether or not the tag contains any XML attributes. If the tag contains XML attributes, the parsed attribute name takes the value specified in the STORE_CONTENT_AS parameter; otherwise, the parsed attribute name takes the tag name.

The default XML parser accepts the following parameters:

Parameter Description
MULTIKEY_DELIMITER Delimiter that separates a list of XML attribute names in the CONTAINER_NAME parameter; default is tilde (~)
STORE_CONTENT_AS Name to give to parsed attributes derived from element text content, where the element contains XML attributes; default is text_value
CONTAINER_NAME A list of XML attribute names delimited by the value of the MULTIKEY_DELIMITER parameter. If an attribute name in this list appears in a tag in the original file, the tag becomes a container named for the value of the XML attribute. All other XML attributes become parsed attributes as usual. The tag name itself is discarded.

For example, the list includes attribute names Moe and Larry in this order. The original file contains an XML tag Stooges that has attributes Moe, Larry, and Curly. As Moe appears first in the delimited list, its value, leader, becomes the parsed container name; Larry and Curly become parsed attributes. The tag name Stooges is discarded. The original XML fragment might be as follows:

<?xml version="1.0" encoding="UTF-8"?>
<Comedy>
   <Stooges Moe="leader", Larry="zany", Curly="bald">
   </Stooges>
</Comedy>

WebLogic Attribute-keyed Parser

Cloud Control provides an out-of-box attribute-keyed parser specifically designed to parse the WebLogic config.xml file. It has the same parameters as the default XML parser and comes with 26 default post-parsing rules to uniquely identify nodes with the same name.

WebSphere Attribute-keyed Parsers

Cloud Control provides several out-of-box attribute-keyed parsers designed to parse specific WebSphere configuration files. Each parser has the same parameters as the default XML parser and comes with a set of default post-parsing rules to uniquely identify nodes with the same name. There are parsers for the following WebSphere configuration files:

  • node.xml (1 default post-parsing rule)

  • plugin-cfg.xml (7 default post-parsing rules)

  • resource.xml (9 default post-parsing rules)

  • server.xml (13 default post-parsing rules)

  • variables.xml (1 default post-parsing rule)

35.7.2.2 About the Generic XML Parser

Parsing occurs as follows:

  • All XML elements become containers.

  • All XML attributes become parsed attributes.

  • Element text content becomes a parsed attribute that takes the name text_value, where the text content becomes the parsed attribute value.

The generic XML parser accepts no parameters.

WebSphere Generic Parser

Cloud Control provides one out-of-box generic parser designed to parse the WebSphere serverindex.xml configuration file. It comes with three default post-parsing rules to uniquely identify nodes with the same name.

35.7.2.3 XML Parser Examples

This section contains three XML parser examples:

  • As parsed using the default XML parser, with out-of-box parameter values

  • As parsed using the default XML parser, with modified parameter values

  • As parsed using the generic XML parser

Parsed examples derive from the following original XML file:

  <?xml version="1.0" encoding="UTF-8"?>
  <Application>
     <AppName>foo</AppName>
     <Server name="ajax" os="linux">production</Server>
  </Application>

Default XML Parser (Out-of-Box Parameter Values)

When parsed using the default XML parser with out-of-box parameter values, the parsed version appears as follows:

  Application
     AppName = foo  
     Server 
        name = ajax
        os = linux
        text_value = production
         

Note the following about this parsed version:

  • The element contents of the AppName and Server tags become parsed attributes.

  • Since the AppName tag contains no XML attributes, the parsed attribute name takes the tag name.

  • Contrast with the Server tag, which has XML attributes (name and os). This results in a container named for the tag (Server), with three parsed attributes, one for each of the XML attributes, and a third for the text content of the Server tag, which is set to the value of the STORE_CONTENT_AS parameter (text_value).

Default XML Parser (Modified Parameter Values)

To modify parameter values, you have to create a new parser by exporting the default XML parser, modifying the exported XML file, and importing the modified parser, using a new name and parser ID.

Assume you followed this process, making the following modifications:

  • Set the STORE_CONTENT_AS parameter to the value myVal

  • Set the CONTAINER_NAME parameter to the value name

When parsed using the default XML parser with modified parameter values, the parsed version appears as follows:

  Application
     AppName = foo  
     ajax 
        os = linux
        myVal = production
         

Note the following about this parsed version:

  • The AppName tag remains the same; that is, it has no XML attributes so it becomes a parsed attribute.

  • Since the Server tag has an XML attribute that matches the value of CONTAINER_NAME, the container takes the value of the attribute (ajax), obviating the name=ajax parsed attribute. Remember that the out-of-box CONTAINER_NAME parameter has a placeholder but no actual default value; thus, the difference in this version of the parsed representation.

  • The remaining Server tag attribute (os) becomes a parsed attribute as usual, and the text content associated with the tag becomes the value of the attribute myVal, per the edited STORE_CONTENT_AS parameter.

Generic XML Parser

When parsed using the generic XML parser (the one that takes no parameters), the parsed version appears as follows:

  Application
     AppName 
        text_value = foo
     Server 
        name = ajax
        os = linux
        text_value = production
         

Refer to Section 35.7.2.1 for a reminder of how parsing occurs.

35.7.3 About Format-Specific Parsers

Format-specific base parsers are applicable only to a particular data format. Format-specific parsers run the gamut from having no parameters to a few to many with which to tailor formatting.

Parser Description
Blue Martini DNA Parser for Blue Martini DNA files (no parameters).
Connect:Direct Parser for Connect:Direct .cfg files (no parameters).
Database Query (see Section 35.7.6.3 for an example) Parser for configuration extension database query output. Cloud Control automatically transforms query results into a format the parser accepts, organizing results into sections similar to a Windows .ini file. Each section represents one record; each line in a section contains a table column name and a value. See Section 35.7.3.1.
Db2 Parser for the output of the DB2 GET DATABASE CONFIGURATION command (no parameters).
Directory Parser for files containing multiple name value pairs on the same line, where each line may have varying numbers of pairs. For example, the first line might be a=b j=k, the second line c=d m=n y=z, and so forth. See Section 35.7.3.2.
E-Business Suite Parser for E-Business Suite .drv files. The parser converts IF...THEN...ELSE structures in the file into containers in the parsed representation, and the rest of the lines into a container with a fixed number of parsed attributes. These lines can be of two types: directory specifications, whose parsed attribute names are specified in the DIR_HEADER parser parameter; configuration file specifications, whose parsed attribute names are specified in the HEADER parser parameter. See Section 35.7.3.3.
Galaxy CFG Parser for Galaxy .cfg files. See Section 35.7.3.4.
Introscope Parser for Introscope files (no parameters).
MQ-Series Parser for MQ-Series files. See Section 35.7.3.5.
Odin Parser for Odin files (no parameters).
Oracle ORA Parser for Oracle .ora files, such as tnsnames.ora (no parameters).
Siebel Parser for Siebel siebns files. The parser creates a container for each unique path in the file, and attributes for name value pairs, except where a line contains the string Type=empty, in which case the parser does not create a parsed attribute for the line. See Section 35.7.3.6.
UbbConfig Parser for BEA Tuxedo files (no parameters). The parser converts sections prefixed with an asterisk (*), and names in double quotes at the start of a new line, into containers. It converts all other data into attributes.
Unix Installed Patches Parser for Unix installed patches data. The parser creates one container per (non-comment) line of the file. It treats every field ending with a colon (:) on each line as a property name field and the value following, if any, as the property value. Note that a property does not have to have a value. See Section 35.7.3.7.
Unix Recursive Directory List Parser for output of Unix recursive directory listing (ls -l -R). The parser converts each subdirectory line into a container, and each file information line into a container with a fixed set of attributes. See Section 35.7.3.8.

Remember, to modify a format-specific parser, you have to create a new parser by exporting the particular parser, modifying the exported XML file, and importing the modified parser, using a new name and parser ID.

35.7.3.1 Database Query Parser Parameters

The following table describes the parameters with which you can customize the Database Query parser:

Parameter Description
CELL_DELIMITER Character that separates name value pairs; default is =.
PROPERTY_DELIMITER Character that separates the length of a name or value from the value itself; default is _.
COMMENT Character that tells the parser to ignore the line that follows; default is #.
SECTION_START Character that denotes the start of a section; default is \[ (backslash is escape character).
SECTION_END Character that denotes the end of a section; default is \] (backslash is escape character).
USE_INI_SECTION Flag that tells the parser to use Windows .ini type sections; default is true.

35.7.3.2 Directory Parser Parameters

The following table describes the parameters with which you can customize the Directory parser:

Parameter Description
CELL_DELIMITER Character that separates one property from another; default is a space.
EXTRA_DELIMITER Character that separates a property name from its value; default is =.
COMMENT Character that tells the parser to ignore the line that follows; default is #.

35.7.3.3 E-Business Suite Parser Parameters

The following table describes the parameters with which you can customize the E-Business Suite parser:

Parameter Description
DIR_HEADER A tilde-delimited list of attribute names for directory specifications.
STRUCTURE_START A tilde-delimited list of regular expressions denoting the start of a structure.
CELL_DELIMITER A tilde-delimited list of regular expressions denoting name value pair delimiters.
HEADER A tilde-delimited list of attribute names for file specifications.
COMMENT A tilde-delimited list of regular expressions denoting comments.
STRUCTURE_END A tilde-delimited list of regular expressions denoting the end of a structure.
LAST_FREE_FORM Flag that tells the parser to ignore cell delimiters in the last value of a directory or file specification; default is true.
ELEMENT_FIELD A tilde-delimited list of file specification attribute names. The parser concatenates values of the specified attributes to form the name of the container associated with the file specification.
DIR_ELEMENT_FIELD A tilde-delimited list of directory specification attribute names the parser uses to determine the name of the container associated with the directory specification.

35.7.3.4 Galaxy CFG Parser Parameters

The following table describes the parameters with which you can customize the Galaxy CFG parser:

Parameter Description
COMMENT Character that tells the parser to ignore the line that follows; default is !.
ADD_SUFFIX Names of attributes whose values to append to a container name.
MONO_PROP_SECTION Names of sections that have a single property.
MULTI_PROP_SECTION Names of sections that have multiple properties.
NODES_SECTION Names of section start and end elements

35.7.3.5 MQ-Series Parser Parameters

The MQ-Series parser has a single parameter that you can customize: COMMENT, which defaults to *.

35.7.3.6 Siebel Parser Parameters

The following table describes the parameters with which you can customize the Siebel parser:

Parameter Description
LINES_TO_SKIP Tells the parser the number of lines to ignore at the beginning of the file; default is 4.
CELL_DELIMITER A tilde-delimited list of regular expressions denoting name value pair delimiters.
COMMENT A tilde -delimited list of regular expressions denoting comments.
SECTION_START A tilde-delimited list of regular expressions denoting the start of a unique path specification section.
SECTION_END A tilde-delimited list of regular expressions denoting the end of a unique path specification section.
USE_INI_SECTION Flag that tells the parser to use Windows .ini type sections; default is true.

35.7.3.7 Unix Installed Patches Parser Parameters

The following table describes the parameters with which you can customize the Unix Installed Patches parser:

Parameter Description
CELL_DELIMITER Character that separates name value pairs; default is a space.
EXTRA_DELIMITER Character that separates a property name from its value; default is :.
COMMENT Character that tells the parser to ignore the line that follows; default is #.

35.7.3.8 Unix Recursive Directory List Parser Parameters

The following table describes the parameters with which you can customize the Unix Recursive Directory List parser:

Parameter Description
LINES_TO_SKIP Tells the parser the number of lines to ignore at the beginning of the file; default is 4.
CELL_DELIMITER A tilde-delimited list of regular expressions denoting name value pair delimiters.
COMMENT A tilde-delimited list of regular expressions denoting comments.
HEADER A tilde-delimited list of attribute names.
LAST_FREE_FORM Flag that tells the parser to ignore cell delimiters in the last value of a line; default is true.
SECTION_START A tilde-delimited list of regular expressions denoting the start of a subdirectory section.
SECTION_END A tilde-delimited list of regular expressions denoting the end of a subdirectory section.
ELEMENT_FIELD A tilde-delimited list of attribute names. The parser concatenates values of the specified attributes to form the name of the container associated with the line.

35.7.4 About Columnar Parsers

Columnar parsers are inherently flexible owing to the parameters they can accept to tailor formatting. All columnar parsers use a subset of the same parameters.

Parser Description
Cron Access Parser for cron.allow and cron.deny files.
Cron Directory Parser for Unix etc and cron.d files.
CSV Parser for comma-separated-value data. The out-of-box parameter values support CSV files with these characteristics:
  • Each line has the same number of values

  • The first parsed (that is, non-comment) line is a header line whose content is a comma-separated list of column names

  • Commas in double quotes are considered part of the value, not value delimiters

  • One of the column names is "name" whose value becomes the container name associated with each line

Text inside double quotes is considered part of a value; to specify a value that contains a double quote, escape the double quote with a backslash (\). Use a backslash to escape the backslash character itself (\\).

Hosts Access Parser for hosts.allow and hosts.deny files.
Kernel Modules Parser for kernel modules files.
Linux Directory List Parser for Linux directory listing data format (for example, output of a ls -l command).
PAM Configuration Parser for pam.conf files.
PAM Directory Parser for Unix etc/pam.d files.
Process Local Parser for process.local files.
Secure TTY Parser for Unix etc/securetty files.
Solaris Installed Packages Parser for Solaris installed packages files.
Unix Crontab Parser for Unix crontab files.
Unix Directory List Parser for Unix directory listing data format for example, the output of a ls -l command).
Unix Groups Parser for Unix etc/group files. The parser ignores group name and password information.
Unix GShadow Parser for Unix etc/gshadow files.
Unix Hosts Parser for Unix etc/hosts files.
Unix INETD Parser for Unix etc/inetd.conf files.
Unix Passwd Parser for Unix etc/passwd files. The parser ignores password values.
Unix Protocols Parser for Unix etc/hosts files.
Unix Services Parser for Unix etc/services.conf files.
Unix Shadow Parser for Unix etc/shadow files.
Unix System Crontab Parser for Unix system crontab files. System crontab files are very similar to crontab files, but may contain name value pairs such as PATH=/a/b.

35.7.4.1 Columnar Parser Parameters

This section describes all columnar base parser parameters. Although the base parser can accept values for any of these parameters, a given parser specification does not necessarily need to provide values for all of them. All parameters have default values, which are used in the absence of a specified value, although in some cases, parameters have explicit values.

Use quotes when delimiters or other special text such as comment characters or new lines are part of some value. The QUOTE_DELIMITER determines the character value to use. Prefix the quote delimiter with a backslash (\) if you need to escape the character. Use a backslash to escape the backslash character itself (\\) in quoted strings.

Parameter Description
COMMENT A tilde-delimited list of regular expressions that denote comment characters or sequences. For example, #[^\r\n]* specifies that everything on a line following the # character is a comment. Default is an empty list; that is, parse all file contents.
LINES_TO_SKIP The number of initial lines (excluding blank or comment lines) to ignore for parsing purposes, treating them in effect as comments. Default is 0; that is, skip no lines.
CELL_DELIMITER A tilde-delimited list of regular expressions that delimit line values. Default is an empty list; that is, no delimiters (it is unusual to use the default).
QUOTE_DELIMITER A tilde-delimited list of regular expressions that define how quoted values begin and end (usually either a single or double quote character). The beginning and end quote delimiter must be the same. Default is an empty list; that is, parser does not recognize quoted values.
PROPERTY_DELIMITER A tilde-delimited list of regular expressions that delimit property names and values. Default is an empty list; that is, no property delimiters.

Rarely, a columnar file may contain name value pairs of the syntax a=b.

RESERVED_DIRECTIVES A tilde-delimited list of property keywords. Some crontab files contain lines of simple name value pairs, separated by a delimiter (foo=bar), thus violating the requirement that each line have the same number of fields. This parameter provides a workaround to specify property keywords. In the example, the property keyword would be foo. This says, in effect, parse any line beginning with this keyword as a parsed attribute name value pair under the root container. Default is an empty list; that is, no property keywords.
ALTERNATE_DELIMITER An alternate delimiter for property names and values. Default is '/' (used only if ALTERNATE_FIELD parameter is nonempty).
ALTERNATE_FIELD A tilde-delimited list of fields separated by alternate delimiters. Default is an empty list; that is, no alternate delimiters.
HEADER_FLAG A flag specifying whether or not the file has a header line that specifies the column names. Default is false.
HEADER A tilde-delimited list of column names to use if there is no header line. Default is an empty list; that is, no column names (it is unusual to use the default).
ELEMENT_FIELD A tilde-delimited list of column names whose values the parser concatenates to create the container name associated with a line. Default is an empty list; that is, no column names (it is unusual to use the default).
IGNORE_FIELD A tilde-delimited list of column names to ignore. No parsing of values in these columns occurs. Default is an empty list; that is, ignore nothing.
LAST_FREE_FORM A flag that specifies whether the last column is free form. The parser ignores all delimiters in a free form column value. Default is false.
USE_LINE_COMMENT A flag that specifies whether to treat end of line comments as a value to appear in the parsed representation of the data. Default is false.

35.7.5 About Properties Parsers

Properties parsers are inherently flexible owing to the parameters they can accept to tailor formatting and handle disparate organizational elements. All properties parsers use the same set of basic and advanced parameters, as well as advanced constructs.

Parser Description
AIX Installed Packages Parser for AIX installed packages files.
Apache HTTPD Parser for Apache HTTPD.conf files.
Autosys Parser for Autosys.jil files.
Custom CFG Parser for custom .cfg files. This syntax defines an element with E = {} syntax, where the brackets may contain name value pairs, nested elements, or both.
Java Policy Parser for java.policy files.
Java Properties Parser for java.properties files.
LDAP Parser for LDAP .cfg files.
Mime Types Parser for mime.types files.
Radia Parser for Radia .cfg files.
Sectioned Properties Parser for files containing name value pairs organized into sections, such as a Windows .ini file.
SiteMinder Agent Parser for SiteMinder agent files.
SiteMinder Registry Parser for SiteMinder .registry files.
SiteMinder Report Parser for SiteMinder SmReport.txt files.
SmWalker Parser for SiteMinder SmWalker.dat files.
Sun ONE Magnus Parser for Sun ONE magnus.conf files.
Sun ONE Obj Parser for Sun ONE obj.conf files.
Tuxedo Parser for Tuxedo files.
Unix Config Parser for Unix etc/config files.
Unix Login Parser for Unix etc/login.defs files.
Unix PROFTPD Parser for Unix etc/proftpd.conf files.
Unix Resolve Parser for Unix etc/resolve.conf files.
Unix SSH Config Parser for Unix etc/ssh/sshd.conf files.
Unix System Parser for Unix etc/system files.
Unix VSFTPD Parser for Unix etc/vsftpd.conf files.
Unix XINETD Parser for Unix etc/xinetd.conf files.
WebAgent Parser for WebAgent files.
Windows Checksum Parser for Windows checksum output generated with fciv.exe.

35.7.5.1 Basic Properties Parser Parameters

This section describes basic properties parser parameters that are required to parse simple property data formats. Simple property data formats specify a property as a name value pair, usually with a defined delimiter separating the name and the value: foo=bar. The basic data format is a list of properties, one property to a line, together with optional comments; a java.properties file, for example. All parameters have default values, which are used in the absence of a specified value.

Use quotes when delimiters or other special text such as comment characters or new lines are part of some value. The QUOTE_DELIMITER determines the character value to use. Prefix the quote delimiter with a backslash (\) if you need to escape the character. Use a backslash to escape the backslash character itself (\\) in quoted strings.

A comment character such as the pound sign (#), or a particular character sequence (//) usually denotes a comment. Special sequences such as a C style comment (/*….*/) might denote the beginning and end of a comment. Some files might have generic informational content in the first couple of lines. In this case, a parameter is available to tell the parser to ignore these lines.

Parameter Description
COMMENT A tilde-delimited list of regular expressions that denote comment characters or sequences. For example, #[^\r\n]* specifies that everything on a line following the # character is a comment. Default is an empty list; that is, parse all file contents.
LINES_TO_SKIP The number of initial lines (excluding blank or comment lines) to ignore for parsing purposes, treating them in effect as comments. Default is 0; that is, skip no lines.
CELL_DELIMITER A tilde-delimited list of regular expressions that delimit line values. Default is an empty list; that is, no delimiters (it is unusual to use the default).
QUOTE_DELIMITER A tilde-delimited list of regular expressions that define how quoted values begin and end (usually either a single or double quote character). The beginning and end quote delimiter must be the same. Default is an empty list; that is, parser does not recognize quoted values.
ALLOW_NAME_ONLY_PROPERTIES A flag that indicates whether the parser allows property names without a delimiter or a value. Default: false.
REVERSE_PROPERTY A flag that indicates whether the parser allows the value to come before the delimiter and property name. Default: false.

35.7.5.2 Advanced Properties Parser Parameters

This section describes advanced properties parser parameters that are required to parse more complex property data formats. All parameters have default values, which are used in the absence of a specified value.

Parameter Description
PROPERTY_DELIMITER A tilde-delimited list of regular expressions denoting property delimiters. For example, the text "a=b : x=y" could be interpreted in either of two ways:
  • As a single property "a" with value "b : x=y"

  • As two separate properties," a=b" and "x=y"

If a colon (:) is the property delimiter, the parsing engine interprets the text as containing two separate properties. Default is an empty list; that is, parser does not recognize property delimiters.

LINE_END_DELIMITER A tilde-delimited list of regular expressions denoting line end sequences. When the parser encounters a line end delimiter, it assumes a new property or construct starts on the next line. Default is an empty list; that is, parser does not recognize line end delimiters.
CONTINUE_LINE A tilde-delimited list of regular expressions denoting continue line sequences. When the parser encounters a continue line pattern, it interprets data on the following line as a continuation of the construct or property on the previous line, as opposed to interpreting the new line as the beginning of a new property or construct. For example, the parser must encounter a line continuation pattern to recognize property values that span multiple lines. Default is an empty list; that is, parser does not recognize line continuation patterns.
SECTION_START A tilde-delimited list of regular expressions denoting the beginning of a section. Sections cannot be nested. Default is an empty list; that is, parser does not recognize sections.
SECTION_END A tilde-delimited list of regular expressions denoting the end of a section. Default is an empty list.
STRUCTURE_START A tilde-delimited list of regular expressions denoting the beginning of a structure. Structures can be nested. Default is an empty list; that is, parser does not recognize structures.
STRUCTURE_END A tilde-delimited list of regular expressions denoting the end of a structure. Default is an empty list.
XML_STYLE_TAG A flag that indicates whether structures in the file are XML style tags. Default: false.
USE_INI_SECTION A flag that indicates whether INI style sections are present. Default: false.
RESERVED_DIRECTIVES A tilde-delimited list of reserved names indicating the start of a reserved directive. Default is an empty list; that is, parser does not recognize reserved directives.
RESERVED_FUNCTIONS A tilde-delimited list of reserved names indicating the start of a reserved function. Default is an empty list; that is, parser does not recognize reserved functions.
DIRECTIVE_PROPERTIES A tilde-delimited list of reserved directive- implicit property names. Default is an empty list.
FUNCTION_PROPERTIES A tilde-delimited list of required reserved function-explicit property names. Default is an empty list.
SECTION_PROPERTIES A tilde-delimited list of section-implicit property names. Default is an empty list.
STRUCTURE_PROPERTIES A tilde-delimited list of structure-implicit property names. Default is an empty list.
ELEMENT_FIELD A keyword to be ignored by the parser when parsing properties. This typically applies to data formats that specify a keyword before a name value pair; "set a=b" for example. Default is an empty list; that is, parser ignores nothing.
ALLOW_ELEMENT_CELL A flag that indicates whether the file format supports element cell structures. Default: false.
SECTION_EXPLICIT_PROPERTIES A flag that indicates whether sections support explicit properties. Default: false.
STRUCTURE_EXPLICIT_PROPERTIES A flag that indicates whether structures support explicit properties. Default: false.
NEWLINE_CONTINUE_LIN A flag that indicates whether newlines can be line continuation sequences. Default: false.
KEYWORD_FIELD A tilde-delimited list of regular expressions denoting keywords that precede properties that use a whitespace delimiter. Default is an empty list; that is, parser does not recognize keywords.

35.7.5.3 Advanced Properties Parser Constructs

Properties files come in variety of file formats. To accommodate the widest possible range of formats, the generic properties base parser uses combinations of constructs found in most files.

The constructs fall into two categories:

  • Container constructs, which can be reserved functions, reserved directives, XML structures, structures, delimited structures, INI sections, delimited sections, sections, and element cells

  • Property constructs, which can be simple properties, reverse properties, keyword properties, keyword name properties, bracket properties, implicit properties and explicit properties

Of the element constructs, section constructs cannot be nested, but can contain any other construct. Structure constructs can be nested, and can contain any construct except a section. Element cells can be nested, but can only contain element cells and simple properties. Reserved directives and reserved functions cannot be nested, nor can they contain any other constructs.

The rest of this section describes the constructs the base properties parser supports.

Simple Property

A simple property consists of a property name, cell delimiter, property value, and newline sequence, in that order. A simple property may take up more than one line, although properties that span multiple lines usually contain a line continuation character or sequence. The parser ignores whitespace such as tabs and spaces, unless a parameter specifies whitespace as having some significance (cell delimiter, for example).

Example: name=value_that_wraps_to_next_line_/, where the forward slash serves as a line continuation character. A Java Properties file typifies this data format.

Keyword Property

This construct is the same as a simple property, only with a keyword in front, which the parser ignores.

Example: set name=value, where set is the ignored keyword. A Unix System file typifies this data format.

Keyword Name Property

This construct is a simple property where the property name matches a regular expression specified in the KEYWORD_FIELD parser parameter. This is a special case property type specific to the Unix XINETD parser. The XINETD file uses an equal sign (=) as a cell delimiter except when the property begins with the keyword "include" or "includedir", in which case the cell delimiter is whitespace.

While added specifically for XINETD files, the property can be used for other file types where appropriate.

Example: includedir /etc, where includedir is the parser parameter regular expression and whitespace is the cell delimiter.

Explicit Property

An explicit property consists of a property name, a delimiter, and a property value. Unlike a simple or keyword property, an explicit property is bound to a container construct such as a section or a structure; an XML tag attribute, for example.

Examples:

[SectionName p1=v1 p2=v2]

<StructureName p1=v1 p2=v2>
...
</StructureName>

In these constructs, the name value pairs p1 v1 and p2 v2 are explicit properties. A Sun ONE Obj file typifies this data format.

Implicit Property

An implicit property is a property value without an associated property name. Like an explicit property, an implicit property is bound to a container construct, usually a reserved directive. The DIRECTIVE_PROPERTIES parser parameter contains the property names of implicit properties.

Examples:

[SectionName myName myPath]
<StructureName myName myPath>
...
</StructureName>

In these constructs, the implicit properties have the values myName and myPath, with the presumed property names name and path, as declared in the DIRECTIVE_PROPERTIES parser parameter. An Apache HTTPD file typifies this data format.

Reserved Function

A reserved function is a keyword followed by one or more explicit properties. The RESERVED_FUNCTIONS parser parameter specifies keywords that denote reserved functions.

Example: Error fn="query-handler" type="forbidden", where Error is the reserved function keyword specified in the RESERVED_FUNCTIONS parser parameter. A Sun ONE Magnus file typifies this data format.

Reserved Directive

A reserved directive is a keyword followed by one or more implicit properties. The RESERVED_DIRECTIVES parser parameter specifies keywords that denote reserved directives.

Example: LoadModule cgi_module "/bin/modules/std/cgi", where LoadModule is the reserved function keyword specified in the RESERVED_DIRECTIVES parser parameter. An Apache HTTPD file typifies this data format.

XML Structure

An XML structure is a standard XML tag that can contain a name only, a name followed by explicit properties, or a name followed by implicit properties.

Examples:

<Name>
...
</Name>

<Name p1=v1 p2=v2>
...
</Name>
<Name "implicit_property1" "implicit_property2">
...
</Name>

A WebAgent file typifies this data format.

Delimited Structure

A delimited structure consists of the following (in the specified order):

  • Structure name

  • Delimiter

  • Start structure character or character sequence

  • Structure contents

  • End structure character or character sequence

Example:

StructureName = {
...
}

Explicit and implicit properties are not allowed. Java Policy and Custom CFG files typify this data format.

Structure

A structure consists of the following (in the specified order):

  • Structure name

  • Start structure character or character sequence

  • Structure contents

  • End structure character or character sequence

The only difference between a delimited structure and a structure is the delimiter; that is, a structure does not require a delimiter between the structure name and the start structure indicator.

Example:

StructureName {
...
}

Explicit and implicit properties are not allowed. A Unix XINETD file typifies this data format.

INI Section

And INI section resembles a section heading in a Windows .ini file, characterized by:

  • Section start character or character sequence

  • Section name

  • Optional (explicit and implicit) properties

  • Section end character or character sequence

Examples:

[SectionName]

[SectionName p1=v1 p2=v2]

[SectionName "implicit_property1" "implicit_ property2"]

SmWalker and Sectioned Properties files typify this data format.

Delimited Section

A delimited section is a line that begins with a common pattern, but otherwise resembles a simple property.

Examples:

HKEY_LOCAL_MACHINE\SOFTWARE\A\B\C=789

HKEY_LOCAL_MACHINE\SOFTWARE\X\Y\Z=123

These are two delimited section headings where the common pattern is HKEY_. SiteMinder Registry and LDAP files typify this data format.

Element Cell

An element cell consists of an element cell name and a property name value pair of the form A = B = C. Element cells typically use line continuation sequences and nesting to clarify the structure. An element cell that has multiple properties uses a property delimiter to separate them.

Example 1:

EC = \
    B = C, D = F

This example is an element cell named EC with two property name value pairs, B = C and D = F, separated by a comma. The structure uses the backslash character (\) to indicate line continuation. The advanced properties parser parameters PROPERTY_DELIMITER and CONTINUE_LINE define the respective format characters.

Example 2:

EC = \
              EC2 = \
                             A = B, \
                             C = D

This example is an element cell named EC that has a nested element cell named EC2 that contains two property name value pairs, A = B and C = D. This example uses the same delimiter and line continuation characters.

35.7.6 Using Parsed Files and Rules

A collected configuration file is stored in raw form and, if a parser is specified, in a tree structure of nodes, or containers, and attributes, or properties. The file also is generated internally in XML format for the purpose of applying post-parsing rules, which consist of XPath conditions and expressions. Note that even non-XML files are generated in this internal format. Since the internal format must accommodate other file types, it introduces an additional root node in the XML to compensate for files such as Java properties files that have only attribute names and values.

Examples of how files are parsed and displayed, and the effects of post-parsing rules help to clarify:

35.7.6.1 Sample XML File Parsing and Rule Application

Consider the following simple XML file:

  <dir name="/a/b/c">    
    <file name="file1" size=120/>    
    <file name="file2" size=350/>    
  </dir>

Its parsed form, using the default XML parser, appears in the user interface in the following tree structure:

  dir
        name    = /a/b/c
        file
                name = file1
                size = 120
        file
                name = file2
                size = 350
                

Notice that two containers have the same name (file), which makes it impossible to distinguish between the two, at the container level, at least. Thus, this file is a candidate for a post-parsing rule. As mentioned, there is a special internal XML format against which to apply a rule's XPath condition and expression. This format treats nodes and attributes as XML elements, and converts attribute values into corresponding element text content. It also adds a root element that doesn't appear in the original file:

  <root>  
    <dir>
        <name>/a/b/c</name>
        <file>
              <name>file1</name>
              <size>120</size>
        </file>
        <file>
              <name>file2</name>
              <size>350</size>
        </file>
    </dir>
  </root>

Given the problem in the parsed form of having two containers with the same name, a rule resolution might consist of the following:


Condition: /root/dir/file
Expression: name/text()

Effectively, this says: for each file evaluate name/text() to produce an identifier that distinguishes one file from another within the dir node.

After applying the post-parsing rule, the parsed tree structure appears as follows:

  dir
        name = /a/b/c
        file[file1]
              name = file1
              size = 120
        file[file2]
              name = file2
              size = 350
         

The rule resolves to an identifier appended in square brackets to the container name. The combination (file[file1], for example) enables various operations such as compare, search, change history, and so forth, to distinguish between file containers.

35.7.6.2 Sample Non-XML File Parsing and Rule Application

Consider the following simple ORA file:

  acme=
     (DESCRIPTION=
        (SOURCE_ROUTE=yes)
        (ADDRESS=(PROTOCOL=tcp)(HOST=host1)(PORT=1630))
        (ADDRESS_LIST=
           (FAILOVER=on)
           (LOAD_BALANCE=off)
     (ADDRESS=(PROTOCOL=tcp)(HOST=host2a)(PORT=1630))
           (ADDRESS=(PROTOCOL=tcp)(HOST=host2b)(PORT=1630)))
        (ADDRESS=(PROTOCOL=tcp)(HOST=host3)(PORT=1630))
        (CONNECT_DATA=(SERVICE_NAME=Sales.us.acme.com)))

Its parsed form, using the Oracle ORA parser, appears in the user interface in the following tree structure:

  acme
          DESCRIPTION
               SOURCE_ROUTE    yes
               ADDRESS
                       PROTOCOL         tcp
                       HOST             host1
                       PORT             1630
               ADDRESS_LIST
                       FAILOVER         on
                       LOAD_BALANCE     off
                       ADDRESS
                               PROTOCOL          tcp
                               HOST              host2a
                               PORT              1630
                       ADDRESS
                               PROTOCOL          tcp
                               HOST              host2b
                               PORT              1630
               ADDRESS
                       PROTOCOL         tcp
                       HOST             host3
                       PORT             1630
               CONNECT_DATA
                       SERVICE_NAME     Sales.us.acme.com

Notice that the address containers, both standalone and within ADDRESS_LIST are indistinguishable. Thus, this file is a candidate for a post-parsing rule. As mentioned, there is a special internal XML format against which to apply a rule's XPath condition and expression. This format treats nodes and attributes as XML elements, and converts attribute values into corresponding element text content. It also adds a root element that doesn't appear in the original file:

  <root>
          <acme>
                  <DESCRIPTION>
                          <SOURCE_ROUTE>yes</SOURCE_ROUTE>
                          <ADDRESS>
                                  <PROTOCOL>tcp</PROTOCOL>
                                  <HOST>host1</HOST>
                                  <PORT>1630</PORT>
                          </ADDRESS>
                          <ADDRESS_LIST>
                                  <FAILOVER>on</FAILOVER>
                                  <LOAD_BALANCE>off</LOAD_BALANCE>
                                  <ADDRESS>
                                          <PROTOCOL>tcp</PROTOCOL>
                                          <HOST>host2a</HOST>
                                          <PORT>1630</PORT>
                                  </ADDRESS>
                                  <ADDRESS>
                                          <PROTOCOL>tcp</PROTOCOL>
                                          <HOST>host2b</HOST>
                                          <PORT>1630</PORT>
                                  </ADDRESS>
                          </ADDRESS_LIST>
                          <ADDRESS>
                                  <PROTOCOL>tcp</PROTOCOL>
                                  <HOST>host3</HOST>
                                  <PORT>1630</PORT>
                          </ADDRESS>
                          <CONNECT_DATA>
                                  <SERVICE_NAME>Sales.us.acme.com</SERVICE_NAME>
                          </CONNECT_DATA>
                  </DESCRIPTION>
          </acme>
  </root>

Given the problem in the parsed form of having containers with the same name, a rule resolution might consist of the following:


Condition: //ADDRESS
Expression:/HOST/text()

Effectively, this says: for each address element evaluate /HOST/text() to extract the host name as the address identifier.

After applying the post-parsing rule, the parsed tree structure appears as follows:

  acme
          DESCRIPTION
               SOURCE_ROUTE    yes
               ADDRESS[host1]
                       PROTOCOL         tcp
                       HOST             host1
                       PORT             1630
               ADDRESS_LIST
                       FAILOVER         on
                       LOAD_BALANCE     off
                       ADDRESS[host2a]
                               PROTOCOL          tcp
                               HOST              host2a
                               PORT              1630
                       ADDRESS[host2b]
                               PROTOCOL          tcp
                               HOST              host2b
                               PORT              1630
               ADDRESS[host3]
                       PROTOCOL         tcp
                       HOST             host3
                       PORT             1630
               CONNECT_DATA
                       SERVICE_NAME     Sales.us.acme.com

The rule resolves to an identifier appended in square brackets to the container name. The combination (ADDRESS[host2a], for example) enables various operations such as compare, search, change history, and so forth, to distinguish between address containers.

35.7.6.3 Sample SQL Query Parsing and Rule Application

Consider the following three-column database table SERVER_DETAILS:

SERVER_NAME ENVIRONMENT HOSTED_APPLICATIONS
webserver-100 QA 5
webserver-200 PERFORMANCE 6
webserver-500 PRODUCTION 3

The SQL query expressed as part of the configuration extension creation is as follows:

select * from SERVER_DETAILS

This query returns the following raw output:

  [row]
  11_SERVER_NAME=13_ webserver-100
  11_ENVIRONMENT=2_ QA
  19_HOSTED_APPLICATIONS=1_5
  [row]
  11_SERVER_NAME=13_ webserver-200
  11_ENVIRONMENT=11_ PERFORMANCE
  19_HOSTED_APPLICATIONS=1_6
  [row]
  11_SERVER_NAME=13_ webserver-500
  11_ENVIRONMENT=10_ PRODUCTION
  19_HOSTED_APPLICATIONS=1_3

The Configuration Browser Source tab renders the data the same way.

Its parsed form, using the Database Query parser, appears in the user interface in the following tree structure:

  row
         SERVER_NAME=webserver-100
         ENVIRONMENT=QA
         HOSTED_APPLICATIONS=5
  row
         SERVER_NAME=webserver-200
         ENVIRONMENT=PERFORMANCE
         HOSTED_APPLICATIONS=6
  row
         SERVER_NAME=webserver-500
         ENVIRONMENT=PRODUCTION
         HOSTED_APPLICATIONS=3

Notice that the row containers are indistinguishable. Thus, this query result is a candidate for a post-parsing rule. As mentioned, there is a special internal XML format against which to apply a rule's XPath condition and expression. This format treats nodes and attributes as XML elements, and converts attribute values into corresponding element text content. It also adds a root element that doesn't appear in the original file:

  <root>
              <row>
                          <SERVER_NAME>webserver-100</SERVER_NAME>
                          <ENVIRONMENT>QA</ENVIRONMENT>
                          <HOSTED_APPLICATIONS>5</HOSTED_APPLICATIONS>
              </row>
              <row>
                          <SERVER_NAME>webserver-200</SERVER_NAME>
                          <ENVIRONMENT>PERFORMANCE</ENVIRONMENT>
                          <HOSTED_APPLICATIONS>6</HOSTED_APPLICATIONS>
              </row>
              <row>
                          <SERVER_NAME>webserver-500</SERVER_NAME>
                          <ENVIRONMENT>PRODUCTION</ENVIRONMENT>
                          <HOSTED_APPLICATIONS>3</HOSTED_APPLICATIONS>
              </row>
  </root> 

Given the problem in the parsed form of having three containers with the same name, a rule resolution might consist of the following:


Condition:/root/row/SERVER_NAME
Expression:SERVER_NAME/text()

Effectively, this says: for each row evaluate SERVER_NAME/text() to produce an identifier that distinguishes one row from another within the tree structure.

After applying the post-parsing rule, the parsed tree structure appears as follows:

  row[webserver-100]
         SERVER_NAME=webserver-100
         ENVIRONMENT=QA
         HOSTED_APPLICATIONS=5
  row[webserver-200]
         SERVER_NAME=webserver-200
         ENVIRONMENT=PERFORMANCE
         HOSTED_APPLICATIONS=6
  row[webserver-500]
         SERVER_NAME=webserver-500
         ENVIRONMENT=PRODUCTION
         HOSTED_APPLICATIONS=3

The rule resolves to an identifier appended in square brackets to the container name. The combination (row[webserver-100], for example) enables various operations such as compare, search, change history, and so forth, to distinguish between row containers.

35.8 Overview of Client Configurations

A "client" represents an end-user or customer system—a system that is not part of your own IT infrastructure. A "client configuration" represents the configuration data collected about the end-user's system. These configurations differ from the internal deployments that you manage using Cloud Control.

The Client System Analyzer (CSA) application allows Web server administrators to collect and analyze data from end-user systems. The client data is collected by an applet, diagnosed, and sent back to the CSA application. You can either use the CSA application that comes pre-installed with Cloud Control, or you can deploy CSA independently to your Web server.

To access client configurations, from the Enterprise menu, select Configuration, then select Refresh Host Configuration. On the Refresh Host Configuration page, click Client Configurations under Related Links. See the Cloud Control online help for information on performing tasks related to client configurations.

This section covers the following topics:

35.8.1 About Client System Analyzer in Cloud Control

Using the pre-installed application allows you to collect client data without having to set up a separate Web server. The Management Agents collect, analyze, and upload the client data to the Management Repository. End users do not need login credentials to access Cloud Control. Example usage scenarios include:

  • End users who call the Help Desk may be asked to navigate to the out-of-box CSA page so that their system information is uploaded. The Technical Support Representative can then review the system information and offer solutions.

  • The client's application can be changed to provide an "Upload my system information" link to the Client System Analyzer in the Cloud Control application. The link can specify certain configuration parameters, such as the URL to return to after the Client System Analyzer runs.

  • The client's application can be modified to redirect its users to the Client System Analyzer in the Cloud Control page during login or at other points in the application. Collected information can then be used from within Cloud Control to obtain various bits of information about the client systems. Examples include most popular browser versions, or systems that do not have a necessary Operating System patch applied or do not have enough RAM.

To access the CSA application, from the Enterprise menu, select Configuration, then select Refresh Host Configuration. On the Refresh Host Configuration page, click Client System Analyzer under Related Links. See the Cloud Control online help for information on working with the CSA application.

35.8.2 Deploying Client System Analyzer Independently

CSA can be deployed independently to any J2EE-capable Web server. This deployment strategy is appropriate when:

  • Clients accessing CSA cannot reach or have limited access to a Cloud Control deployment; for example, due to a firewall.

  • Further customization to the CSA application is required, such as:

    • Custom rules can be supplied to the CSA application so that the end users have immediate feedback as to whether their systems satisfy certain constraints.

    • The behavior of the applet can be changed to collect additional information or to present end users with additional or different user interfaces.

    • The load on the Management Service Web servers needs to be reduced.

Both pre-installed and standalone types of deployments assign a configurable identifier called a Client Configuration Collection Tag to every client configuration collection. 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 application, you must configure Cloud Control to collect the client configuration data and upload it to the Management Repository.

See the Cloud Control online help for information on collecting and viewing client configurations.

35.9 Overview of Relationships

Relationships define the associations that exist among targets, or more extensively, among managed entities. In general, relationships are inherent to a target type definition. But not all relationships can be anticipated at target type creation. Thus, Cloud Control supports creation of supplemental relationships. There are two methods available to create new relationships:

  • Manually, by adding a generic system target

  • Interactively, within the Configuration Topology Viewer

This section describes the manual process. For information on creating relationships within the Configuration Topology Viewer, see Section 35.10.14.

There are two ways to access the generic system wizard:

  • From the Setup menu, select Add Target, then select Generic System

  • From the Targets menu, select Systems, then click the Add button

General

Provide general details of the generic system:

  • Specify a meaningful target name

  • Indicate whether this is to be a privilege-propagating system

  • Set system properties such as cost center and life cycle status

  • Add system members; there should a logical correspondence to the selections

  • Review member dependencies and indicate whether to include them

  • Set the time zone appropriately (defaults to Greenwich Mean Time)

When done, click Next.

Define Associations

Select the check box to display any associations (relationships) that Cloud Control automatically detects based on the members added to the system. Add additional associations as follows:

  1. Click Add.

  2. Complete the dialog that opens as follows:

    1. Select a member target in the left table. This populates the right table.

    2. Select an associated target in the right table. This populates the association drop-down list.

    3. Select the association you want to create.

    4. Click OK. The new association appears in the associations table.

  3. Click Add and repeat to create additional associations.

When done, click Next.

Availability Criteria

Use this page to declare the key members of the system; that is, the members that must be running for the system to be considered available. You can select any one, some, or all members, but you must select at least one.

When done, click Next.

Charts

Customize how you want charts to appear on the System Charts page:

  • Supplement suggested charts with charts you add

  • Edit certain suggested charts to fit your needs

  • Deselect the suggested charts check box and customize the page entirely

  • Alter the appearance of the Members page by adding and removing columns and abbreviations

When done, click Next.

Review

Verify the makeup of the generic system target. If everything appears in order, click Finish.

Upon confirmation that the target was successfully created, use the Configuration Topology Viewer to review and traverse the relationships you created.

35.10 Overview of Configuration Topology Viewer

The Configuration Topology Viewer provides a visual layout of a target's relationships with other targets.

This section covers the following topics:

35.10.1 About Configuration Topology Viewer

The Configuration Topology Viewer provides a visual layout of a target's relationships with other targets. To access the Configuration Topology Viewer from a target's home page, select Configuration, then select Topology in the dynamic target menu. A topology graph appears for the current target. Using the viewer, you can:

  • Determine the source of a target's health problems, that is, detect which targets might be causing the failure. For example, a database is down because its host is down.

  • Analyze the impact of a target on other targets. For example, the payroll and finance applications will be impacted if the database goes down.

  • Determine the system's structure by viewing the members of a system and their interrelationships.

  • Add additional relationships between targets. These relationships will be reflected in other Cloud Control tools.

  • Customize your configuration topology views to focus on the targets for which you have responsibility.

  • Share custom topology views that you have created with other Cloud Control users.

35.10.2 Examples of Using Topology

The following are examples of when to use the topology feature:

35.10.3 Viewing a Configuration Topology

The Configuration Topology Viewer provides a visual layout of a target's relationships with other targets.

In the situations where the topology you are viewing is larger than your browser window, you can adjust the view by:

  • Clicking the small arrow icon in the bottom right corner of the window to bring up a navigator, which allows you to select which portion of the topology is in view.

  • Decreasing the size of the nodes in the display using the zoom control in the top left of the display.

Perform the following steps:

  1. Access the Configuration Topology Viewer.

    From the Targets menu on the Cloud Control home page, select All Targets. In the table, click the appropriate target. On the resulting page, select Configuration then select Topology from the dynamic target menu.

  2. From the View list, select any of the following:

    • Uses

      This view helps you determine the targets that the selected target depends on. If a target is having problems, this view can be useful in helping you determine whether its problems have been caused by another target it depends on.

    • Used By

      This view shows you the targets that depend on the selected target. This can be useful, for example, if you are planning on shutting down the target and need to know what other targets will be affected

    • System Members

      This view shows the members of the system (available only for targets that are systems).

    • Custom views that have been defined and shared by end users (custom views must be explicitly shared before they are available to others).

    The Uses, Used By, and System Members views are out-of-box topology views. They cannot be modified.

  3. The following operations are available on the Topology page:

35.10.4 Determining System Component Structure

To determine which components (targets and target components) comprise your IT system and their interrelationships, use the Configuration Topology Viewer.

Perform the following steps:

  1. Access the Configuration Topology Viewer.

  2. In the View menu, select System Members (available only if the target is a system). The view displays the relationships between the targets. The target type controls the default view that is shown.

To see the specific relationship between two targets, you can either hover over the link between them and the relationship name will pop up, or select Link Labels from the Annotations menu to display the relationship name on all links.

Note the following:

  • The topology feature is available any time you are in the context of a target: select Configuration from the target type menu, then select Topology.

  • Not all target types have configuration data. For these target types, the Configuration menu and topology graphs are not available.

35.10.5 Determining General Status of Target's Configuration Health

Topology enables you to view system health by displaying relationships among system entities, structure of a target, and target components, thus enabling you to analyze configuration health and status of the configuration.

Perform the following steps:

  1. Access the Configuration Topology Viewer.

  2. On the Configuration Topology Viewer page, icons indicate whether the target is down. You can choose a particular view, for example, Uses or Used By. In addition, icons indicate whether targets have associated incidents.

35.10.6 Getting Configuration Health/Compliance Score of a Target

To determine the configuration health and compliance score of a target, perform the following steps:

  1. Access the Configuration Topology Viewer.

  2. Zoom in on the target that has problems. Problems are represented by icons indicating a problem target status, and icons indicating target incidents. The target you selected in the All Targets page will always be highlighted.

  3. When you hover over a target, click the more link in the popup. Properties for the target are available in the General, Incident Summary, and Configuration tabs. The Configuration tab shows information about target compliance, configuration changes in the past week, and recommended patches. Links from these values lead to more detailed reports.

    If incidents are reported in the Incident Summary tab, resolve the reported events and incidents. Compliance information is available through the Configuration tab. If the target is not compliant, resolve the issue. Also if patches are missing, apply them.

  4. Repeat the process of analyzing the various targets until all targets are functioning properly.

35.10.7 Analyzing a Problem and Viewing a Specific Issue in Detail

When you drill-down in topology graphs, you can have a detailed view of the specific issue that could be the cause of the problem.

Perform the following steps:

  1. Access the Configuration Topology Viewer.

    From the Targets menu on the Cloud Control home page, select All Targets. In the table, click the appropriate target. On the resulting page, select Configuration then select Topology from the dynamic target menu.

    To view target data, place the mouse over the node and continue to move the mouse to >>. The popup containing data appears. Select more for additional information. The links associated with the data lead to the detail pages.

  2. View configuration history changes.

    From the dynamic target menu, select Configuration, then select History. On the Configuration History page, determine whether there has been a history change in the last 24 hours. If so, view those changes in detail for that particular target.

  3. View compliance violations, incidents, and unauthorized changes.

  4. View critical or warning incidents generated for a particular target.

    From the Enterprise menu, select Monitoring, then select Incident Manager.

  5. Determine whether there are patch recommendations.

    On the Topology page, hover over an element and click more in the popup. Click the Configuration tab and determine whether Patch Advisories have been addressed.

35.10.8 About Dependency Analysis

Dependency analysis, also known as root cause analysis, traverses the relationships top to bottom to see if there is cause of a problem due to an issue with an asset on which the item is dependent.

To find the source of a target's health problem, perform the following steps:

  1. Access the Configuration Topology Viewer.

  2. In the View list, select Uses. This shows a topology of the targets that the selected target depends on.

    Paths to the target or targets potentially causing the problem are colored.

    If your target is not up, paths to the target or targets that may be causing the problem are colored. Red links lead from your target to targets that are down, and yellow links lead to targets whose status is not known.

    By default the topology includes all depths of the tree, including the dependency relationships between those targets.

35.10.9 About Impact Analysis

Impact analysis traverses the relationships from the bottom to the top of the tree to see if a problem will occur if changes are made to the element (target or system) in which I'm interested. It answers the question: What items are dependent on my element that would be effected should I do something to my element. For example, if I shut down a listener, what databases would be affected?

Perform the following steps:

  1. Access the Configuration Topology Viewer.

  2. On the Topology page, analyze the Used By view. The topology will show the targets that depend on the selected target.

35.10.10 Creating a Custom Topology View

Create a custom topology view to include only those targets of interest, perhaps for a specific task or report. From a custom view, you can also augment the relationship data provided by Cloud Control.

Perform the following steps:

  1. Access the Configuration Topology Viewer.

  2. From the Customize menu, select Create Custom View.... Provide the name and description for the topology and select one of the Initial Contents:

    • Copy Current View to create a topology view similar to the one you are viewing.

    • Create Empty View to create a topology view that starts with the root node.

    Also, choose one of the following expose options:

    • Expose the custom view for all targets of the current target type. For example, if you are creating at a topology view for a database target, the new view will be available for all database targets.

    • Expose the custom view for the current target only.

    To share the view, click Share this custom view with other users.

    Click OK.

  3. Reduce the unwanted information in the topology by highlighting the target and selecting Hide Relationships... in the Customize menu.

    You can also display relationships that are not being displayed by selecting a target. From the Customize menu, select Target, then select Show More Relationships to Target Type....

    Privileged users can also choose to share their custom views with other users. To share a custom view, select the checkbox labeled Share this custom view with other users.

  4. Click OK.

35.10.11 Deleting a Custom Topology View

When a custom topology view is no longer of use, delete it so it no longer clutters the View list. Note: System owned views cannot be deleted.

Perform the following steps:

  1. Access the Configuration Topology Viewer.

  2. From the View list, select the topology view you want to delete.

  3. From the Customize menu, select Delete Custom View...

  4. Click Delete Custom View in the confirmation popup.

35.10.12 Excluding Relationships from a Custom Topology View

After you create a topology view, you may want to remove some of the targets displayed in the custom view. Note that you cannot modify the out-of-box topology views: Uses, Used By, and System Members.

Perform the following steps:

  1. Access the Configuration Topology Viewer.

  2. From the View list, select the topology view you want to change then select the target.

    Note: System created views cannot be modified.

  3. From the Customize menu, select Hide Relationships....

  4. The list of relationships that are displayed in the graph are listed in the Hide Relationships page. You can multi-select the relationships to exclude from the graph. Click OK.

35.10.13 Including Relationships to a Target in a Custom Topology View

After you create a topology view, you may find it necessary to include more relationships in the custom view. This will add targets to your custom view if they are related to the currently displayed targets using relationships you include.

Perform the following steps:

  1. Access the Configuration Topology Viewer.

  2. From the View list, select the custom topology view you own or have the privileges to change. System views such as Uses, Used By, and System Members cannot be modified.

  3. Highlight a target from which to expand the topology. From the Customize menu, select Target, then select Show More Relationships to Target Type....

  4. The resulting dialog shows a list of the relationships that the selected target type can participate in. Select the relationships of interest, and click OK. Any targets that are related to the selected target type using the selected relationships will be added to the topology view.

35.10.14 Creating a Relationship to a Target

In cases where you find that Cloud Control has incomplete information about your systems, you can create relationships between targets.

Note: Once new relationships are created, any topology showing the specified relationships and containing the targets will automatically show the new relationships.

Perform the following steps:

  1. Access the Configuration Topology Viewer.

  2. From the View list, select the topology view you want to change then select the target.

  3. Select a target in the topology to be one end of the relationship.

  4. On the Create Custom View page, provide a name and description, choose the initial contents, and determine how this custom view should be exposed. Click OK.

  5. From the Customize menu, select Target, then select Create Relationship to Target....

  6. On the Create Relationship to Target page, select the related target and the relationship between targets. Only relationships that the target type can participate in are shown in the list. Not all target types can be related to each other.

    Note: Created relationships are independent of the view. You can see and use created relationships in other areas of Cloud Control, such as System templates, topology views, and configuration comparisons. Deleting a custom view will not delete the new relationship.

  7. On the Confirmation page, click Create.

The related target will be added to the view.

35.10.15 Deleting a Relationship from a Target

If you have created a relationship between two targets, you may decide that the relationship no longer exists. Reflect this change by deleting extraneous relationships where appropriate. Note that once relationships are removed, they no longer show in any topology views.

Perform the following steps:

  1. Access the Configuration Topology Viewer.

  2. From the View list, select a custom view.

  3. Select the link to the relationship you want to delete. You can either right click the node to view the context menu that allows you to delete the relationship or, from the Customize menu, select Relationship, then select Delete Relationship....

  4. On the Confirmation page, click Delete.

Relationships are used in various places in Cloud Control, such as System templates, topology views, configuration comparisons, and so on. Deleting a relationship from this topology can impact these other areas.

If you create a relationship, you can later delete it by using the Delete Relationship... menu item.

35.10.16 Controlling the Appearance of Information on a Configuration Topology Graph

To control the way the targets are displayed in a custom topology, you can customize the tier in which a target type is shown, and you can group target types together.

The tier in which a target type is shown will affect its vertical or horizontal placement in the topology, depending on whether the layout is left-right or top-down.

To customize the appearance, perform the following steps:

  1. Access the Configuration Topology Viewer.

  2. Create or select an existing custom view.

  3. To control highlighted paths to targets that are down, toggle the "Highlight 'Down' Root Cause" menu item.

    When this menu item is selected and the root target is down, paths from the root node to other down targets are highlighted. By visually following the highlighted paths, you may determine which targets are causing the root target's down status.

    Note:

    When this option is selected, you will not be able to group nodes together.
  4. To manipulate tiers:

    1. On the Customize menu, select Select Tiers.

    2. Select either Specify Tiers or Use Default Tiers. If you choose to specify tiers, drag target types to their desired tier.

  5. To turn the coloring of the links on and off, on the Customize menu, select Highlight "Down" Root Cause.

  6. To group targets:

    1. Select a link that represents one or more associations between the source and destination target types.

    2. On the Customize menu, select Relationship, then select Group Targets...(Another way to select group targets is to right mouse click a link and select Group Targets.)

      All matching associations are placed into group boxes.

Note:

Grouping targets is not possible when "Highlight 'Down' Root Cause' is selected.