GlassFish - World's first Java EE 7 Application Server


relchiricle

Solaris package response file support in openInstaller

This page details the design for adding support for installation of packages with interactive request scripts, using non-interactive response files, in openInstaller 1.x.

Response file overview

See Solaris Application Packaging Developer's Guide: Creating Installation Scripts for information on how request scripts are written by package maintainers.

Packages that contain interactive request scripts are normally interactive when they are installed (using pkgadd). The job of the request script is to prompt the user for questions, and write out their answers to $1 (e.g. echo SETTING=$answer >> $1). This interaction is bad for installers because it causes installation to hang (as there is no "console" to answer the questions during install). Therefore, a package administrator can provide a response file which is used instead of running the request script. The response file represents the answers that would have been written out by the request script. The package is installed in a non-interactive mode (pkgadd -n) passing the response file using the -r response_file option.

Response file contents

The contents of a response file, as outlined above, is a set of NAME=VALUE pairs which represent environment variables that are available during the installation of a package. For example, a package's postinstall script may refer to the value of one or more of the variables. The underlying packaging tools use the response file to fill out the system environment during package installation.

The values found in a response file are specific to the package (or product in which the package resides). The values found typically represent user-supplied configuration information or other dynamic variables that cannot be hard-coded at the time the package is built. Normally, the values are determined through the
package's interactive request script, but a response file can be used instead. However, the values are still typically determined by an interactive
higher-level installer, such as openInstaller. Therefore, there needs to be a way to transfer user-supplied values to the underlying packages via the response file.

Relationship to openInstaller configuration

openInstaller's configuration architecture is such that each individual product to be installed by openInstaller can describe their configuration in the form of a configuration schema (also called an OOR file, as it is based on the openOffice Registry format). This file describes the configuration parameters that a product
can use to configure itself during installation, upgrade, or unconfiguration during uninstall. Here is a sample snippet from a configuration schema:

<group oor:name="Administration">
        <prop oor:name="WS_ADMIN_HOST" oor:type="xs:string" oor:nillable="false">
           <value if:eval=":[target:sys.hostName]">localhost</value>
        </prop>
        <prop oor:name="WS_CONFIG_NAME" oor:type="xs:string" oor:nillable="false">
           <value if:eval=":[target:sys.hostName]">localhost</value>
        </prop>
   </group>
 </component>

This defines that this particular product has two configuration parameters, WS_ADMIN_HOST, and WS_CONFIG_NAME, and both are strings,
grouped into the Administration group.

The response files that products use in most cases need to know one or more of the configuration values that the configuration schema (OOR) file describes. Therefore, a 1-1 mapping in most cases would work. That is, each configuration parameter in the configuration schema file should also be put into the response file when a package from that product is installed. This is exactly what this design document details.

Design of openInstaller feature

The following points provide a summary of the proposed behavior of openInstaller:

  • By default, all packages that are part of a product which has defined a configuration schema (OOR) file will be passed a response file.
  • The response file, by default, will contain NAME=VALUE pairs for each and every configuration parameter defined in the configuration schema (OOR) file. The VALUE of each pair will be the current value as computed by the openInstaller engine (the same value that is passed to the product's init-config configurator).
  • For products that are not configurable (those that do not have a configuration schema which a name which matches the product name) will have no changes. They will not be passed a response file.

This will cover 80-90% of the use cases for response files. However, there are two slightly more complex scenarios for which we provide additional support for. The design behavior is:

  • Names of parameters used in response files may be different than names used in the configuration schema. In this case, the user must specify the mapping in the component's dependency descriptor file (where the package names are declared).
  • Values of parameters may be dynamically specified instead of being taken from the current value of the configuration parameter.

These two additional behaviors are explained below:

1. Names of parameters used in response files may be different than names used in the configuration schema.

In this scenario, the openInstaller installer developer has chosen to use different names in their configuration schema file vs. the names that are expected by the packages themselves. For example, a package may be expecting PORTAL_HOSTNAME=some hostname but the install developer has chosen to use PS_HOSTNAME in their configuration schema because this value is expected by the product's configurator itself or the name was chosen for some other unknown reason.

In this case, a way to map one name to another is necessary. This can be specified in the dependency descriptor as is done in the following example:

<Realization>
        <OS>
          ...
        </OS>
        <InstallableUnit>SUNWwbsvr7</InstallableUnit>
          ...
        <ParameterMap real_name="OOR_NAME1" mapped_name="RESPONSE_NAME1"/>
        <ParameterMap real_name="OOR_NAME2" mapped_name="RESPONSE_NAME2"/>
          ...
      </Realization>

In this example, the OOR configuration schema name is OOR_NAME1, but the name expected in the response file is RESPONSE_NAME1. When the package is
2000
installed, a response file will be generated with all of the name/value pairs as defined in the configuration schema file, but any occurance of a parameter with the name OOR_NAME1 will be substituted with a parameter by the name of RESPONSE_NAME1. The value however will be the same. If no variable by the name OOR_NAME1 is present in the configuraiton schema file, then no substitution will be made and the contents of the response file will be the same as if this XML Parameter element were deleted.

2. Values of parameters may be dynamically specified

In other cases, the value of a particular response file parameter passed to pkgadd is the combination of two or more other configuration parameters. In this case, a dynamic calculation of the value must be made. There are actually two ways to accomplish this:

  • 2a. The first way is already possible in openInstaller. You simply define a new parameter in your configuration schema file which has a dynamic default value, using existing substitution syntax. This new parameter's value is computed and the value is passed in the response file along with all other parameters. Here is an example of a dynamic configuration parameter:
<prop oor:name="SERVER_NAME" oor:type="xs:string">
 <value if:eval=":[component:accessmgr:Configuration:AM_SERVER_NAME]">localhost</value>
 <info>
   <desc xml:lang="en-US">Name of the host on which the Access Manager server has been or will be deployed</desc>
 </info>
</prop>

This defines a new parameter named SERVER_NAME which will take on the value of another configuration parameter, accessmgr.Configuration.AM_SERVER_NAME. This substitution syntax can be used any number of times in a single expression, and can refer to other component variables, OI engine options, machine data (e.g. ip address, hostname), and a host of other dynamic info. For more detail on the possible values, see the openInstaller Configuration Architecture Specification in the openInstaller Documentation Depot

  • 2b. The second way, which is defined here, is to define a new parameter using the <Parameter> element in the dependency descriptor. This defines a new parameter which is not present in the configuration schema (OOR) file, but is used during pkgadd to pass a new response file parameter. Here is an example:
<Realization>
        <OS>
          ...
        </OS>
        <InstallableUnit>SUNWwbsvr7</InstallableUnit>
          ...
        <Parameter name="NEW_PARAM1">:[component:accessmgr:conf:AM_SERVER_NAME]&:[component:accessmgr:conf:AM_SERVER_PORT]</Parameter>
        <Parameter name="NEW_PARAM2">:[target:sys.hostName]&:[component:accessmgr:conf:AM_SERVER_PORT]</Parameter>
          ...
      </Realization>

In this example, a two new parameters named NEW_PARAM1 and NEW_PARAM2 are defined for passing to the package during pkgadd. The value passed is the dynamically calculated value using the specified component substitution values. In this example, you also see a different substitution parameter :[target:sys.hostName]. This is substituted with the running machine's hostname. At pkgadd-time, a response file is generated with all of the parameters specified in the configuraiton schema file, and in addition, these two new parameters are included. For example, the values for these two new parameters may appear as:

NEW_PARAM1=amserver.sfbay.sun.com&8080
NEW_PARAM2=installsvr.sfbay.sun.com&8080

This option provides a way for an install author to specify additional parameters that aren't present in the configuration schema (OOR) file.

Specifying Parameter/ParameterMap elements at the CompositeUnit level

In the above examples, the <Parameter> and <ParameterMap> elements were specified under the <Realization> element. This meant that the parameters only applied to the individual realization. When other realizations are installed (e.g. on other platforms), these parameters would not be passed to the package being installed. In some cases, it is desirable to pass the same values to multiple realizations (e.g. on Solaris/sparc and Solaris/x86). To do this, one can specify the parameters as part of a higher-level element (the <CompositeUnit>). An example is shown below:

<Payload>
    <CompositeUnit>
      <Name>core</Name>
      <Parameters>
        <Parameter name="TestProductACompositeLevelParameter">TestProductACompositeLevelParameterValue</Parameter>
      </Parameters>
      <Realization>
        ...
      </Realization>
    </CompositeUnit>
  </Payload>

In this example, a new parameter called TestProductACompositeLevelParameter is defined at the CompositeUnit level. This means that the parameter applies to all realizations of this CompositeUnit. Similarly, <ParameterMap> can be used in this way.

Precedence rules

In the above example, a Parameter was declared at the CompositeUnit level. In addition, parameters can be specified at the Realization level. When two parameters conflict, the parameter defined at the Realization level takes precedence. This allows developers to specify a generic set of parameters and values at the CompositeUnit level, and then override their values (or their name mappings) . For example:

<Payload>
    <CompositeUnit>
      <Name>core</Name>
      <Parameters>
        <Parameter name="TestProductASetting">TestProductASettingValue</Parameter>
        <ParameterMap real_name="TestProductAOtherSetting" mapped_name="MappedName"/>
      </Parameters>
      <Realization>
        <OS>
          ...
        </OS>
        <InstallableUnit>SUNWfoo</InstallableUnit>
        <Parameters>
          <Parameter name="TestProductASetting">TestProductASomeOtherValue</Parameter>
          <Parameter name="TestProductAOtherSetting">TestProductASomeValue</Parameter>
        </Parameters>
      </Realization>
    </CompositeUnit>
  </Payload>

In this example, the developer has declared a setting using the same name TestProductASetting. When SUNWfoo is installed, the value of this setting will be taken from the Realization declaration, so the value will be TestProductASomeOtherValue.

You will also notice at the CompositeUnit level, a declaration of a map for the TestProductAOtherSetting. Then, at the Realization, a parameter is defined using the same name. In this case, the Parameter at the Realization level takes precedence, and the mapping defined at the CompositeUnit level is not applied (it is essentially invisible, masked by the declaration at the Realization level).