Chapter 22 |
Integrating Addon Products with Sun Management Center |
This chapter covers the following topics:
This document describes the procedures to be followed for proper Addon integration with Sun Management Center.
Below are definitions of some key terms used in this document:
By organizing Addons as described in this document, Sun Management Center installation and setup procedures can detect the Addon product and continue to install and setup Addon.
This section deals with the layout of Addon packages with respect to overall Sun Management Center Directory Organization.
Sun Management Center image is organized into three main levels:
The two main Sun Management Center products, the Production Environment (PE) and the Developer Environment (DE), reside in the product level. Addon products reside in the Addons sub-directory at the product level.
For backward compatibility, Sun Management Center 2.x Addon products can also be installed using Sun Management Center installation program.
All Sun Management Center 2.x Addon products should reside under the following directory:
Addons/SUNMC2.X/<OS>
The installation of Sun Management Center 2.x Addon products is driven by pkginfo file instead of the installation.info file.
Therefore, the layout of Addon products with respect to the overall Sun Management Center directory hierarchy can be represented as below:
+PE +DE -Addons (Product Level) -ADDON_PRODUCT1 +Common -Solaris_2.6 +locale -installation.info -installation.properties (Pack Level) -PACK1 (Package Level) -PACKAGE1 -pkginfo -pkgmap +reloc +PACKAGE2 +PACK2 +Solaris_7 +Solaris_8 +ADDON_PRODUCT2 -SUNMC2.X -Solaris_7 +locale +Desktop +PACKAGE1 -pkginfo -pkgmap -reloc +PACKAGE2 +WorkgroupServer +PACKAGE1 +PACKAGE2 +Solaris_8 +Docs +Patches
An Addon product, for example, can be structured in the following manner:
1. | When the Product Name is AdvancedMonitoring:
|
2. | When the OS specific package is Solaris 7:
|
Note that installation files are specific to each OS directory:
|
3. | When the Advanced Monitoring product consists of a Basic pack:
|
4. | When the Basic pack consists of SUNWesamn package:
|
5. | Each package contains pkginfo and pkgmap files:
|
This section deals with steps on how to package Addon products so that they are installed properly. There are two ways by which Addon products can interface with the installation program so that the installation program can detect them:
1. | Using the installation.info File |
2. | Packaging Sun Management Center 2.x Addon Products |
Supply a file which captures the installation information of Addon. This is the installation.info file. The installation.properties file is the corresponding internationalization file. For proper detection of an Addon product, these files have to be placed in their specific directory, as decribed in the previous section.
The format of these files is discussed below. The following table describes the variables that are part of tge pkginfo file for each package:
This file contains all the necessary information for installation. It refers to installation.properties for internationalized messages. All italicized words should be replaced with actual values. There should not be any whitespace before or after the equal sign (\Q=') . The file format and a brief description of each format follow:
<PRODUCT> PRODUCT_KEY= product key <PACK> PACK_KEY= pack key PACK_LICENSE= <key>:<question> PACK_SUBDIR= relative sub-directory that contains the pack PACK_CD= a CD number <COMPONENT> COMPONENT_KEY= Component Key ESSENTIAL= true | false LAYER= a comma-delimited list of layer keys DEPENDENCIES= a comma-delimited list of keys COMPONENT_SCRIPT= Script to be run before installing this component. PACKAGES= a list of comma-delimited sub-directories </COMPONENT> <COMPONENT> ...... </COMPONENT> </PACK> </PRODUCT>
Product Consists of group of Pack's and Pack consists of group of Components. (Currently, a product may have only one Pack). A \QComponent' is defined as a logical group of packages and forms a basic unit of installation. For example, the set of packages can be divided to belong to either agent component, console component or server component.
PRODUCT_KEY, PACK_KEY, and COMPONENT_KEY Used by the Sun Management Center installation program to display information on the Addon package being installed. They are purely used for information display purposes.
PACK_LICENCE Used to generate a question to obtain licensing information for a particular pack. The question is displayed. The key is specific to a pack. For example, Advanced Services pack will have have advanced_services as key.
PACK_SUBDIR Specifies the relative sub-directory that contains the pack relative to installation.info file.
PACK_CD If a pack resides on another CD, indicate the setting PACK_CD key with a positive number.
For Addons being shipped with Sun Management Center, the PACK_CD value must be 2. Third-party Addons should use value of 1. The installation program will prompt for the directory when the corresponding CD is mounted. Since ordering is important, all packs that reside on another CD should be placed on the bottom of the list. All essential packs should be kept on the first CD as much as possible.
ESSENTIAL Used to specify whether the user should be prompted before installing the component (TRUE/FALSE).
LAYER Specifies the layer that needs to be already installed, for this component to be installed. The valid values are LAYER.AGENT, LAYER.SERVER, and LAYER.CONSOLE.
DEPENDENCIES Specify the COMPONENT_KEY of the Component on which this Component depends. Components should be designed in a way that no circular dependencies are possible. If a component has no dependencies, leave an empty value.
All dependent components must be specified in the same file. The order in which each pack or component is set out is important. The installation program will follow that order in the installation sequence. Hence, the essential core pack and component (that has no dependencies) should be put on the top.
COMPONENT_SCRIPT If a Component requires a script to be executed before the corresponding packages are installed, the script (unix shell script) should be provided in the COMPONENT_SCRIPT field. The script should have a function named runComponentScript() that is the starting point of execution of the script. runComponentScript() should return 0 to indicate that the product should not be installed, 1 to indicate a successful execution of the script, and 2 to indicate that this component should not be installed. This script should be placed in corresponding \QPack' sub-directory.
PACKAGES Specifies the packages that belong to this component.
If a package name in the PACKAGES list requires internationalization, use the "${LOCALE_CODE}" string to indicate where the internationalized code should be placed. For example, SUNW${LOCALE_CODE}esh would be interpreted as SUNWzhesh if the locale code is "zh."
All OS-independent components should be included explicitly even though they reside in the Common directory. If the installation program cannot find a specified component in the specified subdirectory, it will try to find in the Common directory.
For windows installation, all the information should be filled in as well. The PACKAGES field will contain a list of directories under the pack directory that should be copied over to the target directory of a Windows machine. (The target directory is prompted for by the installation script). Everything in the specified directories will be copied over to target destination. Following is an example installation.info file used for the AdvancedMonitoring Addon product. The corresponding installation.properties file is supplied later on this section:
<PRODUCT> PRODUCT_KEY=PRODUCT.ADVANCEDMONITORING <PACK> PACK_KEY=PACK.BASIC PACK_LICENSE=advanced_monitoring:LICENSE.QUESTION PACK_SUBDIR=Basic PACK_CD=2 <COMPONENT> COMPONENT_KEY=COMPONENT.SERVER ESSENTIAL=true LAYER=LAYER.SERVER DEPENDENCIES= COMPONENT_SCRIPT= PACKAGES=SUNWessmn </COMPONENT> <COMPONENT> COMPONENT_KEY=COMPONENT.AGENT ESSENTIAL=true LAYER=LAYER.AGENT,LAYER.SERVER DEPENDENCIES= COMPONENT_SCRIPT= PACKAGES=SUNWesamn </COMPONENT> <COMPONENT> COMPONENT_KEY=COMPONENT.CONSOLE ESSENTIAL=true LAYER=LAYER.CONSOLE DEPENDENCIES= COMPONENT_SCRIPT= PACKAGES=SUNWescam </COMPONENT> </PACK> </PRODUCT>
This file follows the naming conventions of internationalization for Java. The format is: "installation_<LOCALE>.properties", where <LOCALE> is a specific locale (for example, zh, en_US, and such). The absence of _<LOCALE>, means that the installation.properties file is in English.
The file contains all the keys that map to their respective internationalized values and is used by the installation program in conjunction with the installation.info file. It contains only the key/value pairs for layers, packs, and components. There should not be any whitespace in the keys, neither before nor after the equal sign (=). Comments start with the pound character (#).
Following is the installation.properties file for installation.info file presented above:
PRODUCT.ADVANCEDMONITORING=Advanced System Monitoring # #Layers # LAYER.SERVER=Server Layer LAYER.AGENT=Agent Layer LAYER.CONSOLE=Console Layer # #Packs # PACK.BASIC=Advanced Monitoring Pack # #Components # COMPONENT.SERVER=Advanced Monitoring Server Component COMPONENT.AGENT=Advanced Monitoring Agent Component COMPONENT.CONSOLE=Advanced Monitoring Console Component # #License question # LICENSE.QUESTION=Please enter Advanced System Monitoring Product license or press return.
For backward compatibility, Addons which provide installation information through pkginfo variables (instead of installation.info) file will also be detected and processed. This method is appropriate for Sun Management Center 2.x Addon products.
These packages must be placed in special directory, SUNMC2.X (described in the previous section). For these packages, the following variables in the pkginfo file will be used to filter Addons as described in the table:
Variable
Semantics
CATEGORY If the term "SyMON" is not present in the variable, the package will not be presented for selection.
ES_ADDON_COMPONENT Specifies which component the package belongs to: agent , server, or console. These should be specified in lower case.
ES_ADDON_PLATFORM If the value of this variable is blank, then continues with further checking on whether or not to install the package. For more information, see "ES_ADDON_PLATFORM".
ES_ADDON_PACKAGE_DEPENDENCY A list of packages separated by a space between each package. If any of the required packages are not present on the system, this Addon will not be presented for selection.
ES_ADDON_FILE_DEPENDENCY A list of files, separated by spaces, which must exist on the host for this package to be installed.
The ES_ADDON_DIRECTORY_DEPENDENCY variable is provided for directories in which files are searched.
ES_ADDON_DIRECTORY_DEPENDENCY A list of directories, separated by spaces, in which the files mentioned in ES_ADDON_FILE_DEPENDENCY are searched.
ES_ADDON_VERSION Version required in x.x.x format. Forward compatibility is assumed here, that is, a pack for 2.1.1 is assumed to work for 3.0, 3.5, 4.0, and other versions.
ES_ADDON_CONFIRM TRUE to check the ES_ADDON_ FAMILY variable. For other values, there is no effect on installation.
ES_ADDON_FAMILY This variable is used only if ES_ADDON_CONFIRM=true. For more information, see "ES_ADDON_FAMILY".
If the value of this variable is blank, then check further to determine whether to install the package or not. If the value is not blank, it should be same as the current platform in order to proceed to further checking for installing this package.
Sun Management Center installation program uses the following procedure to obtain the string representing current platform:
1. | To obtain the value of DirName, enter the following command:
|
DirName is the string obtained from the above command, for example, if the result is: SunOS machne 5.7 Generic_106541-04 sun4u sparc SUNW,Ultra-60, then DirName would be SUNW,Ultra-60.
2. | Execute the following command:
|
A typical result of the above command would be:
System Configuration: Sun Microsystems sun4u Sun Ultra 60
UPA/PCI (2 X UltraSPARC-II 360MHz)In this case, the string representing the current platform is Sun Ultra 60
(not Sun Ultra 6).
3. | From the above result, enter the string representing the current platform as a value for ES_ADDON_PLATFORM. |
If there are more than one relevant platforms, seperate the entries by a colon. |
This variable is used only if ES_ADDON_CONFIRM=true.
The value of this variable is compared with the entry in <VAROPTDIR>/platform/ platform.prop file and the component is installed if they are same. If the file entry is different then the component is not installed. If the file does not exist, the installation program prompts the user to confirm the installation. Also if the file does not exist, the installation program prompts you to enter the string representing the family. Your entry is stored in platform.prop file and it is used in future comparisons with ES_ADDON_FAMILY.
For the location of the locale directory, refer to "Sun Management Center Directory Organization".
The locale directory contains locale information for script-based installation of this pack. Error messages and other messages are contained in the respective .mo files. For more information on .mo files and structure of locale directory, refer to man pages for msgfmt, gettext, textdomain and Chapter 19.
If an addon product requires setup after installation, it should have its own setup script with the name es-setup.sh in the sbin directory under its own top level directory.
<BASEDIR>/addons/<Addon_product>/sbin/es-setup.sh
where,
<BASEDIR> is the base location of the installed image. For example, the name of Addon is:
/opt/SUNWsymon/<Addon_product>
For example, if /opt/SUNWsymon is the base directory, then the es-setup script for Advanced Monitoring product should reside at:
/opt/SUNWsymon/addons/AdvancedMonitoring/sbin/es-setup.sh
es-inst -R option is used for installing Sun Management Center when the root filesystem of the target machine is mounted on the current machine. In this situation, the platform and the OS of the target machine may differ from their counterparts on the current machine. For Addon products to behave correctly in this situation, the addon scripts (such as, the component script) should make use of the target machine's attributes (platform and OS).
The following variables may be used in addon scripts to obtain this information.
For the target machine's platform:
RELOC_PLATFORM
For the target machine's OS:
OSVERS
Note that the PKG_INSTALL_ROOT variable maintained by the pkgadd program can be used to obtain the location at which the root filesystem has been mounted.
For example, the following could be a code fragment from the component script demonstrating the use of RELOC_PLATFORM to obtain the target platform information:
runComponentScript() { . . . . . if [ -z "$RELOC_PLATFORM" ]; then RELOC_PLATFORM=\Q/usr/bin/uname -i\Q fi /usr/bin/echo "$RELOC_PLATFORM" | /usr/bin/grep "Ultra-Enterprise-10000" > /dev/null 2>&1 if [ $? -eq 0 ]; then return 1 # platform correct, install component else return 2 # platform incorrect, do not install component fi }
The Addon packages that need to be installed on Windows platform should be laid out in the following manner:
<image>/Windows/Addons/<Addon-Product>/ |
For example:
<image> <Windows> <Addons> <WinAddon1> installation.info installation.properties
Note - The PACK_CD key in the installation.info file should be set to 2.
<image>/Addons/Windows/<Addon-Product>/<Pack>/ |
For example, for Addon product, WinAddon1, consisting of pack Pack1, and Pack1 consisting of directories Dir1 and Dir2, would have a directory organization as follows:
<Addons> <Windows> <WinAddon1> <Pack1> <Dir1> <Dir2>