Installation Framework
Part 2: Implementation Specification

Version 0.9
09/04/97
Phong Vo


This is the specification for the Installation Framework and individual server installation programs, and how they fit together.


 

References

Software Packaging

Each software package (Product, Module, Update, or Patch) must consist of the following:

Source Repository

The source repository for the servers, whether it's on a CD-ROM, local directory or a network repository, will look like the following:

<root>
   |
   + -- suitespot.pi
   |
   + -- /base
   |        |
   |        +-- base.pi
   |            base.archive
   |
   + -- /admin
   |         |
   |         +-- admin.pi       -- Admin Product Info
   |             admin.archive  -- Admin server archive
   |             ns-config      -- Admin pre-installation program
   |
   + -- /<server nickname>
             |
             +-- server.pi
                 server.archive
                 server.pre-install

                 server-module-1.pi
                 server-module-1.archive
                 server-module-1.pre-install
                 ...
                 server-module-n.pi
                 server-module-n.archive
                 server-module-n.pre-install
                 ...
                 Other packages/modules/updates/patches

   +
   |
   + -- /<other products>
 

Package Information File

Package Information File format

General

Server Information File (suitespot.pi)

#
# Sample Server Package Information File
#
Name=Sample Server Suite
Vendor=Example Inc.
Description=
Type=Composite
Version=7.1

# Package contents
# List all Products here

[admin]
Name=Administration Server
Version=7.1

[https]
Name=Enterprise Server
Version=6.2

[slapd]
Name=Directory Server
Version=7.2

Server Information File (server-nickname.pi)

# Administration Server Information File

Name=Administration Server
Vendor=Example Inc.
NickName=admin
Description=
Type=Package
Version=7.1
BuildNumber=

Compatible=6.0
Dependencies=

Archive=admin.tar
PreInstallProgram=ns-config
PostInstallProgram=%%%ROOT%%%/bin/admin/adm-update
StartProgram=
ImportProgram=
UninstallProgram=
RemovalProgram=
ImportProgram=

Languages=
Expires=
Security=

# Additional modules

# Administration Server Japanese Language Support
[admin-jp]
Name=Administration Server Japanese Language Support
Version=4.0

[admin-p1002]
Name=Admin Patch 1002
Description=Fix bugs causing Admin to crash at 12:00am everyday

Module Information File (module-nickname.pi)

# Web Server Module information file
Name=Web Publishing Module
NickName=webpub
Type=Module
ApplyTo=https/4.0
Description=
Version=4.0
Removable=True

Archive=webpub.tar
PreInstallProgram=
PostInstallProgram=
RemovalProgram=

# Available patches

[webpub-p25672]
Name=Web Publishing Module patch
Version=25672

Software Update Information File

Name=Web Publishing Module
Description=
Type=Update
ApplyTo=webpub/4.01.1
Description=
Revision=2

Archive=webpub-4.01.1.tar
PreInstallProgram=
PostInstallProgram=

Patch Information File

Name=Web Publishing Module Patch 1002
NickName=webpub-p1002
Description=Fix bugs in file versioning
Type=Patch
ApplyTo=webpub/4.01.1
Version=1002
Dependencies=webpub-p1001/1001

Archive=webpub-1002.tar
PreInstallProgram=
PostInstallProgram=

Explanation

Name

Format:

Alias

Server Information File only.

A shorter name for Product Name. e.g. Admin vs. Administration.

Specify one of the following:
 
Server Alias
Administration Admin
Directory Directory
Messaging Mail
Collabra News
Calendar Calendar
Enterprise Enterprise
Proxy Proxy
Catalog Catalog
Certificate Certificate
 

 NickName

An alternate name to refer to the Product, Module, Update, or Patch. For example, https for Enterprise Server.

Format:

Vendor

Format:
"Example Inc."

Description

Format:
Text. Must be on the same line.

Version

Format:
In the case of a Patch, it's the Patch Number.

Type

Type of the Package Information File.
Format:

BuildNumber

Format:

Compatible

Server Information File only.
Format:

Dependencies

This field is used to specify the list installation dependencies.
Format:
e.g

BuildNumber

Format:

Languages

Comma separated list of accepted languages in the order of preference.
Format:
e.g.

Archive

Name of package archive in the form of <nickname>.<archive suffix>.
Format:

Expires

Optional expiration date.
Format:

Security

Server Package Information File only.
Product Security level.
Format:

ApplyTo

For Module, Update, or Patch only.
Specify which package this Module, Update, or Patch applies to.
Format:

PreInstallProgram

Format:
e.g

PostInstallProgram

This field is used to specify the executable to be run right after the server binaries have been extracted into the server root. The value must be prefixed with %%%ROOT%%%.
Format:
e.g.

StartProgram

Specify the executable used to start the server. The Installer will attempt to start the server automatically if this field is specified. Start-program must be prefixed with %%%ROOT%%%.
Format:
e.g.

UninstallProgram

Applicable for NT only. Specify the GUI-based program that will remove all of a specific server's files.

RemoveProgram

Uninstallation of a server is to be handled by the server's specific uninstallation code. Specify here the name of the server removal program to be called when a server is to be removed via the Server Administration screen. The removal program must be prefixed with %%%ROOT%%% The removal program must: The Administration server will have stopped the server before invoking the uninstall program.
Format:
e.g.

The Common Installer

Synopsis

Description

ns-setup is the common installer.

Options

Pre-Installation Program

Synopsis

Description

The purpose of the pre-installation program is to collect all user inputs prior to the installation of binaries and configuration of the package. The program must be packaged as a stand-alone rather than embedded within the binary archive.

The program should adhere to the following schemes

Options

The common installer will pass the following parameters to the install-setup program:

Exit Status

The pre-installation program must explicitly return a 0 value (i.e. exit(0)) upon successful completion. Any non-zero return value may be used for non-successful completion.

PostInstallation Program

Synopsis

Description

The post-installation program configures the server/module based on the output of the pre-installation program (passed to it via the -f parameter). The post-installation program must adhere to the following:

Exit Status

The post-installation program must explicitly return a 0 value (i.e. exit(0)) upon successful completion. Any non-zero return value may be used for non-successful completion.

Silent Installation Script

Format

# COMMON PORTION GENERATED BY THE INSTALLER
#
# The common name/value pairs are defined in instutil.h
#
# Alias of the servers to install.
#   - Directory
#   - Enterprise
#   - ...
# ... separated by commas
#
#define SERVER_LIST

Servers=  Admin,Directory,Mail,News,Enterprise,

# Server Root
#  Defaults are:
#    - UNIX: /opt/<serverrootname>
#define SERVER_ROOT
ServerRoot=           /opt/fedora

# Full path name of the UNIX tar command
#define ARCHIVE_PROGRAM
ExtractProgram=       /usr/bin/tar

# Fully qualified domain name of machine, i.e. <hostname>.<domainname>
# If blank, will be autodetected
#define MACHINE_NAME
FullMachineName=      lupine.mcom.com

# URL to access LDAP server
#define LDAP_URL
LdapURL=              ldap://lupine.mcom.com:389/o=Ace Industry,c=US

# UNIX User ID and Group with which individual server will run as by default
#define SS_USER_ID
#define SS_GROUP

SuiteSpotUserID=      nobody
SuiteSpotGroup=       nobody

#
# Administrator
#
#define SS_ADMIN_ID
#define SS_ADMIN_PWD

SuiteSpotAdminID=        admin
SuiteSpotAdminPwd=       admin

# Default preferred client languages in the order of preference. What specified here should be
# a union of accepted client languages of individual server selected

PreferredLanguages=    fr

# ADMIN SERVER SECTION

[admin]

# The Port on which the Admin Server listens to. Leave blank to allow auto selection
AdminServerPort=      30000

# Run privilege of Admin Server (UNIX)
AdminSysUser=         root

# Pre-3.0 Server Root - UNIX only - optional
OldServerRoot=        /usr/ns-home

# User ID and password of the Server Administrator (to log in the Admin server)
# If absent, will default to admin/admin
ServerAdminID=        admin
ServerAdminPwd=       admin

# SERVER-SPECIFIC SECTION

[slapd]
 

[https]
 

[mail]
 

[news]
 

Installation Cache (answer cache)

The common installer will create the installation cache  with the name install.info in the <server root>/install directory. The full path name of this file will be passed to individual server's installation program to be appended with server-specific name/value pairs. The second purpose of the installation cache is to communicate information among the Common Installer and server-specific installation programs.

After the installation is complete, the user will be ask whether he/she wants to delete this file.

The format of the install.info file is exactly the same as that of the installation script file so that it could be used for subsequent similar installations.  Also, individual server installation program needs to read from the installation cache for common information such as FullMachineName, SuiteSpotUserID, etc. as specified above.

Note that re-installation of a server may not generate an output script that could be used for subsequent installation. The output script is only useful when one installs brand new servers (including the Admin server).

The current UNIX installer does not support script-generation-only mode.

User Interface

UNIX UI

UNIX UI will be modeled after InstallShield with the following capabilities: This project will provide server teams with the following C++ API for accomplishing the UI work on UNIX. Detailed descriptions and usage will be documented in the appropriate header files (dialog.h).
 

Dialog Class

C++ class implementing the curses-based screen dialogs.

DialogInput, DialogYesNo, DialogPwdEntry, DialogAlert, DialogProgress classes

"Canned" dialog screens.

DialogManager Class

Abstract class of the dialog manager who manages the dialogs in the fashion described previously. The derived dialog manager must keep track of dialogs and states and allow the user to go back and forward among the dialogs.

Reading/Writing silent installation script/ installation cache

This project will provide server teams with a C++ API for reading,writing, and manipulating the installation script/cache. Detailed description and usage will be documented in the appropriate header file (nsdefs.h).

NVPair Class

This class allows the creation, reading, writing, getting/setting of key/values of the installation script and installation cache.

Logging a silent installation session

This project will provide server teams with a C++ API for writing the installation log. Detailed description and usage will be documented in the appropriate header file (instutil.h).

Class InstallLog

This class allows the creation and writing of the silent installation log. Detailed description and usage will be documented in the appropriate header file (instutil.h)
Copyright (C) 2001 Sun Microsystems, Inc. Used by permission. Copyright (C) 2005 Red Hat, Inc. All rights reserved.
This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at http://www.opencontent.org/openpub/