Home Index Changes Prefs Log in »

Update Center Install Time Configuration Functional Specification

Version 0.6

1.0 Project Description

1.1 Introduction

During a software installation session some amount of software configuration is typically performed. This document describes a general architecture for how "install time" configuration will be performed in UC2.0, and includes best practices as well as some specific mechanisms for performing configuration.

Even though this document discusses configuration performed during an installation session, it is important to make a distinction between software installation and software configuration. The primary focus of software installation is to get the correct version of the bits installed in the correct locations, and to ensure the software is self consistent and has its dependencies resolved. Installation must be simple and robust.

Configuration is modifying that software so that it runs and behaves as desired. All too often the act of configuring software is fragile and error prone. Most "installation" issues are actually configuration issues. Therefore it is important that we protect the fundamental operation of installing software from its more tempermental cousin.

This leads us to the following basic principles:

Basic Tenets

  • The architecture and experiences of installing software should be kept separate from configuring software.
  • Configuration and customization tasks required of the user during an install session should be kept to a minimum.
  • The installer is not the primary place for users to perform configuration and customization tasks.
  • Projects should provide users with robust postinstallation tools for performing configuration and customization tasks (requirements concerning such tools are outside the scope of this document).
  • Users must be able to reconfigure products without re-installing the product.

Generally speaking the configuration performed during an installation session should be just enough to get a product up and running in a basic deployment. If the configuration tasks required to get a basic deployment operational is non-trivial, then the install session should do just enough to enable postinstallation tools to be used to complete configuration operations.

1.2 When To Configure: Overview

We look at five stages at which point configuration can be performed:

StageDescriptionExamples
0At the factory, before software is shippedGood defaults, preconfigured images
1During package installation.Package scripts, IPS actions.
2After package installation, triggered by the installer/updaterJava ES installer configurators.
3After the install session performed by the user.Running product administrative commands or post install config wizards.
4After the install automatically performed by the software.Updating configuration values the first time software executes.

This specification will provide some guidance concerning stages 0, 1, 3 and 4 and define a specific mechanism for stage 2.

1.3 Deliverables

The scope of this document includes the following deliverables:

Updates to the the SWI Configuration Best Practices and Policies document.
Design and interfaces for the "Stage 2" post install configuration mechanism.
Implementations of the "Stage 2" post install configuration mechanism in the UC 2.0 installer and update clients

1.4 Relevant UC 2.0 Requirements

The following UC 2.0 Requirements are covered by this document:

PM-8.1Clear separation between installation and configuration: The packaging and update mechanism architecture must support a clear and distinct separation between installation and configuration without intermingling the two.
PM-8.2Well defined API to trigger configuration logic (configurators) after installation
PM-8.3Supports silent configurators as well as those that require interaction with the user

2 Technical Description

2.1 Architecture

2.1.1 When To Configure: Details

As mentioned in the Project Description there are five points at when software configuration can occur during (or following) an installation session.

Stage 0: At The Factory

The best time to perform configuration is at the factory, before software reaches the user. There are a couple approaches to consider:

Good DefaultsSoftware should ship with a reasonable default configuration so that most settings do not need to be altered by the user.
Pre-configured ImagesAn alternative to the traditional installer download is the pre-configured install image. In this case the product has been installed and configured at the factory into an image to reflect a particular deployment scenario. The image is shipped as a binary distribution and can be installed by the user. An image can be as simple as an IPS user image that is zipped up, or as sophisticated as a VMWare image. Details concerning best practices and techniques for creating pre-configured images are outside the scope of this document.

Stage 1: During Package Installation

Many packaging systems provide hooks for executing package specific scripts at various points of a packages lifecycle (preinstall, postinstall, preremove, etc). These mechanisms are flexible allowing the scripts to do pretty much anything. While this is quite powerful, it has the negative trait of promoting the intermingling of configuration and installation. History has proven that package maintainers often do not get packaging scripts correct which leads to various installation and patching issues.

The problem of poorly behaved package scripts has gotten so bad in Solaris, that the new OpenSolaris packaging system, IPS, has eliminated free-form package scripts entirely. Instead they have been replaced by well defined (and reversable) package actions. The existing set of actions is fairly limited -- covering the basics of installation plus smf(5) manifest registration and device driver installation. While it is possible to add new actions, the likelyhood is that this will rarely happen.

Since Update Center 2.0 uses IPS there will be little to no configuration performed during package installation. Projects are free to use IPS actions, but at this time it is not possible to introduce custom package scripts.

Note: IPS is designing a generic post-installation action that could be used to execute scripts after package installation when the system is in a known state. As we learn more about the details of this mechanism we will update this specification with guidelines on its use. We hope to use this mechanism to perform simple configuration tasks like performing desktop integration tasks.

Stage 2: After Package Installation: Installer Configurators

When software is installed using an installer, there is an opportunity to perform software configuration during the install session after the packages are installed (in this document the term "installer" should also be understood to include an update client that can install and update software). In Update Center 2.0 this will be done using product "configurators". These configurators have great latitude in what configuration operations they can perform since the user is sitting in front of an interactive UI that can request input, provide feedback, display status/errors, etc.

But even in this case restraint must be shown. As mentioned in the introduction, the installer is not the primary place to perform configuration. It should only ask the user enough to get the software operational. Therefore product configurators should constrain themselves to a couple of configuration panels at most.

Details on the Update Center 2.0 installer configurators is given in section 3.

Stage 3: After Installation Session, Performed by User

Once an installation session is complete all options are available to the user. Product teams have a lot of latitude here, although they should always strive to keep their configuration scenarios as simple and robust as possible.

Any operations that were inappropriate for stages 1 or 2 may be accomplished here. Highly sophisticated or complex products may choose to do little to no configuration during the installation session, instead requiring the user to run a configuration tool after installation. Product teams should ensure that post installation configuration tools are as simple, robust, and friendly as possible.

Stage 4: After Installation Session, Performed by Software

It is possible that some configuration tasks can be deferred until the first time the software is executed by the user. Typically these would be non-interactive operations that the software performs after inspecting the system in some fashion (creating a persistent store, determining a thread pool size, etc).

2.1.2 Uninstall

Operations that were performed during the stages listed above must be reversable, and typically un-done upon software uninstallation. Note that there may be exceptions to this rule, or cases where the user is given some options. For example, if I uninstall AppServer I would want it's smf(5) entries removed, but I may not want the default domain removed that was created during the installation session.

The SWI Configuration Policy and Best Practices document gives further guidance in this area.

2.1.3 Updates

In Update Center 2.0, "Updates" are considered a very specific kind of release as described by the Sun Middleware Component Release Taxonomy . Generally speaking when an update is applied no configuration operations should need to be performed. And in the rare case where operations are performed they should be transparent and compatible with the version of the software prior to the update.

Note that an "update" is not the same as an "upgrade". Updates are typically for sustaining purposes and are applied in-place. Upgrades contain a much greater degree of change and are often performed via side-by-side installations with data/config migration.

2.2 Interfaces

These interfaces are described in more detail in section 3.

Interface Name Proposed Stability Classification Reference
Package attributes:
org.updatetool,postinstall
org.updatetool,postupdate
org.updatetool,preremove
Committed Section 3.1.1
Warning: These attribute names may change when the IPS attribute name guidelines are finalized. If that occurs then the implementation must support the older version of the names for compatibility.
Configurator exit codes Committed Section 3.1.2
Location
var/install/log/config/<pkgname>-<TIMESTAMP>.log
Not-an-interface Section 3.1.2

2.4 Compatibility and Interoperability

2.4.1 IPS

This project is fully compatible with IPS. The mechanism described in section 3 is designed using standard IPS interfaces.

2.4.2 GlassFish AddOn Configurators

Update Center 1.0 defines a set of interfaces for installing and configuring addons. Specifically:

It is not a goal of UC 2.0 to be completely compatible with these interfaces. But, for the most part, these interfaces will still be applicable in UC 2.0. One notable exception may be com.sun.appserv.addons.Installer , since its capabilities will be subsumed by the IPS packaging system.

Note that the mechanism described in section 3 can be used to trigger AddOn installation (uninstallation) into GlassFish. For example one could set the org.updatetool,postinstall attribute to install-addon glassfish3/lib/addon/myaddon.jar.

This section needs to be expanded

2.4.3 OpenInstaller

There is no effort made to make this project compatible or interoperate with the OpenInstaller configuration mechanism, although it does not interfere with nor prohibit projects from using such a mechanism. In fact projects are encouraged to leverage the configuration frameworks provided by installers to improve their install experience, as long as that aligns with the basic tenets of this document.

3 Component Architecture

The following sections describe a simple configuration mechanism for use at installation time (so called "Stage 2" in section 2.1.1). Configurators should adhere to those guidelines especially the principle that configuration at install time should be kept to a minimum. Install configurators should be simple, and only perform very basic, necessary configuration tasks.

This mechanism is not an IPS mechanism. It should not be confused with package scripts. This mechanism is layered on top of the packaging system and is invoked by a higher level installer or updater (or person).

Said another way, if a user installs packages directly via IPS, this configuration mechanism is not invoked. However it is designed such that the user can invoke it directly after package installation.

In the following sections the term "installer" is used broadly to mean a traditional installer, an uninstaller, or an update client (performing both updates to an install image and adding new content).

3.1 Description

3.1.1 Configurator Declaration

A package may have zero to three configurators associated with it. A configurator is simply an executable that is delivered by a package and is invoked by the installer at the appropriate time.

A configurator must implement some specific interfaces as described in the Configurator Interface section below.

The three possible configurators are:

postinstallInvoked in order of pkg installation after all packages are installed. Used when no previous version of the package is installed.
postupdateInvoked in order of pkg installation after all packages are installed. Used when a previous version of the package is already installed.
preremoveInvoked in order of pkg removal before any pkgs are removed

It is important to note that the postinstall configurators are invoked only after all packages in the install session are installed. For example if the package glassfish2 is installed, and that also results in the ant and mq packages being installed first, then the order would be:

package ant installed
package mq installed
package glassfish installed
ant postinstall called
mq postinstall called
glassfish postinstall called

The same is true for postupdate (when packages are updated) and preremove (when packages are removed).

A package declares its configurators by setting an IPS package attribute that specifies the configurator to run. These attributes are:

AttributeValue
org.updatetool,postinstallPath to postinstall configurator command to run
org.updatetool,postupdatePath to postupdate configurator command to run
org.updatetool,preremovePath to preremove configurator configurator to run

Warning: These attribute names may change when the IPS attribute name guidelines are finalized

The path to the configurator command is relative to the root of the installation image $INSTALL_HOME. For example: glassfish2/bin/asconfigure.

Configurators are delivered by the package that has the corresponding configurator attribute set.

Issue 1: How do we handle multi-platform packages? Where we need to specify something like glassfish2/bin/asconfigure.sh and glassfish2/bin/asconfigure.bat? Some options:

  1. have the org.updatetool,postinstall attribute specified twice on the package, tagged with the com.sun.application.os attribute and filtered (as described in the Cross-Platform packaging proposal). This would require that the IPS team fixes bug 322 . Or
  2. Support specifying the command without any suffix. If that command is not found then add common suffixes specific to the platform (.bat for Windows, .sh for Unix, etc) and look for the command again.

The decision is to go with option 2 for now. If the command specified is not found by updatetool then the following suffixes are added to the command until a match occurs:

OS Suffixes
Unix .sh, .ksh, .csh
Windows .bat, .exe

This means you can set the postinstall attribute to a command like glassfish2/bin/asconfigure, and ship asconfigure.sh on Unix and asconfigure.bat on Windows.

Issue 2: Do we need to propogate XDisplay information?

Issue 3: The install order of packages may not be well defined in IPS. Instead the order that actions are invoked are well defined. If this is the case then configurators would be invoked in the order that they are installed (the order that their file action is invoked).

3.1.2 Configurator Interface

Exit Codes

0All is well
non-zeroAn error occurred

When a non-zero exit code is returned by a configurator, the installer should inform the user that the configurator failed and give them the option to view the configurator's log file. The installer will then continue to invoke subsequent configurators.

The same is true on uninstallation. Note that a non-zero return code from a preremove script will NOT terminate uninstallation of the package.

Location

Configurator executables should be placed in their product's component area under $INSTALL_HOME. For example:

$INSTALL_HOME/glassfish2/lib/asconfig

Exact location is up to the product.

Log File

Configurators should generate a log file containing all relevant messages. The suggested location for log files is:

$INSTALL_HOME/var/install/log/config/<pkgname>-<TIMSTAMP>.log

where TIMESTAMP is based on ISO8601 UTC. Specifically:

yyyymmddThhmmssZ

For example: var/install/log/config/glassfish2-20071107T162738Z.log

Log file format is left to the discretion of the configurator, but it should be:

  • Simple
  • Easily human readable
  • Each record preceded by a date/time stamp

Determining Context

The configurator is not passed any other context from the UC update tool. This is intentional. Configurators should be designed such that they are easy for a human to run without relying on the user to provide additional information.

A configurator should use the techniques described in Dependency Wiring for Unbundled Software to locate and resolve dependencies inside an $INSTALL_HOME. In particular it can use techniques described in that document to determine the value of $INSTALL_HOME.

3.1.3 Update

When a package is already installed on the system, and a newer version of that packages is installed it is considered an "update". Note it is not considered an "upgrade" (upgrades are more substantial operations and are typically performed by doing side-by-side installs and migrating data).

As defined by the Middleware Release Taxonomy an update occurs in place and should not require any configuration changes. And if any configuration or data changes do take place they must be completely compatible and reversable. The changes must also take place without requiring any user interaction.

In the rare case that an update does require some postprocessing to occur the postupdate attribute may be used to specify an update configurator. While update configurators support the same interfaces as install configurators, in practice their use is much more limited. In particular they should never present a UI and should not require any user interaction.

3.1.4 Uninstall

If a component has a postinstall script specified, then it should typically have a matching preremove script to perform any cleanup that should be done before the package is removed. More detailed guidance on this is given in the SWI Configuration Policy and Best Practices document.

3.1.5 Failure and Recovery

In general failure of configuration operations should not impact installation. As stated previously the postinstall/postupdate configurators are not executed until all packages are installed, and an error in a preremove script will not interrupt package removal.

3.1.6 Security

In order to protect sensitive configuration information all files created by configurators should be owned by the user executing the configurator and readable and writeable only by the owner.

4 References

Sun Middleware Release Taxonomy http://sac.sfbay.sun.com/WSARC/2006/516/proposal/current.html
Multi-platform Package Proposal http://wiki.updatecenter.java.net/Wiki.jsp?page=MultiPlatformPkg
SWI Configuration Policy and Best Practices http://jesarch.sfbay.sun.com/attach/ConfigurationPolicies%2Fconfiguration-best-practices-policies2.pdf
Sun Brand Guidelines http://xdesign.sfbay.sun.com/brand/touchpoints/SunBrandGuidelines_v_1.0.pdf
GlassFish Addon http://wiki.java.net/bin/view/Projects/AddonInterfaces
UC 2.0 Requirements http://wiki.updatecenter.java.net/Wiki.jsp?page=Requirements2
IPS Tags and Attributes Guidelines http://src.opensolaris.org/source/xref/pkg/gate/doc/tags-and-attributes.txt

5 History

Version AuthorDateModifications
0.6joe.dipol@sun.com 26 Sept 2008 Updated interface stability classifications
0.5joe.dipol@sun.com 18 Sept 2008 Changed attribute names: com.sun.application to org.updatetool
0.4joe.dipol@sun.com 11 June 2008 Added Notes concerning upcoming IPS attribute name guidelines. Updated Stage 1 IPS post-install Note
0.3joe.dipol@sun.com 20 May 2008 Add Issue 3. Perform minor edits.
0.2joe.dipol@sun.com 31 March 2008 Removed a number of interfaces including command line arguments and saving of configurator state. Performed other minor edits.
« Home Attachments Info Index Changes
This page (revision-23) was last changed on 26-Sep-08 11:25 AM, -0700 by DiPol