Previous     Contents     Index     Next     
Setup Util Programmer's Guide



Chapter 2   Quick Start


This chapter briefly explains the steps involved in writing an installer with the Setup Util.

It contains the following sections:



Overview of Installations

Installing a product can involve a number of procedures including copying files, getting user input, interacting with a Directory Server, and configuring an application. While some of these tasks are optional or product-specific, others are common to all installations.

An installation typically starts with downloading the Common Install Shell and running it. The shell then does the following:

  1. Determines what server packages and components can be installed or updated.

  2. Prompts the user to choose what to install or update.

  3. Retrieves the selected server packages and components from the repository

  4. Installs the server packages and components.

The shell can also invoke any pre- and post-installation programs.



Performing a Basic Installation



Although the Setup Util supports many advanced features, you can also use it to create a simple installer.

To perform a basic setup procedure you only need to archive your product binaries and modify information files. If desired, you can also request user input, configure products, and register configuration information in the Directory Server during installation.

The rest of this chapter will show you how to perform the tasks required to create a basic installer.


Archiving Product Files

The Setup Util can only install products that are archived in the ZIP format.


To Prepare Your Product Archive

  1. Assemble all files that you want to archive into the desired directory structure. This structure should be identical to the one that you want the installer to create.

  2. Run a ZIP utility to create the product archive. If your machine does not have a zip utility, get it from the web.

    UNIX: zip -r zipfile.zip files where zipfile is the name for the archive and files are the filenames and directories to archive. Make sure to use the -r flag to preserve your directory structure.

    Windows NT: Use a program such as WinZip or InfoZip to create the product archive. Make sure to include subfolders and extra folder information to preserve your directory structure.

  3. Copy the archive to a directory in your repository. Typically, these directories use product nicknames, such as slapd or admin.


Modifying Information Files

During a basic installation, the Setup Util uses two information files. The first, setup.inf, specifies general installation settings as well as the location of additional information files. These additional package information files contain the settings used when installing the server products.

When you install the Setup Util, two sample information files are copied for you. The sample setup.inf file is in the setup directory and the sample package information file, svrcore.inf, is in the setup/svrcore directory.


The setup.inf Information File

The setup.inf file contains information about the installer and the location of one or more package information files. A sample is shown below.


[General]
Name= Example Server Products
Vendor= Example, Inc.
Description= Example Server Products Installation
Mode= ALLMODES
ProgramFolder= Example Server Products
Components= svrcore

[svrcore]
ComponentInfoFile= svrcore/svrcore.inf

You can customize and expand the sample setup.inf file. Fields in the [General] section of setup.inf contain information about your company, the setup program, and which components to install:

Name. What this installer will set up.

Vendor. Your company's name.

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

Mode. 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.

Each component that you list in [General] should have its own section of setup.inf. These sections should contain a field called ComponentInfoFile which identifies the location of a package information file.

For example, if you are installing an application called myProduct, you might create a section of setup.inf called [myProduct] followed by the line ComponentInfoFile = myProduct/myProduct.inf.


The Package Information File

The values specified in the ComponentInfoFile fields of setup.inf identify the location of package information files. These information files contain a product's unique installation settings. A sample is shown below.


[General]
Name= prefix core components
Nickname = svrcore
Version=4.5
BuildNumber= 1999.320.0903
Compatible= 4.0
SourcePath=svrcore
Archive= nssvrcore.zip
Mandatory= true
Checked=true
Visible=False
IsMCC=True
UseLdap=false

Like setup.inf, package information files also contain a [General] section. There are a number of fields you can specify in a[General] section. For a basic installation, you only need to modify the following:

Name. Specify the full name of the package you are installing.

Nickname. Enter the nickname for this package.

Version. Enter the version number for this package.

SourcePath. Enter the name of the directory in which you stored your product archive.

Archive. Enter the name of your product archive file. For more information on creating this archive, see Archiving Product Files" above.

There are many additional fields you can specify in a package information file. For details, see Chapter 3 "Information Files."

If you run setup, any components specified in setup.inf will be installed. If you want to store information in a Directory Server, obtain user input, or perform additional product configuration, read the next section, Extending Your Installation."



Extending Your Installation



You can extend a basic installer to accept user input, configure products, and register information in a Directory Server.


Requesting Input and Configuring Your Product

It is often helpful to request user input before performing an installation and then use it to copy and configure files. Through the use of a pre-installation program, you can gather responses to setup questions before installation. Once the files are copied, you can use a post-installation program to configure your product.

On UNIX, pre- and post-installation programs are both stand-alone executables that are invoked by the Common Install Shell. In order to integrate with the shell, these programs should use the Setup Util libraries. On Windows NT, pre- and post-installation programs are stored in Dynamic Link Libraries (DLLs). One DLL is specified in each package information file. For more information on pre- and post-installation programs, see Chapter 4 "Writing Pre-Installation Programs" and Chapter 6 "Writing Post-Installation Programs."


Registering Information in the Directory Server

When performing a basic installation, you only need to create a product archive and modify information files. Nonetheless, you may want to register configuration information in the Directory Server. This allows administrators to work with your product from within Console.

Registering information in the Directory Server requires the creation of an LDIF file as well as the addition of two lines to your package information file.


To Register Information in the Directory Server

  1. Create an LDIF file containing the entries you wish to create in the Directory Server.

    For example, task entries in myProduct.ldif might look like this:

    dn: cn=Stop, cn=Operation, cn=Tasks
    objectclass: top
    objectclass: nstask
    objectclass: nsMyProductObject
    nsexecref: stopMe

    dn: cn=Restart, cn=Operation, cn=Tasks
    objectclass: top
    objectclass: nstask
    objectclass: nsMyProductObject
    nsexecref: restartMe

    dn: cn=Configure, cn=Operation, cn=Tasks
    objectclass: top
    objectclass: nstask
    objectclass: nsMyProductObject
    nsexecref: configureMe

  2. Save your LDIF file in the same directory as your package information file and archive.

  3. Add the following to the end of your package information file:

    useLdap=True

    updateLdif=myProduct.ldif where myProduct.ldif is the file you created above.

When you run setup, the contents of your LDIF file will be imported into the Directory.



A Simple Installation



If you do not need to configure your product based on user responses, you can create a fully functional installer without writing any specialized code.

The following example illustrates how the Directory Management Solutions team created an installer for the Windows NT versions of the Example Administrator plug-ins.


Background Information

Example Administrator is an HTML-based application for managing user and group information stored in an LDAP Directory Server. It uses Access Control Instructions (ACIs) to specify which information administrators can view and modify.

In version 4.5, the Example Administrator team is using the Directory Server Class of Service plug-in and Performance Measurement Tools to assist in user management. In order to bundle this software with Delegated Administrator, they need to create an installer. This process involves creating an archive and modifying the setup.inf file that comes with the Setup Util.


Creating the Archive

Once the team has a solid base of code, they can prepare a product archive. This involves the following steps:

  1. The team copies the appropriate files into the desired directory structure.

    A directory called lib containing four files: cos-plugin.dll, libsubtreecounter.dll, libvaluecounter.dll, uid-plugin.dll

    A directory called setup/plugins containing three files: cos_schema_at.conf, cos_schema_oc.conf, update_slapd.ldbm.conf

  2. The team runs InfoZip to create the product archive.

    The archive is called plugins.z.

  3. The team copies the archive to the plugins directory in their repository.


Creating the Information Files

With the archive in place, the team is ready to modify the master information file and create a package information file. To do this, they can use the sample setup.inf file that comes with the Setup Util.

  1. The team opens setup.inf in a text editor. The file looks like this:


    #
    # Sample Server Package Information File
    #
    # Components: lists the components to be installed as specified
    # in subsequent sections. If the section or the ComponentInfoFile
    # does note exist the setup program will ignore the component

    [General]
    Name         =    Example Server Products
    Vendor       =    Example, Inc.
    Description  =    Example Server Products Installation
    # Version    =    4.2
    Components =    svrcore, base, admin, slapd, dssynch, msg, mesg-cntrl, cert, mcc, nda, cal, enterprise
    Mode         =    ALLMODES
    ProgramFolder=    Example Server Products
    #DefaultInstallDirectory works for NT and UNIX, NT will set the drive letter to WINDISK
    #DefaultInstallDirectory = /opt/serverrootname

    # Package Contents
    [svrcore]
    ComponentInfoFile = svrcore/svrcore.inf

    [base]
    ComponentInfoFile = base/base.inf

    [admin]
    ComponentInfoFile = admin/admin.inf
    omponentInfoFile = cal/cal.inf
    ...

  2. The team modifies the file to look like this:


    #
    # Installer for iDA Directory Plugins
    #
    [General]
    Name         =    Example Server Products
    Vendor       =    Example, Inc.
    Description  =    Example Server Products
    Version      =    7.1
    Components   =    plugins
    Mode         =    Typical
    FinishMessage=Please read README.txt for instructions on configuring the plugins.

    # Package Contents
    [plugins]
    ComponentInfoFile = plugins/plugins.inf

  3. The team saves the setup.inf file

  4. The team prepares the package information file by modifying setup.inf again.

    When they are finished, they have the following package information file:


    # plugins.inf
    # Package info for iDA45 directory plugins

    [General]
    Name=NDA 4.5 directory plugins
    Description=NDA 4.5 directory plugins
    Nickname=plugins
    Nersion=4.5
    Revision=1
    BuildNumber=2000.123.1122
    Archive=plugins.z
    Compatible=4.5
    Checked=true
    Mandatory=true
    sourcepath=plugins

  5. The team saves the file as plugins.inf and then copies it to the plugins directory in their repository.

During installation, the Common Install Shell reads setup.inf, locates plugins/plugins.inf, and then extracts the files from the archive into a user-specified destination.

The Common Install Shell manages the display of the User Interface and the details of gathering and processing user input. The Directory Management Solutions team simply provides basic information about their component.

If the team decides to perform custom configuration procedures, they can write pre- and post-installation programs to retrieve and process user input. For examples of pre- and post-installation programs, see "Chapter 13, Sample 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