Previous     Contents     Index     Next     
Setup Util Programmer's Guide



Chapter 3   Information Files


This chapter introduces information files, one of the main elements in an installation. It contains the following sections:



Understanding Information Files

Information files are used to pass parameters to the Common Install Shell. They contain basic data such as product names, version numbers, and archive locations. In addition, information files can contain lists of components to install. This allows you to create installations that can flexibly handle numerous packages.

There are two types of information files: master and package. A master information file contains generic package descriptions and pointers to individual package information files. Package information files list the settings that the setup program should use when installing a specific component.

An installation repository has one master information file. Each product or component that is listed in the master file has its own package information file. Optionally, each of these package information files can list subcomponents, allowing for up to three levels of product and component selection. The rest of this chapter will show you how to customize and create master and package information files.



Customizing Information Files



In order to install a product, you must customize the master information file and any package information files that you intend to use. This section will show you how to do this.


Working with the Master Information File

A sample master information file was copied for you during Setup Util installation. This file is called setup.inf and is located in the root directory where you installed the Util.

The setup.inf file is relatively short. It contains a few high-level variables, a list of components, and pointers to those components' package information files. Before you install a product or component, you must modify setup.inf.


To Modify the Master Information File

  1. Open setup.inf in a text editor.

  2. Modify the following fields in the [General] section to meet your product's requirements. For additional valid directives, see Information File Directives" below.

    Name. What this installer will set up. For example, you might use the value "Server Products."

    Vendor. Your company's name.

    Description. A brief description of what this installer is used for.

    Mode. (used by NT only) Specifies the installation mode to use. Possible values include: Express, Typical, Custom, or ALLMODES.

    You can only specify one of these modes. If you specify multiple modes or ALLMODES, the user will have to choose between Express, Typical, and Custom.

    ProgramFolder. (used by NT only) Specifies the name of the Windows NT Program Group in which the installed products will be located. The user will see this name when launching your product from Start > Programs.

    Components. A comma-separated list of the components to install.

  3. Create an additional section of setup.inf for each component that you want to install.

    Each component that you list in [General] should have its own section of setup.inf. For example, if you are installing an application called myProduct, you would create a section of setup.inf called [myProduct].

  4. Create a field called ComponentInfoFile for each component section.

    This field identifies the location of a package information file. For example, in the [myProduct] section, you would include the line

    ComponentInfoFile = myProduct/myProduct.inf.

  5. Save setup.inf in the root directory of your installation repository.


Working with Package Information Files

Every component section in setup.inf lists a package information file. These files contain many of the instructions used to install specific products. There are two formats for package information file. One is used for non-modular component packages, the other is used for modular packages.

Both formats have a [General] section containing information such as package name, version number, and vendor. Non-modular packages list all fields directly beneath the [General] section. Modular packages have additional sections for each module. Sample package information files for non-modular and modular component packages are shown below.


To Create a Non-Modular Package Information File

  1. Open a blank file in a text editor.

  2. Create a [General] section with the following fields:

    Name. This indicates what the installer will set up. For example, you might use the value "Server Products."

    Vendor. Your company's name.

    Nickname. Your product's nickname. This is usually the same as the directory in which your binaries are stored. For example, Directory Server's nickname is slapd and Administration Server's nickname is admin.

    Description. A brief description of your product. For example "Administration Server."

    Version. Your product's version number.

    BuildNumber. Your product's build number. For example "197.24.3356."

    Compatible. The lowest version number of this component with which the new version is compatible. Versions are compatible if, after overwriting an existing component with a replacement, the product still functions normally.

    Dependencies. (Optional) A comma-separated list of components that must be installed before this package.

  3. Add the following package information after your list of dependencies:

    SourcePath. The name of the directory in which your product archive is stored.

    Archive. The name of your archive.

  4. Save your file as nickname.inf where nickname is your product's nickname. Copy this file into your product directory within the installation repository.

There are a number of additional directives you can provide in information files. For more information, see Information File Directives" below.


To Create a Modular Package Information File

  1. Open a blank file in a text editor.

  2. Create a [General] section with the following fields:

    Name. This indicates what the installer will set up. For example, you might use the value "Server Products."

    Vendor. Your company's name.

    Description. A brief description of your product. For example "Administration Server."

    Dependencies. (Optional) A comma-separated list of components that must be installed before this package.

    Components. A comma-separated list of modules to install.

  3. Add a section for each module you listed above.

    Each section should begin with [nickname] where nickname is a single module. The sections should include the following fields.

    Name. The name of the module or component. For example, "Administration Server."

    Vendor. Your company's name.

    Nickname. Your product's nickname. This is usually the same as the directory in which your binaries are stored. For example, Directory Server's nickname is slapd and Administration Server's nickname is admin.

    Description. A brief description of your product. For example "Administration Server."

    Version. Your product's version number.

    BuildNumber. Your product's build number. For example "197.24.3356."

    Compatible. (UNIX Only) The lowest version number of this component with which the new version is compatible. Versions are compatible if, after overwriting an existing component with a replacement, the product still functions normally.

    SourcePath. The name of the directory in which your product archive is stored.

    Archive. The name of your archive.

  4. Save your file as nickname.inf where nickname is your product's nickname. Copy this file into your product directory within the installation repository.

There are a number of additional directives you can provide in information files. For more information, see Information File Directives" below.



Information File Directives



In order to provide the maximum amount of flexibility, the Setup Util supports many different information file directives. You can use these to provide detailed installation instructions to the Common Install Shell.

Table 3-1 lists all information file directives that are supported on both UNIX and Windows NT, whether they are required, and descriptions of their functionality.

Table 3-2 lists all information file directives that are only supported on UNIX, whether they are required, and descriptions of their functionality.

Table 3-3 lists all information file directives that are only supported on Windows NT, whether they are required, and descriptions of their functionality.


Table 3-1 Information File Directives, Requirements, and Descriptions

Directive Name

Required Field?

Description

[section]  

No  

Indicates the beginning of an information file section. Possible values are General and the name of a package or module. Any component that is listed in the master information file must have a corresponding section.  

ApplyTo  

No  

The package to update or patch. This directive is only used for software updates and patches. Use the format nickname/version where nickname is your product's nickname and version is the version number that you wish to patch.  

Archive  

No  

A comma-separated list of ZIP archive files containing component binaries. Use the format: <path>/filename.zip where path is relative to SourcePath.

If you want to use your pre-installation program to determine which product archive to unzip, specify a default archive here. You can change this value later. See Chapter 4 "Writing Pre-Installation Programs" for information on selecting archives during pre-installation.

NT only: The Common Install Shell will unzip any file ending in ".z". Any other files are copied into the installation root.

For example, if admin.inf contains the following line:

Archive=admin.z, \bin\admin\readme.txt

admin.z would be unzipped into the installation root and readme.txt would be installed into the installation root's bin\admin\ subdirectory. If admin.inf contained the line

Archive=admin.z, readme.txt

the readme.txt file would be installed directly under the installation root.  

BackupFiles  

No  

A comma-separated list of files to back up before unzipping the archive. When used with RestoreFiles, this directive lets you recover important data that is overwritten during installation.

Use the format path/filename where path is either a fully qualified path to the file or a relative path from the server root.

For example, BackUpFiles= admin-serv/config/adm.conf,/usr/lib/libslapd##.so

The date will be appended to the backup files as a suffix.  

BuildNumber  

UNIX: Yes

NT: No  

The build number as generated during the build process.  

Checked  

No  

Indicates whether a component is selected by default. On Windows NT, you can select all components by listing this directive in the [General] section of setup.inf.

Possible values for Checked are True and False. If this directive is not listed, the Common Install Shell uses the default value of False.  

Compatible  

UNIX: Yes

NT: No  

The lowest version number of this component with which the new version is compatible. Versions are compatible if, after overwriting an existing component with a replacement, the product still functions normally.  

ComponentInfoFile  

No  

A pointer to a component's package information file. Use the form path/filename where path is relative to the SourcePath.

This directive is only used in the master information file (setup.inf).

If a component does not contain any modules, you can embed its package information directly in a section of the master information file.  

Components  

No  

A comma-separated list of components. In the master information file, each component is a package. In a package information file, each component is a module.

Use package or module nicknames to specify a component. You must include a section in the information file for every listed component.  

Dependencies  

No  

A comma-separated list of components that must be installed before this package.Use the format component/version

Sometimes, one post-installation program requires the successful completion of another one. If this is the case, make sure to list the appropriate dependencies here.  

Description  

UNIX: No

NT: Yes.  

Description of the component.  

Destination  

No  

By default, components are installed into the server root. To install the component in a different location, specify an absolute path.

If you want to set the destination dynamically during pre-installation, you must set an absolute path for Destination in your cache file.  

Expires  

No  

A whole number specifying the number of days until this product expires.

For example, the value Expires=90 specifies that this installation will stop working 90 days from today.  

FinishMessage  

No  

Customizes the message that is displayed at the end of installation.

The value for this directive must fit on a single line in the information file. Insert \n wherever you want a line break to appear onscreen. The value that you specify here replaces the default finish message.

On UNIX, the default message is "Go to <server_root> and type startconsole to begin." On Windows NT, the default finish message can take two forms. If necessary, it prompts the user to restart the system. Otherwise, it offers the option of viewing a Readme file and launching Console.

If this directive is not present, the Common Install Shell will display the default finish message.  

ForceExpressInstall  

No  

Specifies that this component should be installed using Express even if the user selects a different mode. Possible values are True and False.

Use this directive in server and component package information files. If this directive is not present, the Common Install Shell uses the default value of False.  

IsMCC  

No  

Indicates that the package is part of Console. Possible values are True and False.

This directive is only used when installing Console "client" components.  

KeepDirectories  

No  

Specifies which directories to not remove during uninstallation. The Uninstall Shell will keep all files and subdirectories.

For example, the directive

KeepDirectories=userdb, admin-serv/config,

prevents the Uninstall Shell from deleting the userdb and admin-serv/config directories as well as all files and subdirectories beneath them.  

KeepFiles  

No  

Specifies which files to not remove during uninstallation. The Uninstall Shell will keep the directories containing these files.

For example, the directive

KeepFiles=userdb/user.conf, admin-serv/config/adm.conf

prevents the Uninstall Shell from deleting user.conf and adm.conf as well as the userdb and admin-serv/config directories.  

Mandatory  

No  

Indicates whether a component is a mandatory part of the installation. Possible values are True and False.

If Mandatory is set to True and Visible is set to True, the component is "checked" and the user cannot deselect it.

If Mandatory is set to True and Visible is set to False, the component is hidden from the user, but still installed.

If this directive is not present, the Common Install Shell uses the default value of False.  

Mode  

No  

Installation mode. Possible values are Express, Typical, Custom, and AllModes. If you specify a single value, the Common Install shell will not prompt the user to choose a mode. If you specify multiple values or AllModes, the Common Install Shell will prompt the user to select an installation mode.

If this directive is not present, the Common Install Shell will use the default value of AllModes.  

Name  

UNIX: Yes

NT: Yes  

The full name of the component, i.e. Directory Server  

Nickname  

UNIX: Yes

NT: No  

The component's nickname.  

OverrideUninstall  

No  

Specifies the program to use instead of the Uninstall Shell binary removal code.

Do not use this directive when performing a regular uninstallation.  

PatchID  

No  

Unique name used to identify the patch. The value can be a combination of numbers, letters, and symbols, but cannot contain any spaces.

Example:

PatchID=fix#11  

PostInstall  

No  

Specifies the post-installation program. On UNIX, use the format path/program [parameters] where path is relative to the server root.

On Windows NT, specify the name of the function in your DLL that is used to launch the post-installation program.

Example PostInstall value for UNIX:

bin/admin/bin/adm-postinst

Example PostInstall value for Windows NT:

Post-Install  

PostUninstall  

No  

Specifies the post-uninstallation program. Use the format path/program [parameters] where path is relative to the server root.

On Windows NT, specify the name of the function in your DLL that is used to launch the post-uninstallation program.

Example PostUninstall value for UNIX:

bin/admin/adm-postuninstl

Example PostUninstall value for Windows NT:

Post-Uninstall  

PreInstall  

No  

Specifies the pre-installation program. This executable file must reside in the directory specified in the SourcePath directive.

On Windows NT, specify the name of the function in your DLL that is used to launch the pre-installation program.

Example PreInstall value for UNIX:

bin/admin/bin/adm-preinst

Example PreInstall value for Windows NT:

Pre-Install  

PreUninstall  

No  

Specifies the pre-uninstallation program. Use the format path/program [parameters] where path is relative to the server root.

On Windows NT, specify the name of the function in your DLL that is used to launch the pre-uninstallation program.

Example PreUninstall value for UNIX:

bin/admin/bin/adm-preuninst

Example PreUninstall value for Windows NT:

Pre-Uninstall  

Registration  

No  

Indicates whether a popup window reminding the user to register this product should appear when Console is started for the first time. Possible values are True and False.

If this directive is not present, the Common Install Shell will use the default value of False and a popup will not appear.  

RequireDomain  

No  

Indicates whether a domain name is required for product installation.

If this directive is not present, the Common Install Shell will use the default value of True and a domain name will be required.  

RestoreFiles  

No  

A comma-separated list of files to restore after unzipping the archive. When used with BackupFiles, this directive lets you recover important data that is overwritten during installation.

Use the format path/filename where path is either a fully qualified path to the file or a relative path from the server root.

For example, RestoreFiles= shared/config/certmap.conf,/usr/lib/libslapd##.so  

Revision  

No  

Component's revision number. This value must be a whole number. For example, Revision=3.

This value is only required for software update modules or patches. If this field is absent, the default value of 0 is used.  

Security  

No  

Type of security used by this product. Possible values are Domestic, Export, or None. If this field is not present, the default value of None is used.

If you are performing an upgrade, the following hierarchy applies:

You can install Domestic over any type of security.

You can install Export over Export or None.

You can install None over None only.  

SecurityCheck  

No  

Indicates whether the Setup Util should check version, dependency, and security level (export/domestic) compatibility within a given server root.

Include this directive in the [General] section of your master information file.

Do not use this directive if your product shares security code with other products.

If this directive is not present, the Common Install Shell uses the default value of True.  

SourcePath  

UNIX: Yes

NT: No  

The name of the directory in which your product archive is stored. This should be a path relative to the directory from which setup is run.  

Type  

No  

Indicates whether you are performing a software update or patch. Possible values are Update and Patch. This directive is only used for software updates and patches.  

UpdateLdif  

No  

A comma-separated list of LDIF files to import into the Directory after post-installation.

Specify files using absolute paths or paths relative to the server root.  

UpdateSchema  

No  

A comma-separated list of LDIF files containing schema changes. The Common Install Shell will import these schema changes into the Directory after post-installation.

Specify files using absolute paths or paths relative to the server root.  

UseLDAP  

No  

Specifies whether to store configuration information in a Directory Server. Possible values are True and False.

If UseLDAP=True, the Common Install Shell requests Configuration Directory information and then authenticates the user.

If this directive is not present, the Common Install Shell uses the default value of False.  

UserDirectoryAuth  

No  

Indicates that at least one server or component requires access to user information stored in an LDAP directory. Possible values are True and False.

If UserDirectoryAuth is set to True, the Common Install Shell will prompt the user for the Directory Server URL and associated authentication credentials.

If this directive is not present, the Common Install Shell will use the default value of False.  

Vendor  

UNIX: Yes

NT: No  

Your company name.  

Version  

UNIX: Yes

NT: No  

The component's version. Use the form major version.minor version.  

Visible  

No  

Indicates whether a component is displayed on the selection screen. Possible values are True and False.

Use this option with Mandatory to specify components that must be installed as part of a product.

If this directive is not present, the Common Install Shell uses the default value of True.  


Table 3-2 UNIX-Only Information File Directives, Requirements, and Descriptions

Directive Name

Required Field?

Description

Resource  

No  

Specifies an external resource file to use when customizing common UI text. Set this directive in the [General] section of your master information file.

For more information on customizing common UI text, see Chapter 5 "Creating Dialogs."  

skipSSUserDialog  

No  

Specifies whether to skip the User/Group dialog on UNIX. Possible values are True (skip the dialog) and False (do not skip the dialog).

If this directive is not present, the Common Install Shell uses the default value of False.  

StartProgram  

No  

The program to start after all binary files are copied to the server root.

Specify the program using an absolute path or a path relative to the server root. You can only use this directive when performing an update or patch.  


Table 3-3 Windows NT-Only Information File Directives, Requirements, and Descriptions

Directive Name

Required Field

Description

AskOptions  

No  

Specifies the name of the function within the DLL that is used to display the user interface.

Example:

AskOptions=QueryUser

For more information on developing DLLs, see Chapter 4 "Writing Pre-Installation Programs" and Chapter 6 "Writing Post-Installation Programs."  

GetSummary  

No  

Specifies the name of the function within the plug-in DLL that is used to retrieve a summary of user-entered options.

Example:

GetSummary=RetrieveUserOptions

For more information on developing plug-ins, see Chapter 4 "Writing Pre-Installation Programs."  

IsAdmin  

No  

When True, indicates that the component is the Administration Server. Possible values are True and False.

If this directive is not present, the Common Install Shell uses the default value of False.  

IsLdap  

No  

When True, indicates that the component is the Directory Server. Possible values are True and False.

If this directive is not present, the Common Install Shell uses the default value of False.  

PlugIn  

No  

The plug-in Dynamic Link Library (DLL) used for pre-installation. Specify a path relative to the Common Install Shell source directory.

If an information file lists components, include this field in any package or module entries for which there is a pre-installation program.  

ReadGlobalCache  

No  

Specifies the name of the function within the plug-in DLL that is used to read information from the global section of the cache file.

Example:

ReadGlobalCache=ReadGlobalCacheValues

For more information on developing plug-ins, see Chapter 4 "Writing Pre-Installation Programs."  

ReadLocalCache  

No  

Specifies the name of the function within the plug-in DLL that is used to read information from the product-specific (local) section of the cache file.

Example:

ReadLocalCache=ReadProductCache

For more information on developing plug-ins, see Chapter 4 "Writing Pre-Installation Programs."  

System32Archive  

No  

Specifies which files to unzip and which to copy to the WINNT/System32 directory.

The only acceptable value for System32Archive is a comma-separated list of Windows NT archive files. If an archive has the extension ".z," it is unzipped. Otherwise, it is considered a system file and placed in the WINNT/System32 directory.

For example, if you include the following directive:

System32Archive=ida.z, prodx.z, runtime.dll

the Common Install Shell will unzip ida.z and prodx.z into the destination directory, and copy runtime.dll into the WINNT/System32 directory.  

WriteGlobalCache  

No  

Specifies the name of the function within the plug-in DLL that is used to write user-entered information to the global section of the cache file.

Example:

WriteGlobalCache=WriteGlobalCacheValues

For more information on developing plug-ins, see Chapter 4 "Writing Pre-Installation Programs."  

WriteLocalCache  

No  

Specifies the name of the function within the plug-in DLL that is used to write user-entered information to the product-specific (local) section of the cache file.

Example:

WriteLocalCache=WriteProductCache

For more information on developing plug-ins, see Chapter 4 "Writing Pre-Installation Programs."  


Previous     Contents     Index     Next     
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/

Last Updated September 21, 2001