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:
-
The Package Information File (.pi)
-
The Pre-Installation program as a standalone program
-
The Package Archive which consists of
-
The Post-Installation program in bin/<server nickname>/<post-install
program>. For example, bin/admin/adm-update. The Post-Installation
Program can be of any name.
-
The Uninstallation program in bin/<server nickname>/<uninstall
program>. For example, bin/admin/adm-remove.
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
-
Comment: any line starting with a # or ; is treated as a comment line
-
Key/Value (or Name/Value): one pair per line with Key and Value being separated
by = or <space>
-
List: a list is a Key/Value pair with the Value being a comma delimited
string.
Named section: enclosed in square brackets []
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:
<Name> Server
e.g. Administration Server, Messaging Server
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:
<major version>.<minor version>.<revision>
In the case of a Patch, it's the Patch Number.
Type
Type of the Package Information File.
Format:
Type= Composite | Package | Module | Update | Patch
BuildNumber
Format:
xxx.xx.xxxx
e.g. 97.125.1023
Compatible
Server Information File only.
Format:
As that of Server Version.
Dependencies
This field is used to specify the list installation dependencies.
-
If appearing in Server Information File, the list of other servers
that must be installed in order for this server to be installed into the
same server root. Note that this is in contrast to run-time dependency
that is not enforced by the installer.
-
If appearing in Module Information File, the list of other modules of the
same server that must be installed first.
-
If appearing in Patch Information File, the list of other patches to the
same server or module that must have been installed first.
Format:
Dependencies= <server alias>/<server version>, ..., ...
Dependencies= <module-nickname>/<module version>,...,...
Dependencies= <patch-nickname>/<patch version>
e.g
Dependencies: Admin/7.1, Directory/7.2
BuildNumber
Format:
xx.xxx.xxxx
e.g. 97.125.1033
Languages
Comma separated list of accepted languages in the order of preference.
Format:
Languages= <language1>, <language2>, ...
e.g.
Archive
Name of package archive in the form of <nickname>.<archive suffix>.
Format:
Expires
Optional expiration date.
Format:
Expires=%%%PUMPKIN_HOUR%%%
Security
Server Package Information File only.
Product Security level.
Format:
Security= None | Domestic | Export
ApplyTo
For Module, Update, or Patch only.
Specify which package this Module, Update, or Patch applies to.
Format:
PreInstallProgram
Format:
PreInstallProgram <name of executable>
e.g
PreInstallProgram ns-config
<any additional options>
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:
PostInstallProgram %%%ROOT%%%/<path/executable>
e.g.
PostInstallProgram %%%ROOT%%%/bin/admin/adm-update
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:
StartProgram %%%ROOT%%%/<path/executable>
e.g.
StartProgram %%%ROOT%%%/start-admin
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:
-
Determine which files to keep and which can be safely remove
-
Remove the server instance
-
Remove the server's binaries if requested and associated directories
The Administration server will have stopped the server before invoking
the uninstall program.
Format:
RemoveProgram <path/executable>
e.g.
RemoveProgram %%%ROOT%%%/bin/slapd/uninst
The Common Installer
Synopsis
ns-setup [-s <silent install-script>][-q]
Description
ns-setup is the common installer.
Options
-s <install-script>
Optional parameter to specify silent installation mode and the installation
script.
-q
Optional parameter to specify Express Mode. This option is mutually
exclusive from -s.
Pre-Installation Program
Synopsis
pre-install [-q] [-s -l <log file> ] [-f <install script>]
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
-
As appropriate, functions as a stand-alone program which the user can execute
to reconfigure the package (whether it's a server or module).
-
Uses the specified UI framework so as to keep consistent look
and feel across servers
Options
The common installer will pass the following parameters to the install-setup
program:
-s
-l <log file>
For silent installation, <input script> and <log file> will contain
the full path to the installation script and installation log.
-f <install script>
Full path name to the installation script. If Silent Installation is
true, this is the silent installation script; otherwise, it is the answer
cache. Note that -f <install script> will always be present. The pre-installation
program is to write installation specific variables to this file.
-q
Express Mode. This option is mutually exclusive with -s.
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
post-install [-s -l <log file> ] [-f <install info>]
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:
-
Must not be interactive
-
Must write to standard output if needed
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:
-
The user should be able to go back to a previous screen (using CTRL-B)
-
Error or information popup allows the user to go back to the previous screen
by hitting RETURN.
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/