Installable Unit Package Format Specification Version 1.0

W3C Member Submission 12 July 2004

This version:: http://www.w3.org/Submission/2004/SUBM-InstallableUnit-PF-20040712/
Latest version:: http://www.w3.org/Submission/InstallableUnit-PF/
Authors:: Heng Chu, IBM Software Strategy, hengchu@us.ibm.com (Editor); Christine Draper, IBM Autonomic Computing Architecture, cdraper@uk.ibm.com; Marcello Vitaletti, IBM Autonomic Computing Architecture, marcello.vitaletti@it.ibm.com; Randy George, IBM Tivoli Architecture, randyg@us.ibm.com; Julia McCarthy, IBM SWG Componentization Architecture, julia@us.ibm.com; Devin Poolman, Zero G Software, devin.poolman@zerog.com; Tim Miller, Zero G Software, tim.miller@ZeroG.com; Art Middlekauff, InstallShield Software Corp., artm@installshield.com; Carlos Montero-Luque, Novell, carlos@novell.com

This document is also available in these non-normative formats: PDF.

Copyright ©2004 InstallShield Software Corporation, International Business Machines, Inc., Novell, Inc., Zero G Software, Inc.. This document is available under the W3C Document License. See the W3C Intellectual Rights Notices and Disclaimers for additional information.

Abstract

The purpose of this specification is to describe a common installable unit package format used in the solution installation architecture. This package format is compatible with existing standard or de facto standard formats. The design pattern allows the solution installation architecture to encapsulate and use the existing install technologies for the various hosting environments. In particular, the artifacts can be standard or de facto standard packages on the target hosting environments. The actual install behavior is delegated to the install technologies for the hosting environments. The differences in various hosting environments (package format, install capabilities, etc.) are encapsulated in the deployment descriptor which provides a common and consistent view of the installable units and the install capabilities. This design allows deploying legacy products or products not created specifically for the solution installation architecture.

Status of this document

By publishing this document, W3C acknowledges that International Business Machines, Inc. and Novell, Inc. have made a formal submission to W3C for discussion. Publication of this document by W3C indicates no endorsement of its content by W3C, nor that W3C has, is, or will be allocating any resources to the issues addressed by it. This document is not the product of a chartered W3C group, but is published as potential input to the W3C Process. Publication of acknowledged Member Submissions at the W3C site is one of the benefits of W3C Membership. Please consult the requirements associated with Member Submissions of section 3.3 of the W3C Patent Policy. Please consult the complete list of acknowledged W3C Member Submissions.

1 Document Control

1.1 Contributing Authors

2 Introduction

2.1 Objective

An installable unit is a logical component that can be selected for installation. An installable unit package (or packaged installable unit) contains files to be installed, files that implement change management operations, and a set of manifest files which include a deployment descriptor that describes the install characteristics of the installable unit, and a media descriptor that describes the binding (or physical locations) of the files. This document describes installable unit package format.

The main objective of this document is to define a common installable unit package format consistent with the solution installation architecture. Packages in this format need to be installed in local or distributed environments. Different package types are defined for a single Zip file, fixed-sized removable media, and network location. Other formats may be accommodated in the future. Installable unit packages can be used with packages in existing (de facto or de jure) packaging standards.

2.2 Audience

This document is intended as a technical specification for people who require an in-depth understanding of the common installable unit package format. This will include developers of application or solution installable unit packages, developers of applications for deploying solution packages, and tooling for constructing install packages.

2.3 Scope

This document specifies the common installable unit package format and related design. In particular, the following areas will be covered in this document.

Relevant designs not covered in this document can be found in other ACAB documents.

2.4 Notational Convention

The key words “MUST,” “MUST NOT,” “REQUIRED,” “SHALL,” “SHALL NOT,” “SHOULD,” “SHOULD NOT,” “RECOMMENDED,” “MAY,” and “OPTIONAL” are to be interpreted as described in [RFC2119].

2.5 Background

Figure 1 depicts an important concept in the solution installation architecture. The install package for an installable unit (IU) consists of two major parts: a deployment descriptor (DD) that describes the contents, and one or more artifacts that can be installed. An IU – or specifically the artifact in the IU – will be installed on a hosting environment. Examples of hosting environments include hardware, operating systems, J2EE application servers, etc.

This document describes a common installable unit package format used in the solution installation architecture. This package format is compatible with existing standard or de facto standard formats. As shown in Figure 1, the design pattern allows the solution installation architecture to encapsulate and use the existing install technologies for the various hosting environments. In particular, the artifacts can be standard or de facto standard packages on the target hosting environments. The actual install behavior is delegated to the install technologies for the hosting environments. The differences in various hosting environments (package format, install capabilities, etc.) are encapsulated in the deployment descriptor which provides a common and consistent view of the installable units and the install capabilities. This design allows deploying legacy products or products not created specifically for the solution installation architecture.

The following sections describe the format of the installable unit packages to be deployed, the package contents, the relationship with the hosting environment package formats, and related tooling.

3 Installable Unit Package

An IU package can be in one of many physical formats. Although those formats are different, they are all based on a common logical layout. In this section, the IU package logical layout is described. Different types of files in an IU package and their relationships will be identified. The physical package format will be described in Section 5, “Package Types.”

3.1 Logical Layout

Figure 2 illustrates the logical view of an IU package. There are three groups of files in an IU package: the manifest files, required files, and optional files. The purposes and relationship of those files will be described in this section. Detailed description of those files, in particular the manifest files, will be provided in the following sections and other specifications.

3.1.1 Manifest Files

The manifest files provide standard ways for providing the IU package information. Standard manifest files enable the IU packages to be processed without human intervention (or, silently). This is in particular important to enable IU packages for autonomic or on-demand environments. Without the standard manifest files, each IU package has unique install information that requires human examination and sometimes modification before the IU package can be processed silently. This manual step may be unnecessary if standard manifest files are used to describe the IU packages.

1. Deployment descriptor: This is an XML document (in the IUDD [ACAB.SD0402] schema) that describes the install characteristics of the IU packages. This descriptor might reference other deployment descriptors ([ACAB.SD0402]) which could also be located in the same IU package.

The name of the deployment descriptor file must be “packagedIU.xml.” Please refer to ACAB specification ([ACAB.SD0402]) for details of the XML schemas.

2. Media descriptor: A deployment descriptor specifies what files are in the IU package, but not where they are. File paths are relative to logical sources. A media descriptor is an XML document that describes, among other things, the physical locations for logical sources of the files defined in the associated deployment descriptor. So an IU can be packaged in different physical formats with the same deployment descriptor, and may have unique media descriptors for each physical format.

A media descriptor is needed when file binding information is complicated. For example, if an IU package spans multiple fixed-sized removable media (such as CD-ROM), a media descriptor is needed to describe the physical file locations that involve the media identification and path within the media.

A media descriptor is optional. If it is not present, a single logical source is assumed for every file in the IU package, and a default physical location is used unless it is overridden by the installer.

The name of the media descriptor file must be “IUMedia.xml.” Section 4, “Media Descriptor”, has more details about the media descriptor and the related schema.

3. Digital signature: This is a binary file that identifies the IU package and the vendor who created it. Digital signature files are used to verify that the IU package has not been tampered with since it was created, and the signer (vendor) is really who it says it is. A digital signature is optional. If present, a digital signature should be co-located with the associated media descriptor.

Section 6, “Security”, has more details about the IU package security architecture.

The current design does not define a “main” manifest file that contains path information for all the other manifest files such as deployment descriptor and media descriptor. Thus, the manifest files for the IU are co-located and have fixed file names. This design allows references for one manifest file to lead to other manifest files and thus the complete package. A main manifest file might be introduced in future versions so the co-location restriction can be removed.

3.1.2 Files Defined in the Deployment Descriptor

Most files in the IU packages are defined in the deployment descriptor (packagedIU.xml) using the <file> elements. The following information, among others, is defined for each file in the deployment descriptor (see [ACAB.SD0402] for more details), and will be referenced in this specification.

· Identifier (the “id” attribute): This is the key used to reference the associated file from the media descriptor (see Section 4, “Media Descriptor”) or elsewhere in the deployment descriptor via the <fileIdRef> attribute or element (see [ACAB.SD0402]).

· File pathname (the “pathname” child element): This is the file pathname in the IU package, and may be overwritten in the media descriptor (see Section 4.3, “File Binding Information”). The physical location of the file depends on the physical package format (see Section 5, “Package Types”), and is defined based on the file binding rules (see Section 4.4, “File Binding Rules”).

· File size (the “length” child element): This is the file size that may be used to verify the physical file (see Section 6, “Security”).

· File digital signature (the “checksum” child element): This is the file signature based on one of several message digest algorithms (CRC32, MD2, MD5, and SHA). This information may be used to verify the physical file (see Section 6, “Security”).

3.1.3 Required Files

There are two types of non-manifest files that will be required during the installation process. These files must be specified in the deployment descriptor, and are mapped to physical locations via the media descriptor.

1. Install customization code: Those are the files used to implement custom install logic. They are specified in artifact descriptors (see [ACAB.SD0402]). Such custom code can be in external files (such as native OS commands) or packaged as part of the IU packages. In the latter case, the custom code is packaged just like other files and the binding information is specified in the media descriptor.

In the case of the multiple fixed-sized removable media packages (such as CD-ROMs), the custom code of the IUs (including the aggregated ones) should be put on the first media so it does not require access to other media to execute the custom code. Unnecessary media swapping should be avoided. In the IUDD spec [ACAB.SD0402], files containing custom code are not specified explicitly (using special XML elements). However, since files containing custom code are referenced in XML elements for custom commands, those files can be identified and moved to the first removable media by examining how they are referenced in the deployment descriptor.

2. Files to be laid down during installation: Also called “payload,” those are the files to be copied to the target host during installation. Examples include the Java class files, shared libraries, executables, DLL, etc.

Binding information for those files is specified in the media descriptor (see Section 4.3, “File Binding Information”).

Since symbolic links are not supported consistently in all physical formats and the behaviors vary on different platforms, symbolic link support must not be assumed for IU packages. For example, ZIP files can not contain symbolic links, UNIX system symbolic links behave differently from the shortcuts on Windows. As a result, symbolic links can not be maintained in IU packages. Symbolic links should be created during installation using, for example, the <addLink> element (see [ACAB.SD0402]).

3.1.4 Optional Files

There are non-manifest files in an IU packages that are specified in neither the deployment descriptor nor the media descriptor. These files may be used by a particular installer technology during installation, or may provide useful information (such as “readme” files) that helps users install the package. They are usually included in IU packages to make the packages self-contained (for example, an executable JAR package file for Java-based install technologies) so the packages can be installed without additional prerequisites. This is also an important usability feature that allows vendor-specific functions to be included in the IU packages.

The only requirement for those files is that the installation of the IU package must not depend on the presence of those optional files. Namely, if the optional files are removed from the IU package and the resulting IU package is still valid and can still be installed according to the information specified in the deployment descriptor.

For example, for a Java-based install technology, the optional files could include the install engine, bundled JVMs (to be extracted and installed first on the target in order to execute the install engine), etc. In this case, the IU package is self-contained and the packaged install engine can be invoked to install the IU package. Those optional files can be safely removed from the IU package since the package without the optional files can still be installed using an external install engine that knows how to process IU packages.

Another example is that an install vendor could provide additional files containing help or information that provides guidance in aggregating the IU. This information may be used by the specific vendor installation IDE to improve usability.

3.2 Aggregation

An installable unit, or IU, package (the aggregating IU) may aggregate other IU packages (the aggregated IUs). The aggregation relationship is defined in the deployment descriptor of the aggregating IU by specifying linkage to the deployment descriptor of the aggregated IUs. This is defined in the IU deployment descriptor specification and related XML schema (see [ACAB.SD0402]).

There may be multiple levels of aggregation. However, examples in this section use a single level of aggregation.

Aggregated IUs may be included “in-line” in the aggregating IU, or referenced externally from the aggregating IU. Based on the aggregation relationship, aggregated IU packages may exist in the aggregating IU package or in an external package for the aggregated IU. Thus, when an IU aggregates other IUs, there may be multiple IU packages (including the one for the aggregating IU) required to be processed in order to deploy the aggregating IU.

Figure 3 illustrates an example of in-line and external IU aggregation. In-line and external aggregation relationships will be described in detail in the following sections.

3.2.1 In-line Aggregation

When an IU is aggregated in-line, its package contents are included as part of the aggregating IU package. Such aggregation should be conducted by a package creation tool (see Section 10, “Tooling”).

The aggregated IU deployment descriptor contents are refactored and included in the aggregating IU deployment descriptor. In the IUDD schema, the <installableUnit> element defines in-line aggregation relationship using Smallest Installable Unit (SIU), Configuration Unit (CU), Container Installable Unit (CIU), or Solution Module (SM), each of which specifies in-line aggregated IU.

For example, in Figure 3, IU1 deployment descriptor is included as part of IU3 deployment descriptor.

The process of refactoring aggregated IU deployment descriptors for in-line aggregation is dependent on the aggregation relationships as defined in the aggregating IU deployment descriptor (see [ACAB.SD0402]), and is outside of the scope of this specification.

In-line aggregation is used when the aggregated IU contents are available at the time of creating the package of aggregating IU. The aggregated IU files are specified in the aggregating IU (via the <file> element), and they are packaged in the aggregating IU package. Those files can be bound or relocated, like other aggregating IU files, through the aggregating IU media descriptor.

For example, in Figure 3, IU1 files are part of IU3 package and can be bound by the IU3 media descriptor.

3.2.2 External Aggregation

When an IU is aggregated through external references, its package exists separately in its entirety. The aggregation relationship is defined via the use of elements of the type iudd:ReferencedIU that references the deployment descriptor of the aggregated IUs. Such elements include the <containedIU>, <containedCIU>, and <referencedIU> elements (see [ACAB.SD0402]).

The aggregated IU package is a complete IU package that has manifest and packaged files. Since all manifest files are co-located, through the reference to the deployment descriptor, the media descriptor and other package files of the aggregated IU can be located.

The external reference is reference to a <file > element that can be bound or remapped through the media descriptor of the aggregating IU. This is illustrated in Figure 4.

The location and package type of the aggregated IU are flexible. Through the use of the media descriptor (see Section 4, “Media Descriptor”), the deployment descriptor location can be a local path, a folder in a ZIP file, a folder on a removable media, or any location in the network. This flexibility allows the aggregated IU package to be a single ZIP file, files on removable media, or files in local or network file systems (see Section 5, “Package Types”).

For example, in Figure 3, IU4 is aggregated by IU3 through external reference. IU4 media descriptor and associated packaged files can be located via the location of the deployment descriptor. The IU4 package can be a ZIP file, a set of files on fixed-sized removable media, or a set of files in local or network file systems.

An externally aggregated IU package may be included as part of the aggregating IU package. Through the reference to its deployment descriptor, the aggregated IU package can be identified and manipulated (such as extraction). For example, in Figure 3, IU4 package can be a ZIP file inside the IU3 ZIP package. IU4 ZIP package can be identified (through the reference in the deployment descriptor) and extracted if necessary.

There is no special requirement on how the pathnames (or file structure) for the referenced IU deployment descriptors should be arranged in the referencing IU. However, in the case of fixed-sized removable media, all (root or referenced) IU deployment descriptors should be located in specific folders on the first media, regardless of what is defined in the root IU deployment descriptor. This should be done through the use of media descriptor (see Section 4, “Media Descriptor”).

4 Media Descriptor

The deployment descriptor specifies what files are in an IU package, but not where they are. Information about the file physical location (the binding information) is kept in a separate, optional media descriptor. This allows the same deployment descriptor to be used for different physical packages. Each physical IU package may have a media descriptor providing file binding information that describes specifically where each file is physically located. Only the files specified in a deployment descriptor can be bound in the associated media descriptor. If a file needs to be bound and accessed via the media descriptor, it must be specified in the IU deployment descriptor.

A media descriptor is optional. If it is not present, all files specified in the deployment descriptor have paths relative to the location of the deployment descriptor in the package. An installer can choose to override this default value via, for example, an install parameter.

There is at most one media descriptor per IU package to provide binding information for files defined in the deployment descriptor. If an IU package is aggregated in another IU package (see Section 3.2, “Aggregation”), the referenced deployment descriptor may have an optional associated media descriptor for the aggregated IU.

1. The corresponding deployment descriptor path name relative to the media descriptor.

2. A default logical source may be defined and apply to files that are not explicitly bound in this media descriptor

4. Optionally the media descriptor can override the file path for selected files. This feature can be used to map to common files shared by several IUs.

Note the path overridden is the location of the file within the package (see Section 5, “Package Types”). If the file path in the deployment descriptor is used for other purposes (for example, for intended install location), the original value in the deployment descriptor can still be used.

4.1 Overview and UML Representation

The UML class diagram in Figure 5 identifies the media descriptor structure and the relationship to the IU deployment descriptor.

The root element in a media descriptor is <binding> of type BindingInfo which consists of the following information:

1. Element deploymentDescriptor
The associated IU deployment descriptor. See Section 4.2.

2. Element fileSource
The physical location, or the binding information, of the files specified in the IU deployment descriptor. A file defined in the IU deployment descriptor has at most one fileSource element in the associated media descriptor. See Section 4.3.

3. Element defaultLogicalSource
This is the default physical location for files not explicitly bound via the fileSource element. This element is optional. See Section 4.4.

The relationship between the deployment descriptor and the media descriptor is illustrated in Figure 7. Details will be given in the remainder of this section to show how a media descriptor provides binding information for the associated deployment descriptor.

Note that the file size and digest information are specified in the deployment descriptor and cannot be overridden in the associated media descriptor. This ensures the file contents remain the same as they were when the deployment descriptor was created. These two pieces of information are used in signing and verifying IU packages (see Section 6, “Security”). Again, the media descriptor can only specify where the files are, not what they are.

Through the use of media descriptors, different files – as defined in the same or different deployment descriptors – can be mapped to the same physical file. This provides flexibility for reducing the IU package size by sharing files.

4.2 Deployment Descriptor Information

A media descriptor specifies the associated deployment descriptor information via the following elements:

· Element location [type=base:RelativePath]
This is the deployment descriptor physical path. The path is relative to the media descriptor and links the media descriptor to the associated deployment descriptor. The current design requires deployment descriptor and media descriptor be located in the same folder and have fixed names, thus this path name is fixed and has ‘packagedIU.xml’ as the value.

In the future this pathname can be used to locate the deployment descriptor if manifest files do not have fixed names or are located at different locations.

· Element digest [type=base:CheckSum]
This is the optional message digest for the entire deployment descriptor. The optional digest value is used for security purposes (see Section 6, “Security”).

Below is the XML schema fragment for the deployment descriptor information in a media descriptor.

4.3 File Binding Information

Files specified in a deployment descriptor have paths relative to logical sources. A logical source, depending on the package types, can be mapped to any physical location. This allows the files to be packaged in a way that meets the user scenarios and needs. The mapping of logical sources is defined in the media descriptor.

If a media descriptor is not present, the default value of the logical source for all files defined in the deployment descriptor is the folder of the deployment descriptor.

· Element fileIdRef [type=NCName]
This is the value of the attribute ID for the corresponding file element in the IU deployment descriptor (see Figure 5 and Figure 7). For any fileIdRef, there must be a corresponding file element with a matching ID value in the associated deployment descriptor. For any file in the deployment descriptor, there should be at most one corresponding entry in the media descriptor.

Below is the XML schema fragment for the fileIdRef element.

· Element location [anonymous type]
For the specific file, this element defines the physical location of the logical source, and optionally overrides the file path. The physical location of the specific file is the logical source plus the file path.

A media descriptor can only specify the physical locations for the logical sources, or override the file path. It can not modify the file sizes and digest values.

· Element physicalLocation [type=media:LogicalSource]
This is the physical location of a file logical source. The physical location for a logical source can be a local path, a path in a separate ZIP file, a path on a fixed-sized removable media (such as CD-ROM), or any network location.

A physical location is of the type the media:LogicalSource which is described in Section 4.3.1.

· Element pathname [type=base:RelativePath]
This optional element defines a new file path relative to the physical logical source. If the file path is specified in the media descriptor, the one in the deployment descriptor will be ignored.

Below is the XML schema fragment for the pathname element.

4.3.1 Logical Source

· Element local [type=base:RelativePath]
This is a path relative to the media descriptor folder (which could be in a ZIP file, file system, network location, or fixed-sized removable media). This is typically used when the IU package is a ZIP file or located in a network location. For example, if the media descriptor is in the /META-INF/ folder of a ZIP file, and a file is located in the /FILES/ folder, the logical source should be a local path ‘../FILES.’

Below is the XML schema fragment for the local element.

· Element removableMedia [anonymous type]
This element specifies a location in a fixed-sized removable media such as a CD-ROM. Such location is identified through the volume identifier and a path in the volume.

Fixed-sized removable media (for example, CD-ROM and DVD) is a common package format for installation. Files could be located on such media. Due to its fixed-sized nature, there could be multiple volumes for large IU packages. For files located on such media, a volume identifier is given and a path relative to the specified volume root is specified.

The removal media information is specified by

· Element path [type=base:RelativePath]
The file location on the media. This is always a relative path and is relative to the root of the media.

· Attribute type [type=media:RemovalMediaType]
This specifies the type of the media where the ZIP is located. Currently the supported media types (as defined in the “RemovableMediaType” type) are: CD-ROM, DVD, Diskette, and others.

· Attribute volumeID [type=xs:string]
This is the volume identifier for the specific media where the ZIP file is located. This value is used to identify the media. The installer processing this information will know how to locate the physical media based on the volume ID. The logic could be vendor or installer specific, and is outside the scope of this specification.

· Element ZipFile [anonymous type]
This specifies a folder in a ZIP file. ZIP [ZIP] is a commonly used compression format but the access to ZIP file is different from the access to regular file systems – the process requires decompression of the contents. So locations of this type need to be specified so installers can properly access the files.

This is typically used in aggregation (see Section 3.2, “Aggregation”) when the file is a deployment descriptor in another IU ZIP package. For example, if the file path is ‘packagedIU.xml’ to indicate an aggregated IU deployment descriptor (through external aggregation) and the aggregated IU package is a ZIP file, this file should be mapped to ‘/META-INF/packagedIU.xml’ in the aggregated IU ZIP package.

ZIP files can be located in a network location (including local, relative locations) or in a fixed-sized removable media such as a CD-ROM. In either case, a path within the ZIP file is specified by

· Element path [type=base:RelativePath]
The file path within the ZIP file. This is always a relative path and is relative to the root of the ZIP file.

· Element networkSource [type=xs:anyURI]
This specifies a location on the network. This value can be absolute or relative. A relative value can be used to specify a local ZIP file.

· Element ZipPath [type=base:RelativePath]
This specifies the location of the ZIP file on the media. This is always a relative path and is relative to the root of the media.

Note the difference between this value and the above path element which specifies the file path within the ZIP file.

Heng Chu	IBM Software Strategy	hengchu@us.ibm.com
Christine Draper	IBM Autonomic Computing Architecture	cdraper@uk.ibm.com
Marcello Vitaletti	IBM Autonomic Computing Architecture	marcello.vitaletti@it.ibm.com
Randy George	IBM Tivoli Architecture	randyg@us.ibm.com
Julia McCarthy	IBM SWG Componentization Architecture	julia@us.ibm.com
Devin Poolman	Zero G Software	devin.poolman@zerog.com
Tim Miller	Zero G Software	tim.miller@ZeroG.com
Art Middlekauff	InstallShield Software Corp.	artm@installshield.com
Carlos Montero-Luque	Novell	carlos@novell.com