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
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
Open setup.inf in a text editor.
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.
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].
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.
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
Open a blank file in a text editor.
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.
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.
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
Open a blank file in a text editor.
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.
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.
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
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.
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.
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
the readme.txt file would be installed directly under the installation root.
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
Indicates that the package is part of Console. Possible values are True and False.
This directive is only used when installing Console "client" components.
Specifies which directories to not remove during uninstallation. The Uninstall Shell will keep all files and subdirectories.
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.
Specifies which files to not remove during uninstallation. The Uninstall Shell will keep the directories containing these files.
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.
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.
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.
Specifies the program to use instead of the Uninstall Shell binary removal code.
Do not use this directive when performing a regular uninstallation.
Unique name used to identify the patch. The value can be a combination of numbers, letters, and symbols, but cannot contain any spaces.
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:
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:
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:
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:
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.
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.
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
The component's version. Use the form major version.minor version.
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
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."
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.
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
Specifies the name of the function within the DLL that is used to display the user interface.
For more information on developing DLLs, see Chapter 4 "Writing Pre-Installation Programs" and Chapter 6 "Writing Post-Installation Programs."
Specifies the name of the function within the plug-in DLL that is used to retrieve a summary of user-entered options.
GetSummary=RetrieveUserOptions
For more information on developing plug-ins, see Chapter 4 "Writing Pre-Installation Programs."
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.
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.
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.
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.
ReadGlobalCache=ReadGlobalCacheValues
For more information on developing plug-ins, see Chapter 4 "Writing Pre-Installation Programs."
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.
ReadLocalCache=ReadProductCache
For more information on developing plug-ins, see Chapter 4 "Writing Pre-Installation Programs."
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.
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.
WriteGlobalCache=WriteGlobalCacheValues
For more information on developing plug-ins, see Chapter 4 "Writing Pre-Installation Programs."
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.
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