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

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.

Creating a Custom Target Type

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

Before creating 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.

From the Enterprise menu, select Configuration, then select Configuration Extensions. On the Configuration Extensions page, select Create Custom Target Type from the Actions menu.
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.
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.
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.
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.

Creating or Editing a Configuration Extension

Use the following instructions 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 About Configuration Extensions and Privileges.

Note:

When you edit a deployed configuration extension, it is automatically redeployed upon saving. This does not apply to saving as draft.

In the Configuration Extensions library, click the Create button; or, select an existing specification in the library and click Create Like or Edit.
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.
Select a target type from the drop-down menu.
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.
For instructions on how to complete the Files & Commands tab, see Using the Files & Commands Tab
For instructions on how to complete the SQL tab, see Using the SQL Tab.
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.
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 About Configuration Extensions and Versioning.
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 About Configuration Extensions and Deployment.

Using the Files & Commands Tab

Create file and command specifications as follows:

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.
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 and command 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 Setting Up Credentials When Creating a Configuration Extension for more information.
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 Managing Parsers for more information.

Optionally, specify post-parser rules to align tree nodes. See Setting Up Rules for information on entering rules.
Repeat Step 3 to specify additional files or commands.

Return to Creating or Editing a Configuration Extension and resume with 7.

Using the SQL Tab

Create SQL query specifications as follows:

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 Setting Up Credentials When Creating a Configuration Extension). Configuration extensions only support database credentials with NORMAL roles, not those with SYSDBA, SYSOPER, or other roles.
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.example.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.
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.

Optionally, specify post-parser rules to align tree nodes. See Setting Up Rules for information on entering rules.
Repeat Step 3 to specify additional SQL queries.

Return to Creating or Editing a Configuration Extension and resume with Step 7.

Setting Up Credentials When Creating a Configuration Extension

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:

From the Setup menu (top right of the page next to the Help menu), select Security, then select Monitoring Credentials.
Select the applicable target type in the table and click Manage Monitoring Credentials.
Select the row with the credential set name you created during the configuration extension definition for the given target type and click Set Credentials.
Enter the username and password for the credential set and click Save (or Test and Save for database credentials).
Return to the Files & Commands tab (Using the Files & Commands Tab) or SQL tab (Using the SQL Tab) description.

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:

Click the Parser Rules button. The Edit Parser Rules page displays.
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.
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 Using Parsed Files and Rules.

Return to the Files & Commands tab (Using the Files & Commands Tab) or SQL tab (Using the SQL Tab) description.

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.

In the Configuration Extensions library, select the specification table row and click View Details.
Peruse the settings and rules on the various tabs.

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.

In the Configuration Extensions library, select the specification table row, then select Export from the Actions menu.
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.

In the Configuration Extensions library, select the specification table row, then select Import from the Actions menu.
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.

In the Configuration Extensions library, select the specification table row and click Delete.
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.

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.

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.

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:

Deploying and Undeploying Configuration Extensions

To deploy a configuration extension:

In the Configuration Extensions library, select the specification table row and click Manage Deployments.
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.
When you close the dialog (click Select), a new column appears denoting a pending action of Deploy and the status becomes Selected for Deployment.
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.
Click Refresh Status on the Deployments page to confirm a successful outcome.

Usually, if you update a deployed configuration extension (CE), redeployment occurs automatically. However, redeployment will not be initiated when certain CE attributes are modified, such as the sample target.

To undeploy a configuration extension:

On the Deployments page, select the deployment in the table.
Click Remove. A new column appears denoting a pending action of Undeploy; status remains Deployed.
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.
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 currently deployed configuration extensions. The number in the column indicates how many targets the configuration extension has been deployed to. Click the number to navigate to the relevant deployments page.

Editing a Deployment of Configuration Extensions

To edit a deployment, follow these steps:

In the Configuration Extensions library, locate the appropriate table row and click the numerical link in the Deployments column. In addition, you can, after selecting the configuration extension table row, click the Manage Deployments button in the toolbar.
On the Deployments page, select the deployment in the table and click Edit.
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. Click OK.
After closing the Edit dialog, 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 Save to initiate the redeployment and navigate back to the Configuration Extension library page
- Click Cancel to void the request and return to the library.
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 not change the configuration extension definition.

Viewing a Configuration Collection

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

In the Configuration Extensions library, locate the appropriate table row and click the deployments link.
On the Deployments page, select the deployment in the table and click View Configuration.
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.

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

Extending Existing Target Collections

The following instructions 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 as provided by Oracle. To extend the listener data collection to include this item, take the following steps:

From the Enterprise menu, select Configuration, then select Configuration Extensions.
In the Configuration Extensions library, click the Create button.
Give the configuration extension an appropriate name and select Listener as the target type.
Click Select Target to choose a listener instance that is already deployed, so you can browse to the file location. Note that clicking this link selects a Sample Target for the configuration extension.
Set the Default Base Directory to OracleHome.
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.
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.
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.
In the Configuration Extension library, select the new configuration extension and click Manage Deployments.
On the Manage Deployments page, click Add. In the dialog that opens, select the targets where you want to deploy the configuration extension.
When the status displays Selected for Deployment, click Apply. Refresh the view until status is successful, then click Save.
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.

Adding New Target Data Collections

The following instructions 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.

From the Enterprise menu, select Configuration, then select Configuration Extensions.
From the Actions menu, select Create Custom Target Type.
In the dialog that opens, enter a target type name, MyApache, for example. Click OK.
After a while, a message confirms target type creation. Click Yes to add a sample target instance.
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.
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.
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.
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.
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.
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.
In the Configuration Extensions library, select the new configuration extension and click Manage Deployments.
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.
When the status displays Selected for Deployment, click Apply. Refresh the view until status is successful, then click Save.
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.
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.