# Chapter 22

| # Integrating Addon Products with Sun Management Center

> This chapter covers the following topics:

- Sun Management Center Directory Organization--page 496
- Packaging of Addon--page 499
- Locale Information--page 506
- Addon Setup Interface--page 506
- es-inst -R Option--page 507
- Packaging for Windows--page 508

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

- A package is a software package that contains images for installation.
- A component 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 one of ro the following: the Agent component, the Console component, or the Server component.
- A pack is a group of components.
- A product is a group of packs. For example, there are two main products, the Production Environment (PE) product and the Developer Environment (DE) product. This term is also used to define a group of packs that belong to a third party vendor.
- An Addon product is a product with one or more packs possibly from a third party. These products may not necessarily be bundled with the Sun Management Center; therefore, the corresponding packs may not reside in the same location as the Sun Management Center packs.

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

## Sun Management Center Directory Organization

> 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 product level
- the pack level
- the package level

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

- Each product level has an OS-independent sub-directory, called `Common`, for common code as well as OS-dependent sub-directories as required.
- Each of these sub-directories in turn have pack-level sub-directories.
- Each pack level sub-directory has package-level sub-directories.
- In addition to pack directories, each OS directory contains the \Qlocale' sub-directory and the following files: `installation.info` and `installation.properties`.
  - `installation.info` is the configuration file that drives the installation of Addon product
  - `installation.properties` is the corresponding internationalization file.

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

### Layout of Addon Products

> 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

### Example Layout

> An Addon product, for example, can be structured in the following manner:

| 1. | When the Product Name is `AdvancedMonitoring`:
    <image>/Addons/AdvancedMonitoring/

| 2. | When the OS specific package is Solaris 7:
    <image>/Addons/AdvancedMonitoring/Solaris_7/

|  | Note that installation files are specific to each OS directory:
    <image>/Addons/AdvancedMonitoring/Solaris_7/installation.info
    <image>/Addons/AdvancedMonitoring/Solaris_7/installation.properties

| 3. | When the Advanced Monitoring product consists of a Basic pack:
    <image>/Addons/AdvancedMonitoring/Solaris_7/Basic

| 4. | When the Basic pack consists of `SUNWesamn` package:
    <image>/Addons/AdvancedMonitoring/Solaris_7/Basic/SUNWesamn

| 5. | Each package contains `pkginfo` and `pkgmap` files:
    <image>/Addons/AdvancedMonitoring/Solaris_7/Basic/SUNWesamn/pkginfo
    <image>/Addons/AdvancedMonitoring/Solaris_7/Basic/SUNWesamn/pkgmap

## Packaging of Addon

> 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

### Using the `installation.info` File

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

Variable | Description
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. The terms, agent, server, and console, should be specified in lower case.

#### Format of the `installation.info` File

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

### The `installation.properties` File

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

### Packaging Sun Management Center 2.x Addon Products

> 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".

#### ES_ADDON_PLATFORM

> 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:
    uname -a

> 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:
    /usr/platform/<DirName>/sbin/prtdiag | head -1

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

#### ES_ADDON_FAMILY

> 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`.

## Locale Information

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

## Addon Setup Interface

> 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

> `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
>     }

## Packaging for Windows

> The Addon packages that need to be installed on Windows platform should be laid out in the following manner:

- The `installation.info` and `installation.properties` files should be placed in:

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

- The actual packages and directories should be placed in:

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

Copyright © 2000 Sun Microsystems, Inc. All Rights Reserved.