This document describes the methods used by a person to assemble an install bundle using the Image Packaging System (also known as pkg (5)) multi-OS platform tools.

Overview

A software distribution in the context of pkg(5) consists of:

1. a set of software packages in one or more pkg(5) package repositories
2. one or more initial install bundles that are used to deliver a subset of the repositories

Role of Pre-installed Images
The install bundles can exist in several forms, however, the end result of using an install bundle is to realize a set of pre-installed packages on the target system. In the pkg(5) system, a set of pre-installed packages is housed in an "image". Thus, we use the term "pre-installed image" to refer to the common means of pre-installing a set of content in an image and then wrapping the image in an install bundle. The image includes both the installed package content and the pkg(5) metadata describing the installed packages and the sources (repositories) of future add-on packages and updates.

Forms of Install Bundles
One form of an install bundle is a simple archive, such as a zip archive, of the pre-installed packages. Another form is a self-extracting executable file (e.g. .exe, .sh, .dmg, etc.) containing an initial install program that simply expands an archive of the pre-installed packages into a user-specified location and performs other initial installation duties such as license agreement, product registration and perhaps initial configuration.

Overall Install Bundle Assembly Steps
An install bundle assembler is the person who puts together the initial download and install bundles. Assembling pkg(5)-based these bundles entails:

• Setting up the pkg(5) tools
• Selecting the type of and content for the initial image
• Ensuring access to the necessary feeder package repositories
• Constructing the install bundles including the optional creation of an install program
• Including licenses and other information
• Publishing the install bundles

Populating packages repositories with the appropriate packages may not be the responsibility of the person assembling the install bundles. The install bundle assembler may simply be creating and maintaining scripts that draw content from existing package repositories. Since package repositories associated with a distribution typically contain content that is now owned by the project delivering and maintaining a distribution, establishing the supporting package repositories is typically handled outside of the install bundle assembly process and is a prerequisite to process of assembling install bundles.

Universal and Platform-specific Pre-installed Images
Pre-installed images can be constructed in one of two basic forms:

• Universal
• Platform-specific

Universal Pre-installed Images: A universal image is contained within a single install bundle that can be used on any platform. It will typically contain very little, if any, platform-specific software. The software in the image provides the ability to obtain the platform-specific software that is needed.

Platform-specific Pre-installed Images: An OS platform-specific image, on the other hand, contains the software that is needed for a specific OS platform, so a separate install bundle is generated for each platform. Other variations on the initial image result from the install bundle assembler making choices about what software to put into the initial image. For example, the Update Tool GUI may or may not be included in the install bundle. The detailed process for constructing the install bundle is described below.

Procedure for Install Bundle Assembly

The following flowchart provides an overview of the procedure for assembling an install bundle when using the pkg(5) multi-OS platform tools:

Generally, the flow for the install bundle assembler works as follows:

1. An install bundle assembly server is prepared by downloading and unzipping the platform-specific pkg(5) install bundle which contains the pkg(5) tools.

2. An starter repository file, e.g., repo-windows-i386.zip for Windows, is downloaded and unzipped, and the pkg.depotd server is started and pointed at the downloaded repository. The content of this file forms the initial content for the repository. This repository contains pkg(5) packages containing the pkg(5) tools.

3. The pkgsend command is used to publish the software product packages into the repository on the install bundle assembly server. Now the repository contains the pkg(5) mulit-OS platform tools and the product software. This step is optional depending on whether repositories already exist.

4. A pre-installed product image is initialized by running the pkg image-create command. This step is not necessary when the pkg(5) install bundle is used as the starting point for a platform-specific pre-installed image.

5. The product image is initially populated or primed by adding the desired packages from the repository by running pkg install commands.

6. For a universal image, the pkg(5) Java package, pkg-java, is pre-installed in the image. This package contains a pkg-bootstrap.jar file and bootstub wrapper scripts for the updatetool and pkg commands that are copied to bin/ of the image. The pkg-bootstrap.jar can be used by an initial install program can use to dynamically complete the installation of the Update Tool GUI and pkg(5) client tools. When an initial install program is not used, a user can simply execute the bin/pkg or bin/updatetool scripts to trigger dynamic installation of the pkg(5) client tools.

7. For a platform-specific image in which you want to pre-install the pkg(5) client tools, the image may be augmented with the Update Tool GUI package, updatetool.

8. Finalize the image:

• Set the image title and description that will be displayed in the Update Tool GUI and desktop notifier.
• Set the pointers to the sources (repositories) containing all of the packages for the distribution.
• Remove the download cache in .org.opensolaris,pkg/download to reduce the size of the download.
• Remove the UUID settings in the .org.opensolaris,pkg/cfg_cache file to force an automatic reset of the UUID. Optionally set the value of the send-uuid property.
• For a platform independent image, remove the variant.arch setting from the .org.opensolaris,pkg/cfg_cache file so that it will be determined when the pkg(5) software runs.

9. The product-repo.zip and product.zip files are created by zipping up the repository and the pre-installed image, respectively. The product.zip file may be replaced by an installable file generated using an installation framework. The install bundle and repository files is moved to the distribution server.

10. The distribution server is prepared by installing the pkg(5) tools as in step 1 and a web server. The pkg.depotd server is started on the distribution server using the product-repo.zip file for its content, and the product.zip file is made available through the web server. (Not shown in diagram)

11. For a universal image, additional repositories for other supported OS platforms are created by unzipping the various repo-''platform''.zip files on the distribution server and running the copypkgs.py script to copy the portable packages from the initial repository to the additional repositories. Additional pkg.depotd servers are then started for the additional repositories. (Not shown in diagram)

There are several variations of this procedure based on the questions in the flowchart.

Image Type?

If the image type is universal, then the pkg(5) tools and the minimized python cannot be included in the pre-installed image, because those packages are platform specific. Therefore, the pkg(5) tools are extracted to a TOOLS_HOME area that is not part of the image. The remainder of the procedure uses the tools from the TOOLS_HOME area.

Embed pkg(5) Tools in Image?

For a platform-specific image, it may still be desirable to not put the pkg(5) tools in the pre-installed image to minimize initial download size. If the tools are not going to be in the image, then the tools must be installed into a TOOLS_HOME area. The pkg(5) client and its native dependencies cost about 3-4 MB in size compressed.

If pkg(5) is embedded in the image, the pkg(5) platform-specific zip file can be used as the initial content for the image. So with this choice, there is no need to create a new image using the pkg image-create command.

pkg(5) Client Available?

Some operating system distributions, such as OpenSolaris distributions available from OpenSolaris.com, already contain the pkg(5) client. When using one of these distributions, then you can simply use the pkg(5) tools contained in the OS. The pkg(5) tools are needed on both the distro assembly server and the distribution server, so this question applies to both servers.

Embed Update Tool GUI?

For a platform-specific image, one option is to include the Update Tool GUI with the image so that the user does not need to download it as a post-installation step. This adds about 8-12 MB depending to the install bundle depending on the OS platform.

Make Update Tool GUI available?

For a universal image, the platform-specific parts of the Update Tool GUI must be downloaded after the image is activated before a user can use the tool. These steps are for making it easy for the user to do this.

Repositories and OS Platform Considerations

Current pkg(5) repository deployment conventions entail establishing a repository instance for each supported client OS platform. This approach is mainly driven by the fact that, although your product's content may be comprised of all cross-platform code, the pkg(5) toolkit contains some platform-specific binaries. Those platform-specific binaries and their packages are hosted in distinct instances of pkg(5) repositories. A copy of your multi-platform packages is represented in each of the platform-specific repositories.

From an install bundle assembly standpoint, you don't need to worry about the fact that there are multiple back end repositories serving up your packages the the pkg(5) toolkit packages. Typically, an Apache HTTP server tier is deployed in front of the pkg(5) repository instances. This web tier can dynamically inspect requests from your installed images and route the requests to the appropriate repository based on that inspection.

You will need to specify the appropriate platform-independent repository URLs in your pre-installed image. The example below provides details on setting the repository URLs.

Detailed Example of Assembling an Install Bundle

This example shows how to assemble a simple install bundle for a product called Money Manager consisting of one platform-independent package, gold that is made available as part of the pre-installed universal image and one platform-independent package, silver that is made available within the repository as an available add-on. Each package contains only one simple text file, README.txt that is placed into the gold and silver directories. The overall distribution is to be supported on all of the available platforms.

The example assumes that install bundle assembly is being on a Solaris/x86 system which already contains a web server with a document root at $HOME/webserver/docroot. Install bundle assembly and distribution use the same server, so the steps that are involved in moving the data from one server to the other are skipped. The name of the server is assumed to be pkg.example.com. The pkg(5) multi-OS platform toolkit files are assumed to have been downloaded to the $HOME/UC2 directory. The source for the README.txt is in $HOME/src. The example starts from a user's home directory.

Step 1: Prepare the Server by Installing the pkg(5) Tools

$ cd $HOME
$ mkdir distro
$ cd distro
$ (mkdir ips; cd ips; unzip -q $HOME/UC2/pkg-toolkit-sunos-i386.zip)

Step 2: Start the Initial Repository Used for Publishing Packages

$ mkdir mm-repo-windows-i386
$ (cd mm-repo-windows-i386; unzip -q $HOME/UC2/repo-windows-i386.zip)
$ nohup ips/pkg/bin/pkg.depotd -d `pwd`/mm-repo-windows-i386 -p 10000 --rebuild >mm-repo-windows-i386.log 2>&1 &

The --rebuild option is recommended to deal with file modification time anomalies caused by unzipping a repository.

Step 3: Publish the Packages for the Distribution

$ export PATH=$HOME/ips/pkg/bin:$PATH
$ export PKG_REPO=http://localhost:10000/
$ eval `pkgsend open gold@1.0`
$ pkgsend add set name="description" value="Gold"
$ pkgsend add file $HOME/src/README.txt mode=0644 owner=nobody group=staff path=gold/README.txt
$ pkgsend close

$ eval `pkgsend open silver@1.0`
$ pkgsend add set name="description" value="Silver"
$ pkgsend add file $HOME/src/README.txt mode=0644 owner=nobody group=staff path=silver/README.txt
$ pkgsend close

Step 4: Create the Pre-installed Image

$ pkg image-create -U -a sun.com=http://localhost:10000/ mm

Set a Title and Description in the Image

This is an optional step, but supplying a title and description as part of your image will enhance the manner in which the image is displayed within client side tooling. For example, the Update Tool GUI will list the image's title in the list of installation images rather than displaying only the filesystem path of the image.

You are encouraged to at least set the title property in your pre-installed images.

pkg set-property title "GlassFish V3 Tech Preview 2"
pkg set-property description "GlassFish v3 Technology Preview 2 (TP2) is a milestone release of the GlassFish v3 Application Server. TP2 gives you an early look at GlassFish v3. It is not a full, feature-complete application server and is not suitable for production deployments. It is suitable for experimentation and exploration. TP2 contains a subset of all features in the GlassFish v3 Application Server and of the technologies in the Java EE 5 platform, which means it doesn't contain everything! It contains just the core v3 modules, Java EE web tier technologies, the Java Persistence API, and non-Java programming language containers."

Try to limit the length of the title to 30 characters or less such that the value fits within the default area provide by client side GUI tooling.

Step 5: Add the Pre-installed Software to the Image

$ pkg -R `pwd`/mm install gold
$ rm -rf mm/.org.opensolaris,pkg/download

The last command removes the cache of downloaded files from the image to reduce the size of the download file.

NOTE: We should pre-install pkg-java in this step

Step 6: Prepare the Image for Platform-specific Initialization

Set the Repository URLs

You have two options when modifying the cfg_cache file to point to the appropriate repositories:

1. Using Platform-independent Repository URLs
2. Using Platform-specific Repository URLs

Most install bundles will use platform-independent repository URLs and depend on a front-end web server to dynamically determine the client's OS and processor architecture and the correct package repository based on inspecting the User-Agent HTTP header. In these cases, you can simply set the origin URL using pkg set-authority.

$ pkg -R mm set-authority -O http://pkg.example.com/ sun.com

If you are not using a front-end web server, then edit the cfg_cache file to include the URLs for the various platform-specific repositories:

$ cp mm/.org.opensolaris,pkg/cfg_cache /tmp/cfg_cache
$ awk '/ssl_key = None/ { print "origin-for-windows-i386 = http://pkg.example.com:10000"
        print "origin-for-sunos-i386 = http://pkg.example.com:10001"
        print "origin-for-sunos-sparc = http://pkg.example.com:10002"
        print "origin-for-linux-i386 = http://pkg.example.com:10003"
        print "origin-for-darwin-universal = http://pkg.example.com:10004"
        print "origin-for-aix-powerpc = http://pkg.example.com:10005"
        }
        { print }' /tmp/cfg_cache > mm/.org.opensolaris,pkg/cfg_cache

Unset the Image UUIDs

If you are distributing a platform-specific image without an installer, it is desirable to remove the UUIDs from the cfg_cache file so that they will be reset automatically when the image is used. To do this, just run the cfg_cache file through grep:

$ cp mm/.org.opensolaris,pkg/cfg_cache /tmp/cfg_cache
$ grep -v "uuid =" /tmp/cfg_cache > mm/.org.opensolaris,pkg/cfg_cache

Also, you may want to set the send-uuid value for the image to true:

$ pkg -R mm set-property send-uuid True

Remove the variant.arch Setting

If you are distributing a platform-independent image or if you are building a paltform-specific image on a system with a different type of architecture than the target system, the variant.arch value must be determined on the target system. To cause this to happen, remove the variant.arch setting from the cfg_cache file by running the cfg_cache file through grep:

$ cp mm/.org.opensolaris,pkg/cfg_cache /tmp/cfg_cache
$ grep -v "variant.arch" /tmp/cfg_cache > mm/.org.opensolaris,pkg/cfg_cache

Step 7: Augment the Image with Startup Scripts

If you are providing a universal (platform neutral) pre-installed image that requires pkg-bootstrap to be run to bootstrap the pkg(5) client, then you have the option of including some stub scripts for pkg and updatetool that will automatically run pkg-bootstrap when they are run. This results in the pkg(5) mulit-OS platform toolkit being installed, at which point pkg and updatetool become functional. To do this:

$ mkdir mm/bin
$ cp $HOME/UC2/pkg-bootstub.sh  mm/bin/pkg
$ cp $HOME/UC2/pkg-bootstub.sh  mm/bin/updatetool
$ chmod 777 mm/bin/pkg mm/bin/updatetool
$ cp $HOME/UC2/pkg-bootstub.bat mm/bin/pkg.bat
$ cp $HOME/UC2/pkg-bootstub.bat mm/bin/updatetool.bat

If you have placed pkg-bootstrap.jar some place other than in mm/pkg/lib/pkg-bootstrap.jar you will need to modify the scripts and change the BOOTSTRAPJAR variable to point to your location.

NOTE: This section needs to be updated to reflect that since pkg-java will already be pre-installed:

• wrapper scripts should be copied from their installed location from within the image
• there's no need to mention anything about the location of pkg-bootstrap.jar since the wrapper scripts work relative to bin/.

The stub scripts display a message notifying the user that 1) the software will automatically check for updates (only when the updatetool is being installed) and 2) when the tool interacts with package repositories anonymous usage data will be sent to the repository server. If your distribution has its own web page describing anonymous usage information that is captured, you should replace the default URL with your own.

If you choose to install Update Tool, your system will be automatically
configured to periodically check for software updates. If you would like
to configure the tool to not check for updates, you can override the
default behavior via the tool's Preferences facility.

When this tool interacts with package repositories, some system information
such as your system's IP address and operating system type and version
is sent to the repository server. For more information please see:

http://wiki.updatecenter.java.net/Wiki.jsp?page=UsageMetricsUC2

So what does this do for you? When a user unzips your install image and runs bin/pkg or bin/updatetool they will be told that the software for those commands is not installed, and given the option to install it. If they choose to install it, the script runs pkg-bootstrap to install the IPS client tooling and, optionally, the Update Tool GUI. After that the user can run pkg or updatetool and they are good to go.

If you intend on having your install program run pkg-bootstrap at install time then these scripts are not necessary.

Step 8: Create the Install Bundle and Publish to Web Server

$ (cd mm; zip -qr ../mm.zip . )
$ cp mm.zip $HOME/webserver/docroot

Step 9: Set up the Distribution Server

''This step is skipped because the distribution server and the distro assembly server are the same for this example. The initial repository is already running on port 10000.''

Step 10: Setup up repository servers for other platforms

$ i=10001
$ for p in sunos-i386 sunos-sparc linux-i386 darwin-universal
do
  mkdir mm-repo-$p
  (cd mm-repo-$p; unzip -q $HOME/UC2/repo-$p.zip)
  python $HOME/UC2/copypkgs.py -s mm-repo-windows-i386 -d mm-repo-$p gold silver
  nohup ips/pkg/bin/pkg.depotd -d `pwd`/mm-repo-$p -p $i --rebuild >mm-repo-$p.log 2>&1 &
  i=`expr $i + 1`
done

At this point, the mm.zip file can be downloaded from the pkg.example.com web server, and pkg(5) repository servers are running on ports 10000-10004 to respond to requests for installation or updates to the packages contained in the servers.

Initial Installation Integration

Typically projects include an initial installation programs in their install bundles that provide users with friendly means of initializing the initial installation. Features of an initial install program typically include:

• Self-extracting archive support in the form of download able .exe, .sh and .dmg files. Users just double click or run the self-extracting executable to start the initial installation process.
• License acceptance
• Install location selection
• Optional initial confguration
• Optional product registration
• Optional immediate check for available updates

Even though projects can pre-install much of the initial content at the factory, these features are often still desirable to offer during initial installation. To install the pre-installed image, the installation program need only expand the archive containing the image to the location specified by the user.

Resetting the Installation Image UUIDs

When you created your pre-installed image at the factory, an installation image UUID was created for each publisher in the image. You may want to ensure that these UUIDs are reset on a user's system. If you don't intend to leverage the unique UUID for back end reporting purposes, you can ignore this section.

Universal Pre-installed Images

If you are using a universal image along with the pkg(5) Java Bootstrap facility, then the publisher UUID will be reset automatically when the bootstrap is executed. The Java Bootstrap facility also has an input value for determining whether anonymous information should be sent to the server. If this is set, then the send-uuid property will be set to true within the image.

Platform-specific Pre-installed Images

If you are using a platform-specific image in which you've pre-installed the pkg(5) Python client package pkg, then you should either have your initial installation program should reset the UUIDs upon installation on a user's system or during image assembly, remove the UUIDs that were assigned. If the latter is done, new image UUIDs will be assigned the first time the pkg(5) API is used on the system. Note that your installation program may be as simple as a short script that does nothing other than reset the UUIDs using the pkg set-authority --reset-uuid command.

You might also want to consider setting the default value for the send-uuid property for the image. The default value is false, meaning that the UUID values will not be sent to the server. Setting this to true means that the user would be opting in by default for gathering anonymous information for packaging operations. To set this value, use pkg set-property send-uuid True

Product Registration

If your product entails optional registration of the installation instance, you can obtain the unique installation image ID from the installed image and use it in your product registration process. For example, an initial installation program may extract the installation ID for later product registration purposes. Doing so may enable your organization to correlate repository interactions with known registered instances of your product.

Sun Product Note To enable correlation between registered product installations and repository activity, client applications can obtain the installation image ID and include it in one of the elements of a Service Tag that is used during the product registration process. Depending on your product's needs, you may choose to include the installation image ID in one of the following Service Tag elements: instance_urn product_defined_instance_id source Refer to the Sun internal Service Tags for Developers Guide for more details. The Sun Inventory service enables customers to discover product installations, register them with their Sun Online Account, and organize and manage it. Applications such as initial installation programs can obtain the installation image ID by inspecting the output of the following command: % pkg authority myproject.org Authority: myproject.org Origin URL: http://pkg.myproject.org/ SSL Key: None SSL Cert: None UUID: 50f9b18e-3c62-4479-bf0c-83e4b715d64e Catalog Updated: Mon Aug 18 09:41:33 2008 Where myproject.org is the name of the repository (known as the "authority" on the pkg CLI) that was specified when you created the pre-installed image at the factory.