N1 Service Provisioning System 4.1 User's Guide

Chapter 7 Comparisons

Comparisons are used to validate an installation or system configuration. By comparing the configuration of a host against its original configuration you can tell if anything has changed. You can also compare one or more hosts against a reference host to ensure that all hosts are configured the same. With the N1 Service Provisioning System software you can compare one or more hosts against another host, one or more hosts against a model in the Master Server, or a host against its original configuration. The provisioning software allows you to check the entire configuration of a host or limit what is checked to a single directory.

When you have run a comparison, you can save the output to a file and view it in a standard application such as Excel.

This section discusses the following topics:

Snapshots

Snapshots are an advanced feature that define what a component should capture at the time it is installed and when it is analyzed for differences. Snapshots are largely a change management tool that helps in the process of detecting when a component installation has changed.

Because the source items for a component is deployed in the order in which they are listed in the component's XML file, it's possible for one source item to overwrite another that has already been deployed, if they both have the same name.

How Snapshots Help

One way that a snapshot is used is to validate that a deployment was done correctly. Because the source items for a component is deployed in the order in which they are listed in the component's XML file, it's possible for one source item to overwrite another that has already been deployed, if they both have the same name.

For example, you may have a component that installs the source for a component named pockets onto a host. One source (S1) of the pants component, pants/config.txt may be deployed, followed by a second, different source (S2), also pants/config.txt. If you were then to go and look at pants/config.txt you might think you were looking at S1, when in fact, config.txt now reflects the contents of S2. To avoid this sort of difficulty, you can define a snapshot that the provisioning software can use to make sure the correct baseline, post installation version of config.txt is used in any Model-to-install comparisons.

Another way snapshots are useful is when a component's source items might be transformed using the transform element, or otherwise changed during the course of deployment by an execNative call that you have defined. Without a snapshot of the “just installed” state, a Model-to-Install comparison would be made against the source items before they were deployed, which would lead to errors in the results.

It is not necessary to define a snapshot block, or specify that one be used, in your components. However, if one is not specified, the installed component that you are comparing against the model will contain no snapshot information, and will never present any differences.

Types of Comparisons and Their Features

N1 Service Provisioning System software allows you to perform three types of comparisons:

Model to Model (M-M)
Model to Install (M-I)
Install to Install (I-I)

Model to Model Comparisons

A Model to Model comparison is the simplest type of comparison. It compares the list of components that the provisioning software has installed on one host with the list of components that the provisioning software has installed on another host. This is purely a comparison of the records that the provisioning software has about what it has installed. If there have been out of band changes made to either component list, they will not be detected. A Model-to-Model comparison takes place entirely on the Master Server based on information it has received about what has been deployed.

Model-to-Install Comparisons

A Model-to-Install comparison compares the `just installed' state of the resources in a component or components to their current state on a given host or host set. You can specify that this comparison compares the model to hosts, host sets, or to component level.

A Model-to-Install comparison uses information about what components and subsequent resources have been deployed to a given host based on snapshot information. A snapshot is a record of the state of an installed component immediately after it has been deployed to a host. The component's XML model includes parameters that control the scope of this snapshot. For example, the XML model can list files, such as log files, that should be ignored during a comparison.

When the provisioning software performs a Model-to-Install comparison, the Master Server looks up the list of snapshots for all the components being compared. It sends this list to the Remote Agent on the host where the components are installed. The snapshot information includes rules for any files and directories that should be ignored during the comparison. The Remote Agent then processes these rules. Both Master Server and Remote Agents must be using the same locale for the Model-to-Install comparison to function properly.

Unlike Model-to-Model comparisons, which compare one ideal installation to another, Model-to-Install comparisons compare the actual state of the installed component or components at deployment time against their current state.

Install-to-Install Comparisons

Install-to-Install comparisons compare the current states of the contents of directories in components that the provisioning software has installed on two different hosts. The list of elements (files, directories, and so on) from the reference host being compared in an Install-to-Install comparison are grouped into batches on the Master Server and then sent to the Remote Agent of the comparison host for processing. If you have defined some rules about file types or specific directories or files for the provisioning software to ignore, the Master Server will discard the appropriate items before sending the remainder of the list to the comparison host. The Remote Agents from each host must be set to use the same locale for Install-to-Install comparisons to function properly.

You can provide the provisioning software with scripts to be run before and after the comparison occurs, in case you need to manipulate files before running the comparison or need to clean up any files you have manipulated to prepare for the comparison.

Why Use Scripts in Install-to-Install Comparisons?

If the components you are comparing include resources that stored in a package, a database, or an archive such as a ZIP file, you can use scripts to export or transform the resources before the comparison occurs. Use execNative step to direct the provisioning software to perform native commands such as unzipping or exporting file contents.

Using Scripts in Install-to-Install Comparisons

You can run any native command within the prepare and cleanup blocks. A common usage of these blocks before and after a comparison is to extract the files from a compressed archive and output them to a specified output file, then delete that file during the cleanup.

Note –

Unlike the execNative contained in a plan or component, this execNative instance must be contained within either a <prepare> or a <cleanup> block, and cannot make use of any variable substitutions.

When you are performing an Install-to-Install comparison using the HTML user interface, you can select a checkbox labeled include temporary files generated by scripts during comparison. When you select this option, the page refreshes and provides two fields into which you can enter the prepare and cleanup blocks.

You can also specify alternate prepare/generate and cleanup blocks for the target host by un-selecting the appropriate boxes.

You can enter scripts such as these into the fields:

This prepare /generate block specifies the output file for the result of the execNative. The execNative lists the contents of the /tmp directory.

<prepare>
  <execNative outputFile="file.txt" dir="temp">
    <exec cmd="ls">
      <arg value="-l"></arg>
      <arg value="/tmp"></arg>
    </exec>
  </execNative></prepare>

This cleanup block then removes the outputFile, file.txt, from the temp directory.

<cleanup>
  <execNative  dir="/temp/">
    <exec cmd="rm">
      <arg value="-rf"></arg>
      <arg value="file.txt"></arg>
    </exec>
  </execNative></cleanup>

Running Comparisons

Time Synchronization for Comparisons

Because the time stamp for a comparison is based on the clock in the Master Server, it is a good idea to run some kind of synchronization utility on all your N1 Service Provisioning System software machines so that all system clocks are synchronized on the same time.

M-I (Model to Installation) Comparisons

An M-I comparison (sometimes called an M-I difference) is a comparison of a component model to a specific installation of a component. When relevant, this chapter's description of a resource type will include information about how the format or content of a resource type affects an M-I comparison.

During a snapshot the current state of the metabase is exported into an XML file. During an M-I comparison, the metabase is re-exported and compared against the original XML file.

M-I Comparison for IIS Types Introduction

During a snapshot the current state of the metabase is exported into an XML file. During an M-I difference the metabase is re-exported and compared against the original XML file. The standard XML differentiator is used to generate differences between these files.

M-I Comparison for COM+ Application

The COM+ Application is re-exported on the target system as an MSI file and compared against the MSI file used to install the application. M-I difference will only indicate that there were differences (i.e. the two binary files are different) but will not indicate the details of the differences.

M-I Comparison for COM Component

The COM component is compared as a binary file against the file used during installation. M-I difference will only indicate that there were differences (i.e. the two binary files are different) but will not indicate the details of the differences.

M-I Comparison for H Keys

During a snapshot the current state of registry key (and its children) is exported into an XML file. During an M-I difference the registry key is re-exported and compared against the original XML file. The standard XML differentiator is used to generate differences between these files.

M-I Comparison for Registry Settings

M-I Differencing is not supported for *.reg files. Snapshots will not be taking during installation resulting in nothing to difference during the M-I difference. If the user would like to difference registry changes they are encouraged to use the built-in Registry keys type.

M-I Comparison for MSI Files or Windows Installer Files

M-I Differencing is not supported for Windows Installer files. Snapshots will not be taking during installation resulting in nothing to difference during the M-I difference. Since ROX does not have first-hand knowledge of the actions taken during the installer run it is not feasible to determine what needs to be captured.

M-I Comparison for Windows Batch Files

M-I Differencing is not supported for Windows Batch files. Snapshots are not taken during installation resulting in nothing to difference during the M-I difference.

M-I Comparison for Comparison for Windows Scripting Host Files

M-I Differencing is not supported for WSH files. Snapshots will not be taking during installation resulting in nothing to difference during the M-I diff.

M-I Comparison for WebLogic WAR Files

Will use the standard file/directory MI difference approach.

M-I Comparison for WebLogic Web Application Settings

The relevant settings for the application will be exported into a file, which will be compared to the file that contained the settings during deployment.

M-I Comparison for WebLogic JAR Files

Will use the standard file/directory MI difference approach.

M-I Comparison for WebLogic EJB Settings

The relevant settings for the EJB will be exported into a file, which will be compared to the file that contained the settings during deployment.

M-I Comparison for WebLogic EAR Files

Will use the standard file/directory MI difference approach.

M-I Comparison for WebLogic Enterprise Application Settings

The relevant settings for the Application will be exported into a file, which will be compared to the file that contained the settings during deployment.

Comparisons User Interface

The Comparisons Page

The Comparisons user interface provides the functionality for users to create, run, and view the results of comparisons.

This page also contains controls for filtering the component list and selecting sort criteria. There are blue wedge shaped arrows over the comparison column that allow you to sort the list by and in either ascending or descending order.

Comparison: A user definable text string that names the comparison object. By default, the comparisons are listed in alphabetical order by component name. You can change the sort order between ascending and descending by clicking on one of the sort icons that is in the plans header area.
Description: An optional user defined text string that describes the comparison object. This attribute is not used by the provisioning software but can provide meaningful information to the user.
Action: Links that take you to other comparison related pages to either create, view details for, or view the results of comparisons.
Actions for Checked Plans: From this area you can either delete or apply categories to the checked plan(s)

The Comparisons Details Page

The details page for comparisons is different for each of the three types of comparisons.

The Comparisons Details Page for M to M

Comparison

Displays the names the comparison object.

Category

A user definable object that is used to filter the comparisons list. Categories are created using the categories page accessed from the Administrative page. Categories are then applied to a plan from the plans page. Categories can also be created by clicking in the “Apply Categories . . .” link.

Description

An optional user defined text string that describes the comparison object. This attribute is not used by the provisioning software but can provide meaningful information to the user.

Style of Comparison

This allows you to select the type of comparison you want.

Model to Model: Sets up the user interface to run a model to model comparison.
Model to Install: Sets up the user interface to run a model to install comparison.
Install to Install: Sets up the user interface to run an install to install comparison.

Reference Host

Specifies which hosts model to use as a reference model for the comparison.

Comparison Host

Specifies which hosts model to compare to the reference host's model.

Limits

This allows you to set a time limit for the provisioning software to complete the comparison. Some types of problems can cause the provisioning software to wait endlessly while attempting to take a snapshot of an installation. This feature provides a time-out to prevent the provisioning software from never finishing a comparison.

Buttons

By clicking one of these buttons you initiate one of the following functions.

Save: Saves the comparison using the current name.
Save As: Saves the comparison using a different name.
Save & Run: Saves the comparison using the current name and performs a comparison.
Previous Results: Displays previous results of a comparison.
Delete: Deletes the comparison.
Cancel: Takes you to the comparisons page without saving any changes.

The Comparisons Details Page for M to I

This comparison allows you to validate that current state of an installation by comparing it to its last know good state.

Because only the model reference and comparison object area changes, the following discussion will focus only on the area of the comparisons page that is different.

Scope: This is a pull down menu that allows you to limit the scope of the comparison to either a host set, a host, or component.

Host Set - changes the following field on this page to allow you to select which host set to compare. The provisioning software then compares that last known state of the specified host set to its current state.

Host - changes the following field on this page to allow you to enter a host name to compare. The provisioning software then compares that last known state of the specified host to its current state.

Component - changes the following field on this page to allow you to enter a host name and component path to compare. The provisioning software then compares that last known state of the specified component to its current state.

Directories & Files to Ignore During Comparison: Allows you to specify things to ignore during this comparison. This feature allows the provisioning software to accommodate changes to things like log files without causing the comparison to fail.

The Comparisons Details Page for I to I

This comparison allows you to validate that current state of an installation by comparing it to an other know good installation.

Because only the model reference and comparison object area changes, the following discussion will focus only on the area of the comparisons page that is different.

Reference Host: Specifies which hosts to use as a reference model for the comparison. This also includes a second field that requires that you specify where in the hierarchical files structure to limit the comparison. If you use the top of the tree structure you will evaluate the entire host.
Comparison Host: Specifies which hosts to compare to the reference host's model. This also includes a second field that requires that you specify where in the hierarchical files structure to limit the comparison.

Options

Defines some parameters when taking a snapshot of the host.

Include All Sub-Directories in Comparison — This causes the provisioning software to recursively follow all subdirectories. within a parent directory.

Follow Symbolic Links Found in Directories — This causes the provisioning software to resolve symbolic links to determine that what the link points to is also valid.

Include Temporary Files Generated by Scripts During Comparison — This causes the provisioning software to include any legacy files generated by running a script. This can be used to verify that a particular script has or has not been run on all the hosts included in the comparison.

Directories & Files to Ignore During Comparison

Allows you to specify things to ignore during this comparison. This feature allows the provisioning software to accommodate changes to things like log files without causing the comparison to fail.

How To View Comparisons List

Step

In the left-hand navigation menu, click comparisons.

The HTML user interface displays the comparisons page, which lists the comparisons already checked in to the database. By clicking on one of the sort arrows in the header yo can change the sort criteria.

How To View Comparisons Details

Steps

In the left-hand navigation menu, click comparisons.

The HTML user interface displays the comparisons page, which lists the comparisons already checked in to the database.

Find the row listing the plan you're interested in, and click details.

The HTML user interface displays the comparisons Details page for the comparison.

How To Create an M to M Comparison

Steps

In the left-hand navigation menu, click comparisons.

The HTML user interface displays the comparisons page, which lists the comparisons already checked in to the database.

Find the row listing the plan you're interested in, and click details.

The HTML user interface displays the comparisons Details page for the comparison.

On this page you select the type of comparison you want to define, and you define parameters for the comparison. When the page is first displayed, it is configured for a Model-to-Model comparison.

In the style of comparison area, leave model to model selected.

In the reference host field, enter the name of the host whose model should serve as the reference (the standard) for the comparison. If you like, you can click select from list to perform a host search to find the host.

In the comparison host field, enter the name of the host whose model you would like to compare to the reference model. If you like, you can click select from list to perform a host search to find the host.

In the fields labeled limits, specify the maximum number of hours or minutes the comparison should run. By default, comparisons are allowed to run for 4 hours.

Click save to save the comparison.

How To Create an M to I Comparison

Steps

In the left-hand navigation menu, click comparisons.

The HTML user interface displays the comparisons page, which lists the comparisons already checked in to the database.

Find the row listing the plan you're interested in, and click details.

The HTML user interface displays the comparisons Details page for the plan.

Click the button labeled model to install.

The HTML user interface displays the page, which now contains fields for defining a model-to-install comparison.

Use the pull-down menu at the end of the model to install line to specify the contents that should be used in the comparison:
- directory and file properties Select this choice to confirm that both hosts have the same files and directories and that the files and directories are the same sizes.
- file contents Select this choice if you want to determine if there are any differences in the contents of files on the two hosts.
  
  Note –
  If the component you are using in a comparison includes its own rules about files to ignore, they will be used in addition to any ignore rules you define for this comparison.

In the scope drop-down list, select whether you want to compare host or host set, or a component.

Specify the name of the host or host set.

If you have specified a scope of `component', perform the following steps:
1. Specify the name of the host on which this component exists.
2. Refresh the screen by clicking Apply change.
3. Select the path to the component.

Set a time limit for the comparison using the limits controls.

Once you've set a time limit, you can choose to save the comparison to run later or run it right now.

Do one of the following:
- To save the comparison without running it, click save.
- To both save the comparison and run it right now, click save & run.

How To Create an I to I Comparison

Before You Begin

The Remote Agents from each host must be set to use the same locale for Install-to-Install comparisons to function properly.

Steps

In the left-hand navigation menu, click comparisons.

The HTML user interface displays the comparisons page, which lists the comparisons already checked in to the database.

Find the row listing the plan you're interested in, and click details.

The HTML user interface displays the comparisons Details page for the comparison.

Choose a level of detail for the comparison.
- Directory and File Properties — Are all the files and directories there? Are they the same sizes?
- File Contents — Are there any text-level differences between files?

Enter the name of the reference host and the path to the directory you want to compare against the target host.

Enter the name of the comparison host and the path to the directory you want to compare against the reference host.

The Include all subdirectories in comparison checkbox is checked by default.

If you want the provisioning software to run a script before and/or after running this comparison, perform the following actions.
1. Check the Include temporary files generated by scripts during comparison checkbox.
  
  The page will refresh and provide two fields for prepare (generate) and cleanup scripts:
2. Enter the scripts into the appropriate fields.
  
  For information on scripts for prepare/generate and cleanup, refer to Using Scripts in Install-to-Install Comparisons.
3. If you do not want the provisioning software to run the same scripts on the target (comparison) host as on the reference host, uncheck the appropriate boxes.
  - If you uncheck the `generate' checkbox, a field is displayed so that you can provide an alternate prepare/generate script for the reference host.
  - If you uncheck the `cleanup' checkbox, a field is displayed so that you can provide an alternate cleanup script for the reference host.
  If you want to specify resources to ignore during this comparison, proceed to Choosing Directories or Files to Ignore During Comparisons.

Set a time limit for the comparison using the Limits controls.

Once you've set a time limit, you can choose to save the comparison to run later or run it right now.

Choosing Directories or Files to Ignore During Comparisons

In addition to describing the level of detail and what hosts/components/resources you want to compare, if you are comparing a host to a model in the repository, or if you are simply comparing two directories on a host, you have the option of defining sets of files or directories to exclude from a comparison. You might want to do this if you know for certain that certain resources have many differences that are not important to you. You can save these definitions and reuse them in other comparison definitions.

To specify directories or files to be ignored, do the following:

Steps

Enter the name of the directory or file you want to ignore, or provide an expression to represent the directories or files you want to ignore using wildcards (*).

For example, if you want to ignore all log files, you can specify *.log to be excluded.

Note –
You must specify a complete pattern (with or without wildcards) all the way to the file name; simply specifying down to the directory level will not exclude the files in that directory unless you add a * to the end. For example, if you want to exclude all the files in /usr/apache/logs, you must specify /usr/apache/logs*

Click add.

Your specification will be added to the bottom of the list of directories and files to be ignored.

The ignore box is checked by default to mark this directory or file so that it is not included in the system comparison.

If you want to remove this exclusion rule in a future comparison, you can uncheck the ignore box.

Removing a Directory or File from the Ignore List

Step

To remove a directory or file from the ignore list, click on remove.

You can also temporarily disable the ignoring of a directory or file by unchecking the ignore checkbox.

Note –
You cannot remove or disable a global ignore rule.

Canceling a System Comparison in Progress

Step

To cancel a system comparison currently in progress, click cancel.

Note –
If you cancel a comparison in progress, you are returned to the page listing all the comparisons. Occasionally, it may take a short while for the listing to refresh and show you that the comparison you canceled has been stopped. The reason for this is that some comparisons include file transfers between the Master Server and the comparison or reference hosts, and the comparison will not halt in mid-transfer, but will continue until the current file is completely transferred (refer to the description of each sort of comparison at the beginning of this chapter for specific information about files being transferred). The time it takes to refresh the page depends on the size of the file that provisioning software is currently transferring. When the comparison is completely halted, the updated list is displayed.

Running a Saved Comparison When a Component's Version has Changed

If you have saved a comparison involving a component, and that component has been upgraded or its version numbers have changed for some other reason, the provisioning software automatically updates the comparison you saved to run against the new version of the component.

Summary of CLI Commands

Table 7–1 lists the CLI commands related to comparisons.

Table 7–1 Summary of cmp Commands


Command Name	Description
cmp.dj.add	Adds (starts) a new comparison.
cmp.dj.del	Deletes (stops) a new comparison.
cmp.dj.la	Lists running and completed comparisons.
cmp.dj.lo	Retrieves a running comparison to display its status.
cmp.ds.add	Adds comparison settings to the specified comparison.
cmp.ds.la	Lists all comparison settings.
cmp.ds.lo	Retrieves the specified comparison settings.
cmp.ds.sc	Associates a comparison settings with a set of categories.
cmp.ds.mod	Modifies the specified comparison settings.