Explanation of AIX ODM VPD and its relationship with WebSphere Application Server products

Resolving The Problem

The following provides information about the AIX ODM VPD and how the WebSphere Application Server product installers interact with it.

What is the purpose of this discussion?
The AIX Object Data Manager Vital Product Data tables (ODM VPD) is a complex aspect of AIX and must be treated carefully. This discussion explains the ODM VPD's relationship with the WebSphere Application Server product installer, and outlines the methods which can be used to repair ODM VPD damage which affects those products.

The ODM VPD is used to track data associated with WebSphere Application Server product installations. Under some circumstances, the data in these tables can be come corrupt or lost. The corruption or loss of this data can cause issues for the WebSphere Application Server product installer or uninstaller. In order to resolve these issues, the ODM VPD needs to be "cleaned" in some manner in order to repair the damage.

This article gives in-depth details about the ODM VPD. This answers many frequently asked questions about why ODM VPD cleanup is necessary and what effects can come about from an ODM VPD cleanup. Instructions for system administrators that give an in-depth explanation of how to handle cleanup procedures are covered in a separate technote, 1231062.

Generally, system administrators will want to use the "complete cleanup" scripts. The scripts are provided in technote 1198862.


Which products does this apply to?
This discussion describes the ODM VPD's relationship with the following products:

• WebSphere Application Server (base edition) V5.0, 5.1, 6.0, 6.1, and 7.0
• WebSphere Application Server Network Deployment V5.0, 5.1, 6.0, 6.1, and 7.0
• WebSphere Application Server Express V5.0, 5.1, 6.0, 6.1, and 7.0
• WebSphere Application Client V5.0, 5.1, 6.0, 6.1, and 7.0
• WebSphere Application Server Enterprise Edition V5.0
• WebSphere Business Integration Server Foundation V5.1
• IBM HTTP Server V1.3, 2.0, 6.0, 6.1, and 7.0

Other WebSphere products not listed here are outside the scope of this article. Other WebSphere products might utilize the ODM VPD in a different manner than described in this article. Also, note that WebSphere Application Server V8.0/v8.5 and later utilizes IBM Installation Manager for the installation process, and Installation Manager does not register entries in the ODM when V8.0 and higher version is installed.

This article was written with consideration to AIX release 5.1 and later. Earlier AIX versions manage the ODM in a different manner, which is beyond the scope of this article.


What is the Object Data Manager, or "ODM"?
The Object Data Manager, also referred to as the "ODM", is an object-oriented database system provided with the AIX operating system. The ODM is optimized to store system information, such as adapter card configuration, file system characteristics, and communications information.

The ODM is packaged with several command-line tools which allow manipulation of the information in the database. These tools allow the user to run simple database queries, add information to the ODM database tables, or delete entries from the ODM database tables. Most configurable system properties which are contained in the ODM can be manipulated using the SMIT tool, so under most circumstances it is not necessary to manually manipulate ODM data using the ODM tools.

A single AIX system may contain multiple ODM databases stored in separate locations. Each ODM database instance is stored as a collection of binary data files in a directory.

Under normal circumstances, WebSphere Application Server products make use of the ODM database in the following directory:

/usr/lib/objrepos

What is Vital Product Data, or "VPD"?
Vital Product Data, also referred to as the "VPD", is a collection of configuration and informational data associated with a particular set of hardware or software. In the context of WebSphere Application Server, the VPD refers to a subset of database tables in the ODM which contains information about WebSphere Application Server product installation instances. In other words, the VPD is the part of the ODM with which WebSphere Application Server products interface.

The VPD is considered a subset of the ODM. Therefore, the "VPD" and "ODM" are sometimes referred to interchangeably. In the context of this discussion, this will be referred to as the "ODM VPD".

In terms of WebSphere Application Server products, the VPD is comprised of five database tables:

• inventory
• lpp
• product
• history
• vendor
  

Why is the SMIT tool unable to uninstall the ODM VPD data associated with WebSphere products?
The WebSphere Application Server software packages tracked by the ODM are not "traditional" software packages. The packages act as "stubs" which indicate that the package exists on the system, but the packages do not contain the traditional data to indicate the content of the package. As a result, the standard facilities used to uninstall packages (such as SMIT) are not sufficient for handling the uninstall process for WebSphere Application Server packages.

If SMIT or other related utilities are instructed to uninstall the WebSphere ODM VPD data, the utility will throw an error indicating that it is not possible to uninstall the package without using an uninstall program.


What is the "vpd.properties" file?
WebSphere Application Server software packages use data attributes which are not stored in the ODM VPD itself. These data attributes are instead stored in a file named vpd.properties, which is located here:

/usr/lib/objrepos

The data in the vpd.properties file correlates to the data stored in the ODM VPD. In other words, if a WebSphere Application Server software package is registered in the ODM, an entry for that package is also recorded in the vpd.properties file.

As WebSphere Application Server product entries are removed from the ODM, the corresponding entries should be removed from the vpd.properties file. The technotes which explain how to handle the cleanup process document the steps necessary for cleaning up the vpd.properties file.


How do the WebSphere Application Server products utilize the ODM VPD?
WebSphere Application Server products use the ODM VPD to track which WebSphere products and features are installed on the system. The ODM VPD entries record information such as the product installation directory, individual files installed, and optional features installed.

The information recorded in the ODM VPD is used by the WebSphere installer to determine whether certain WebSphere Application Server products are installed on the system. This allows the installer to determine whether or not a WebSphere product is present in the directory targeted for installation. If WebSphere is already present, then the installer gives the administrator the opportunity to add features to the existing installation. When features are added to an existing WebSphere product installation, the installer determines which additional packages need to be installed based on the information present in the ODM VPD.

Certain WebSphere products extend the functionality of an existing WebSphere Application Server product. Some of those products require the existing product's ODM VPD information to be present when installing the extension product. The Content Manager product is one such example of a product which requires the WebSphere Application Server product's ODM VPD information to be intact to perform an installation. Other extension products, such as WebSphere Application Server Enterprise Edition V5.0, do not require the ODM VPD information in order to install the extension product.

The updateInstaller utilities for WebSphere Application Server V5.0 and V5.1 use the ODM VPD to determine which WebSphere products are installed on the system and which directories they are located in. Only the update wizard (the "GUI") utilizes the ODM VPD for this purpose. The "silent" update feature does not read the ODM VPD entries.


How do the WebSphere Application Server products NOT utilize the ODM VPD?
It is important to note that the ODM VPD information is NOT used by the application server runtime. In other words, an application server does not read ODM VPD information, so the application server is not concerned whether the ODM VPD information is present or not. This means that even if the ODM VPD information is removed, the application server will continue to behave the same way as when the entries were present.

The WebSphere Application Server ODM VPD entries do not keep records of the exact version of WebSphere installed on the system. The ODM VPD entries are aware of the product release (for example: 5.0, 5.1, or 6.0), but the entries do not track the fix packs, cumulative fixes, or refresh packs which are installed. For example, the ODM VPD entries do not differentiate between version 5.1.1.2 and 5.1.0.0; instead, the ODM VPD entries only show the fact that the product is release 5.1. The updateInstaller utility does not write to the ODM VPD after installing a maintenance pack, nor does it require the ODM VPD information to be present for a maintenance pack to be successfully installed.

Although these entries do not have significance for certain product functionality, the entries do have significance elsewhere. As mentioned above, the ODM VPD entries do have significance to WebSphere product installers.


What problems associated with WebSphere Application Server products and the ODM VPD?
There are two WebSphere product issues commonly associated with the ODM VPD. Each problem has common symptoms and similar solutions.

Problem 1: AIX migration loses certain entries from the ODM VPD
During AIX migration (for example, migrating from AIX 5.1 to AIX 5.2), the "vendor" ODM VPD table is lost. If a WebSphere product is installed on the system, then the ODM VPD entries in the vendor table are lost, but the ODM VPD entries in other tables remain intact. This leaves the ODM VPD in an inconsistent state. (Note that the ODM VPD only enters this inconsistent state if WebSphere products are already present on the system when migration takes place.)

Attempting to install WebSphere product on a system with an inconsistent ODM VPD will most likely result in the following error, which appears in the log.txt file written to the product installation directory or /tmp directory. Note the keywords highlighted in this example to illustrate the specific error:

java.lang.NullPointerException at
com.installshield.product.SoftwareObjectUtils.updateKey
(SoftwareObjectUtils.java:21) at
com.installshield.product.service.product.PureJavaProductServiceImpl$
InstallProduct.addToVPD(PureJavaProductServiceImpl.java:4664)
[error truncated for brevity]


Problem 2: A WebSphere product is deleted without running the uninstall program
This problem covers scenarios where a WebSphere product is deleted without running the uninstall program, or the uninstall program is terminated before it is able to remove all necessary entries from the ODM VPD.

If the uninstall program for a WebSphere product is not used to remove the product from the system, then the ODM VPD entries remain intact. If the uninstaller program is deleted, then there is no way to automatically remove those entries. This can potentially interfere with a new installation instance of a WebSphere product, especially if the product is installed into the same directory as the old, removed product.

In such a case, the installer will skip the installation of several (or all) WebSphere product software packages because the installer is under the false impression that the software packages are already present due to the entries which remain in the ODM VPD from the old, removed WebSphere product. This results in an "instantaneous installation" which reports a success message, when in fact the product is barely installed at all.

The installer does not see this as an error condition because the installer may experience legitimate scenarios with exactly the same characteristics. The installer will throw warnings logged in the installation log.txt file, though. The warning messages appear similar to this example. Note the highlighted key phrase:

Did not replace installed object (Server) with object (Server)

The presence of this message in the install log indicates that the installer detected a previous incarnation of a WebSphere software package in the ODM VPD. In most cases, this message indicates that the installation of the product is incomplete.

Note: The "Did not replace installed object" message can also come up when installing WebSphere products on other platforms. In such cases, consult the information center for the affected product, and search for articles concerning "manual uninstall".

This error scenario commonly occurs when an installation instance of WebSphere Application Server V5.0 or V5.1 is uninstalled using the uninstall program, but the instance of WebSphere Application Server Enterprise Edition V5.0 or WebSphere Business Integration Server Foundation V5.1 is not uninstalled using the separate uninstall program for that product. Even though the WebSphere Application Server product is properly uninstalled, the other extension product remains registered in the ODM VPD.


Problem 3: The ODM entries are not registered due to a specific issue
Clients running AIX with a 64-bit kernel in non-English locale with the environment variable setting EXTSHM=ON may encounter errors when installing WebSphere Application Server V5.1. The effect of these errors is that the product's ODM VPD entries are not registered. The product installation is otherwise completely functional.

This problem does not impact the application server runtime. However, other IBM products may use these ODM entries to verify that WebSphere Application Server V5.1 is present on a system. If the ODM entries are not present when such a product is installed, then that product may refuse to install. Note that the only product known to be affected by this issue is IBM DB2 Content Manager.


What is the CIE Registry?
The CIE Registry (also referred to as the "nifregistry") is a feature included in WebSphere Application Server V6.1 and V7.0. The CIE Registry is similar to the ODM VPD in its purpose. It keeps track of the locations where WebSphere Application Server V6.1 and V7.0 are installed on the system, and the installable features associated with those installed instances. The CIE Registry is separate and distinct from the ODM VPD, and the AIX operating system does not manage the CIE Registry.

The CIE Registry can contain references to installed instances of products, and the product uninstaller program will clean up the CIE Registry entries when the product is uninstalled. If the product uninstaller is not used and the product files are removed, or the product uninstaller is unable to clean up the CIE Registry, then the CIE Registry will need to be cleaned. The CIE Registry is cleaned using the installRegistryUtils utility, which is located on the product installation media. (For example, a copy of this utility is included in the WAS/installRegistryUtils subdirectory of the product installation image.) Please refer to the product InfoCenter and search "installRegistryUtils" for further details.


What solutions are available to resolve the problems discussed above?
When the ODM VPD becomes corrupt in the manner described above, the solution is to clean the remaining WebSphere product entries out of the ODM VPD.

If ODM VPD entries are lost due to an AIX migration (which will lose entries from the ODM VPD "vendor" table), there is no way to reconstruct the missing entries. In order to repair the ODM VPD information, it is necessary to remove the remaining WebSphere product entries present in the ODM for all WebSphere products. By removing the entries, the WebSphere Application Server installation program will not detect the WebSphere entries, and therefore it will not throw errors when attempting to analyze those entries.

If a WebSphere product was removed without running an uninstaller, or if the uninstaller fails due to corrupt ODM VPD information, then it is necessary to clean the ODM VPD entries associated with that product from the ODM. In general, it is safer to remove ODM VPD entries for all WebSphere products installed on the system. That way, the administrator can be assured that the WebSphere ODM VPD entries are completely clean. This ensures that the WebSphere product installer will not react negatively to the presence of corrupt ODM information.

The WebSphere support lab has produced a script which is capable of cleaning the ODM. This script is available in technote 1198862. For details pertaining to the process of identifying and cleaning up the ODM which more concisely explains the process, please refer to technote 1231062.