Chapter 2 Working With the Sun Update Connection - Automated Baseline Management Service 1.0 (Tasks)

This chapter describes the procedures that are associated with the TLP 2.3 tool that is used by Sun Update Connection - ABMS 1.0 service offering. Information about installing and using the TLP 2.3 tool to automatically generate patch sets on multiple systems in large data centers is described in this chapter.

For information on the step-by-step procedures that are associated with administering TLP, see the following:

• TLP Software Installation (Task Map)

• Using the TLP Tool (Task Map)

For overview information on TLP, see Chapter 1, Sun Update Connection - Automated Baseline Management Service 1.0 (Overview). For TLP reference information, see Chapter 3, Sun Update Connection - Automated Baseline Management Service 1.0 (Reference).

For more information on the step-by-step procedures that are associated with managing patches in the Solaris OS, see Chapter 21, Managing Solaris Patches by Using Sun Patch Manager (Tasks), in System Administration Guide: Basic Administration, and Chapter 22, Managing Solaris Patches by Using the patchadd Command (Tasks), in System Administration Guide: Basic Administration.

TLP Software Installation (Task Map)

This task map includes all of the installation tasks that must be completed before you can use the TLP tool. Note that some of the installation procedures must be completed in sequential order. The order in which these procedures should be performed is indicated in this task map.

Installing the TLP Server Software

The TLP server software installation includes the following tasks:

1. Installing or upgrade the TLP server software on a dedicated system.

2. Modifying the tlp.cfg file for your site's specific setup.

3. Updating the configuration, snapshots, and the metafiles (Applies to TLP software upgrades only)

4. Configuring the TLP web server script configuration.

This section provides instructions for installing and configuring the TLP server software. Also included in this section are instructions for upgrading the TLP software and installing the TLP baselines.

How to Install the TLP Server Software

This procedure describes how to install the TLP server software. In this procedure, the current working directory is the TLP installation directory, /opt/SUNWtlp.

Before You Begin

Before you begin the installation, ensure that you have the following:

• A sufficient amount of disk space available on the system.

  For each set of baselines that you use, you will need 3 to 4 Gbytes of disk space. In addition, you need to reserve disk space for each TLP client. The amount of space that is required for each client system can vary between 1 to 5 Mbytes. In rare instances, the amount of disk space that is required could reach 200 Mbytes. Because the created patch sets are built from symbolic links that point to the patch repository, each patch set only requires about 100 Kbytes of disk space.

• Perl, version 5.005_03, or later installed on the system.

  Perl, version 5.005_3, or later is bundled with all Solaris OS versions, beginning with the Solaris 7 OS.

• An HTTP server installed on the system.

  The Apache HTTP Web Server software is bundled with the Solaris OS.

• The latest TLP server software, which has been downloaded from the TLP server.

• Access to the Sun patch baselines, for example, on an EIS-CD.

Steps

1. Log in as superuser to the system where you will install the TLP server software.

2. Extract the archive SUNWtlp-2.3.tar.gz to the /tmp directory.

   # gzcat SUNWtlp-2.3.tar.gz | tar xvf -

3. Check the README file in /opt/SUNWtlp/README for the latest updates.

4. Install the TLP software package.

   # pkgadd -a tlp.policy -d SUNWtlp-2.3

   By default, the TLP software is installed in the /opt/SUNWtlp directory. See How to Add Software Packages (pkgadd) in System Administration Guide: Basic Administration for information on how to modify the installation directory.

5. Create the UNIX user and group for the tlp-user

   Although you can run the TLP tool as the root user, the preferred method is to create a unique user ID. Use the Solaris Management Console to create the new user and group. For more information about creating users and groups with the Solaris Management Console, see Setting Up User Accounts (Task Map) in System Administration Guide: Basic Administration.

6. Create the TLP data directory and give ownership to the tlp-user.

   # mkdir DataDirectory # chown tlp-user DataDirectory

   The data directory is used by the TLP tool for storing patches and TLP results. Note the location of this directory, as you will need to add it to the tlp.cfg file later.

7. Log in to the server as the tlp-user.

   The remaining steps are performed as the tlp-user.

8. Using a text editor, modify the TLP server conf/tlp.cfg configuration file.

   For more information, see How to Modify the TLP Configuration File.

9. Configure the CGI script to enable file transfers from the TLP client to the server.

   For more information, see How to Install and Configure the CGI Script.

Example 2–1 Installing the TLP Server Software

This example shows a TLP server software installation. For the sake of brevity, the output in this example has been truncated.

root# gzcat SUNWtlp-2.3.tar.gz | tar xf -

root# ls
README              SUNWtlp-2.3         SUNWtlp-2.3.tar.gz  tlp.policy

root# pkgadd -a tlp.policy -d SUNWtlp-2.3

The following packages are available:
  1  SUNWtlp     Traffic Light Patchtool
                 (sparc) 2.3

Select package(s) you wish to process (or 'all' to process
all packages). (default: all) [?,??,q]: y

Processing package instance <SUNWtlp> from /var/tmp/tlp/SUNWtlp-2.3

Traffic Light Patchtool
(sparc) 2.3
============================================================================
Copyright (c) 2001-2003 Sun Microsystems, Inc. All rights reserved.
Protected by copyright and distributed under licenses restricting its use,
copying, distribution and decompilation. Sun, Sun Microsystems, the Sun
.
.
..
Checking for perl >= 5.005_03 ... yes
Checking for update ... no

Please enter installation directory (default: /opt/SUNWtlp) :  [?] 

TLP requires a data directoy for the baselines,
Explorer and generated patch sets. It is recommended to
put this directory in a separate file system.

Please enter a data directory (default: /opt/SUNWtlp/data) : \
[?] /export2/data

Which user:group should be the owner of tlp installation \
(default: root:other)
?  [?] tlpuser:staff

Create link /opt/sun/bin/tlp -> /opt/SUNWtlp/tlp ? (default: y) [y,n,?] 

Create link /opt/sun/bin/cpc -> /opt/SUNWtlp/tlp ? (default: y) [y,n,?] 

The selected base directory </opt/SUNWtlp> must exist before
installation is attempted.

Do you want this directory created now [y,n,?,q] y
Using </opt/SUNWtlp> as the package base directory.
## Processing package information.
## Processing system information.
## Verifying disk space requirements.
## Checking for conflicts with packages already installed.
## Checking for setuid/setgid programs.

This package contains scripts which will be executed with super-user
permission during the process of installing this package.

Do you want to continue with the installation of <SUNWtlp> [y,n,?] y

Installing Traffic Light Patchtool as <SUNWtlp>
## Executing preinstall script.
## Installing part 1 of 1.
/opt/SUNWtlp/CHANGES
/opt/SUNWtlp/README
/opt/SUNWtlp/conf/defaults/Patchcluster_README
/opt/SUNWtlp/conf/defaults/WITHDRAWNPATCHES
/opt/SUNWtlp/conf/defaults/black_list.cfg
/opt/SUNWtlp/conf/defaults/cpc.cfg
/opt/SUNWtlp/conf/defaults/log.cfg
.
.
.
## Executing postinstall script.
Installing .... /opt/SUNWtlp/conf/tlp.cfg
Installing .... /opt/SUNWtlp/conf/cpc.cfg
Installing .... /opt/SUNWtlp/conf/log.cfg
Installing .... /opt/SUNWtlp/conf/WITHDRAWNPATCHES
Installing .... /opt/SUNWtlp/conf/white_list.cfg
Installing .... /opt/SUNWtlp/conf/black_list.cfg
Installing .... /opt/SUNWtlp/conf/non-standard-patchids
Installing .... /opt/SUNWtlp/conf/node_group_definition.cfg
Setting DataDirectory in /opt/SUNWtlp/conf/cpc.cfg to /export2/data
Setting DataDirectory in /opt/SUNWtlp/conf/tlp.cfg to /export2/data
Creating link /opt/SUNWtlp/tlp --> /opt/sun/bin/tlp
Creating link /opt/SUNWtlp/tlp --> /opt/sun/bin/cpc
Setting ownership of /opt/SUNWtlp to tlpuser:staff

Installation of <SUNWtlp> was successful.

How to Modify the TLP Configuration File

The TLP configuration file contains default values, parameters, and configuration information for installing, using, and maintaining the TLP tool. This file also contains general instructions for modifying the file. To complete the TLP installation and setup at your site, you might need to modify this file. This section describes how to make changes to the tlp.cfg file.

Steps

1. To change a default value within the configuration file, use a text editor to edit the file.

2. Replace the default value with the new value and save the file.

   Note that some of the available options within the file are commented out by default. To set one of these parameters, uncomment the specific line within the file and save the file.

   ---

   Note –

   The complete TLP default configuration file, tlp.cfg, is located in the /opt/SUNWtlp/conf directory. Configuration instructions are included in the file. To access the file at this location, you must have installed the TLP software. If you need to restore the original default configuration file, a copy of the original file is always stored in the default subdirectory.

   ---

Example 2–2 Changing the DataDirectory Global Variable

This example shows the global variables portion of the TLP configuration file, where the DataDirectory value is set to the $BaseDirectory/data directory. Note that the variable, $BaseDirectory, is referenced here. To use a different DataDirectory value, simply replace the $BaseDirectory/data directory with a different directory, and save the file.

# You can define you own variables here and refer later to it, e.g if
# you define "DataDirectory  /usr/local/tlp" you can later use it like
# in "SnapshotDirectory $DataDirectory/repository"

DataDirectory $BaseDirectory/data

# Helper-Programs
# Tar /usr/bin/tar
# Uncompress /usr/bin/uncompress 

How to Install and Configure the CGI Script

The Common Gateway Interface (CGI) script is used to transfer the Explorer and PatchPro output from the TLP client to the TLP server, by using the HTTP protocol. The TLP client contacts the web server that is running on the TLP server. The client then transfers the data by using a simple file upload over HTTP. The script writes the uploaded file to a directory that is read by the TLP server software. This procedure describes how to install and configure the CGI script.

Before You Begin

To complete this procedure, make sure you have the following:

• Web server - The web server must be capable of running CGI applications. The tlp_server.pl script is a Perl script. Configure your web server to enable the execution of Perl CGI scripts. If you're using the Apache Web Server go to http://httpd.apache.org/docs/howto/cgi.html for more information.

This steps in this procedure use a configuration for the Apache Web Server. If you are using a different web server, adjust these steps accordingly.

Steps

1. Install the CGI script.

   After you install the TLP software, a cgi subdirectory is placed in the installation BaseDirectory. By default, the tlp_server.pl script is located in the /opt/SUNWtlp/cgi directory.

   You can install the script in one of the following ways:

   • Add a ScriptAlias to the httpd.conf file.

     This method is the preferred method.

     1. Locate the httpd.conf file. Use a text editor to add the following line:

        ScriptAlias /tlp-cgi/ /opt/SUNWtlp/cgi/

        where /opt/SUNWtlp/cgi/ is the default installation directory. If you did not install the TLP software in this directory, replace this information with the appropriate installation directory. Adding this line to the file maps all HTTP requests that are directed to http://server/tlp-cgi/ to the /opt/SUNWtlp/cgi/ directory.

     2. To ensure that the modifications are correct, run a configtest before restarting the web server.

     3. After you edit the httpd.conf file, restart the web server.

   • Copy the tlp_server.pl script and the tlp_server.cfg file to the cgi-bin directory.

     ---

     Caution –

     If you use this method, there is a risk that during a TLP update, the tlp_server.pl script might not be updated in another directory.

     ---

     If you are unable to modify the httpd.conf file, copy the tlp_server.pl script and the tlp_server.cfg file to a directory that contains a set of the ExecCGI configuration directives. By default, this is usually the cgi-bin directory. Lastly, copy the tlp_server.pl script and the tlp_server.cfg file to a directory where you can run CGI applications.

2. Modify the tlp_server.cfg file.

   For more information, see Example 2–3.

Example 2–3 Modifying the tlp_server.cfg file.

All configuration data is stored in the tlp_server.cfg file. The CGI script writes all files that are received from the clients to the TargetDirectory directory. Make sure that your web server has the sufficient write permissions for this directory. In addition, make sure that the TLP tool has sufficient read and write permissions to and from this directory. This example shows the portion of the tlp_server.cfg file where this variable is defined.

tlp_server.cfg
# TargetDirectory is the directory where the TLP
# server will store all files received by the clients

TargetDirectory = /opt/SUNWtlp/data/explorer

How to Upgrade the TLP Server Software

This procedure describes how to upgrade to the latest version of the TLP server software. In this procedure, the current working directory is the TLP installation directory, /opt/SUNWtlp.

Before You Begin

Before you begin the installation, ensure that you have the following:

• A sufficient amount of disk space is available on the system.

  For each set of baselines that you use, you will need 3 to 4 Gbytes of disk space. In addition, you need to reserve disk space for each client system. The amount of space that is required for each client system can vary between 1 to 5 Mbytes. In rare instances, the amount of disk space that is required could reach 200 Mbytes. Because the created patch sets are built from symbolic links that point to the patch repository, each patch set only requires about 100 Kbytes of disk space.

• Perl, version 5.005_03, or later installed on the system.

  Perl, version 5.005_3 or later, is bundled with all Solaris OS versions, beginning with the Solaris 7 OS.

• An HTTP server installed on the system.

  The Apache HTTP Web Server is bundled with the Solaris Operating System.

• The latest TLP server software, which has been downloaded from the TLP server.

• Access to the Sun patch baselines, for example, an EIS-CD.

Steps

1. Log in as superuser to the system where you will install the TLP server software.

2. Extract the archive SUNWtlp-2.3.tar.gz to the /tmp directory.

   # gzcat SUNWtlp-2.3.tar.gz | tar xvf -

3. Check the README file in /opt/SUNWtlp/README for the latest updates.

4. Install the TLP software package.

   # pkgadd -a tlp.policy -d SUNWtlp-2.3

   By default, the TLP software is installed in the /opt/SUNWtlp directory. See How to Add Software Packages (pkgadd) in System Administration Guide: Basic Administration for information on how to modify the installation directory.

5. Log in to the server as tlp-user.

   The remaining steps are performed as the tlp-user.

6. Save the old tlp.cfg file.

   $ cd /opt/SUNWtlp/conf $ mv tlp.cfg tlp.cfg.bak

7. Copy the default 2.3 tlp.cfg file to /opt/SUNWtlp/conf/tlp.cfg.

   $ cp default/tlp.cfg

8. Modify the tlp.cfg file for your site's setup.

   See How to Modify the TLP Configuration Filefor task-related information.

Next Steps

After you complete the TLP server software upgrade and configure the tlp.cfg file, you will need to perform the following tasks:

• Update the TLP configuration, the snapshots, and the metafiles.

  For instructions, see How to Update the TLP Configuration, Snapshots and Metafiles After Upgrading the TLP Software.

• Configure the TLP web server CGI script to enable file transfers from the TLP client.

  Although the method previously used for collecting client information still works with the TLP 2.3 software, you might want to consider using the new TLP client to perform this function. For instructions, see How to Install and Configure the CGI Script.

How to Update the TLP Configuration, Snapshots and Metafiles After Upgrading the TLP Software

This procedure describes how to update the TLP configuration and rebuild the existing snapshots after you have upgraded to the TLP 2.3 software. Perform the steps in this procedure as the tlp-user.

Steps

1. Update the TLP metafiles.

   $ tlp download metafiles

2. Rebuild the snapshots.

   This step is required in order to update the snapshot format to the latest TLP release.

   $ tlp snapshot rebuild

3. Fix any inconsistencies between the patchdiag.xref file and the snapshots.

   $ tlp snapshot fix

4. Check and replace any withdrawn patches in the TLP repository.

   $ tlp repo check

   For more information about working the WITHDRAWN patches, see How to Update the WITHDRAWN Patches List.

Installing the TLP Client Software

This section describes how to install the TLP client software. The TLP client is intended for use with the TLP server.

How to Install the TLP Client Software

This procedures assumes that the current working directory is the TLP client installation directory, /opt/SUNWtlpc.

Before You Begin

Before you begin the installation, ensure that you have the following:

• A sufficient amount of disk space.

  To install the TLP client software, you need approximately 10 Mbytes of disk space.

• Perl, version 5.005_03, or later installed on the system.

  Perl, version 5.005_3 or later, is bundled with all Solaris OS versions, beginning with the Solaris 7 OS.

• The latest TLP client software, which has been downloaded from the TLP server.

• The TLP server software installed and running.

• PatchPro, version 2.2 installed.

  The TLP client has been tested with this version of PatchPro. This version of PatchPro is bundled with the Solaris 10 OS. To install PatchPro 2.2, use the SUNWppro package.

Steps

1. Log in as superuser to the system where you will install the TLP client software.

2. Extract the archive, SUNWtlpc-1.0.tar.gz, to the /tmp directory.

   # gzcat SUNWtlpc-1.0.tar.gz | tar xvf -

3. Check the README file that is included for the latest updates.

4. Install the TLP client software package.

   # pkgadd -a tlp.policy -d SUNWtlpc-1.0

   By default, the TLP client software is installed in the /opt/SUNWtlpc directory. For information about modifying the installation directory, see How to Add Software Packages (pkgadd) in System Administration Guide: Basic Administration.

5. Using a text editor, modify the TLP client conf/tlpc.cfg configuration file. Set the TlpServerUrl value to the TLP server CGI script URL.

Next Steps

After you complete the TLP client software installation, you are ready to run the TLP client. See The TLP Client Run Process for more information.

The TLP Client Run Process

The TLP client is used in conjunction with the TLP server. The TLP client can run without any user interaction, after you have properly configured it. When you run the tlpc main command, the TLP client performs the following tasks:

• Gathers system information

• Optionally runs an analyzer on the client

• Stores system information and the output of the system analysis engine

• Transfers data to the TLP server to enable patch set creation for each client system

You can manually run the TLP client. Or, if you choose to, you can set up a cron job to run the TLP client at regularly scheduled intervals. For more information about setting up cron jobs, see Chapter 15, Scheduling System Tasks (Tasks), in System Administration Guide: Advanced Administration. Example 2–4 shows a typical TLP client run.

Example 2–4 Running the TLP Client

This example shows a typical TLP client run. Note that to run PatchPro, you must be superuser or assume an equivalent role.

# ./tlpc main
TLP - Client ------------
		* Tlp::Collector::TlpExplorer
		* Tlp::Analyzer::PatchPro
		+ Starting PatchPro
		+ Parsing PatchPro Output
		* Tlp::Transfer::HTTP
		+ Connecting to http://your-tlp-server/tlp-cgi/tlp_server.pl
		+ Uploading data
100% [===========================================] 

Installing TLP Baselines

The TLP tool uses patch baselines to enable the standardized patching of multiple systems in large data centers. Within the TLP tool, baselines are sometimes referred to as snapshots. Baselines are well-tested. Therefore, the risk of change is minimized. In TLP, a baseline is defined by the date that it was created. The baseline for a given date includes a list of patches that belong to that patch baseline. Baselines are consistent and complete. Baselines do not have any external dependencies. When installing a baseline, the TLP tool checks for any external dependencies and resolves them.

Baseline installation consists of two primary phases:

• Load phase

  During the load phase, the Sun baseline is copied to the local repository to create the snapshot. You then load the snapshot.

• Update phase

  The command that you run during the update phase assigns a name and a color code to the snapshot. Each phase has a creation date that is assigned to it. By default, the TLP tool assigns the date of the creation of the EIS-CD to the snapshot.

In the following procedure you use the tlp repo command during the update phase. This command reads the repo section in the tlp.cfg file to determine the name and starting date of the phase. TLP uses an aging mechanism that enables you to install snapshots before they are assigned to a phase. By default, the first phase, GREEN, is defined to be at least 30 days old. The tlp repo phase update command determines the age of the snapshot and assigns an appropriate name and color code to it. If the baseline that was just copied to the system is not 30 days old, modify the conf/tlp.cfg file to a shorter time period. See How to Modify the TLP Configuration File for more information.

TLP is capable of maintaining multiple phases in parallel. This functionality enables you to track the history of each system's status. TLP automatically assigns a color status to systems in the data center, according to the phase in which each of the systems was patched. For more information, see TLP Reporting.

How to Install TLP Baselines

This procedure describes how to install a TLP patch baseline on the server. This procedure assumes that the current working directory is the TLP installation directory, /opt/SUNWtlp.

Before You Begin

Before you begin the baseline installation, ensure that the following activities have taken place:

• The TLP server software has been installed.

• The selected baseline (EIS-CD) is available.

  ---

  Note –

  The baselines that are used in this procedure are the EIS-CDs. The baselines that used are subject to change.

  ---

Steps

1. To create a snapshot in the repository from an EIS-CD, log in to the system as the tlp-user.

2. Copy the EIS-CD to the local repository.

   $ tlp snapshot load

   TLP uses the creation date of the EIS-CD as the creation date of the snapshot. If you do not have the EIS-CD in the /cdrom/cdrom0 location, you can provide another location by using the --source command-line option.

   $ tlp snapshot load --source=/mnt/cdrom0

3. Repeat the previous step for each EIS-CD from the set of EIS-CDs.

   ---

   Note –

   An alternative to using the EIS-CD as a snapshot is to create a custom snapshot by using this method:

   $ tlp snapshot create --patch-list patch-list --date \ YYYY-MM-DD [--name name]

   Or, you can use the following method:

   $ tlp snapshot current

   This method always uses the most current patches from the SunSolve web site.

   ---

4. Run the tlp repo command for the update phase.

   $ tlp repo [--date date] phase update

5. Verify and list the available phases by typing:

   $ tlp repo list

   All of the installed snapshots and their associated names (phases) are listed.

Example 2–5 Installing the TLP Baselines

This example shows how to install a TLP baseline.

./tlp snapshot load

 Copying EIS-CD 1 from 2003-05-27
 --------------------------------

    + Should EIS-CD 1 be copied (yes/no) ? [yes] : yes
    + Copying patches /export/home/user1/eis1/ --> 
                   data/repository/2003-05-27/patch
 100% [===========================================]
    + Creating CONTENT
 100% [===========================================]
    + Installing tools
    + Copying patch information

 ./tlp repo phases update

 Updating phases
 ---------------

 Reference date: 2003-08-12
 Creating phase link GREEN --> 2003-05-27

./tlp repo list

 Repository Snapshots
 --------------------

 Phases                      Id             Nr. Patches
 =======================================================
 GREEN                       2003-05-27             817

Using the TLP Tool (Task Map)

This task map includes all of the tasks that are required to use the TLP tool.

Creating and Installing the TLP Patch Sets

This section describes how to use the TLP tool. The main purpose of the TLP tool is to create patch sets for client systems. TLP creates one individual patch set, per client system. These patch sets are stored in directories, along with install and backout scripts, and other helpful files. Patch set installation is a separate task that is performed after the patch sets are created.

How to Create Individual TLP Patch Sets

This procedure describes how to use tlp commands to create individual patch sets.

This procedure describes how to create patch sets on demand. You might choose to set up a cron job to run this task at regularly scheduled intervals. For the best performance, value, and ease of use, TLP is configured to run weekly. Scheduling frequent TLP runs enables the tool to capture system changes and adjust patch set creation accordingly. For more information on setting up and running cron jobs, see Chapter 15, Scheduling System Tasks (Tasks), in System Administration Guide: Advanced Administration. Ensure that the TLP client also provides system information according to this schedule. See The TLP Client Run Process.

Before You Begin

Before beginning this procedure, you must have previously done the following:

• Installed the TLP server and client software.

  See How to Install the TLP Server Software and How to Install the TLP Client Softwarefor more information.

• Installed at least one TLP baseline.

  See Installing TLP Baselines for more information.

Steps

1. Log in to the system as the tlp-user.

2. Create a patch set for all client systems.

   $ tlp main

   The tlp main command creates patch sets for all the client systems where the Explorer dumps exist.

3. Locate the patch sets that were created for the phase, GREEN, in the directory, data/target/GREEN.

   You will now find the patch sets that were created for the phase, GREEN, in the data/target/GREEN directory. In this directory, a separate subdirectory for each client system was also created. You can adjust the allowed age of the TLP client data by modifying the explorer module in the tlp.cfg file, as shown in the following example:

   # =================================================================== # System Info Collector which is responsible for collecting a nodes # sytem information <module explorer> # Fetches Explorer information from a directory Class Tlp::Collector::explorer # This directory contains explorer info Directory $DataDirectory/explorer # Optional: List with node names to examine. Each line # must be a name of a system. If this list is not provided # all Explorer dumps in the provided directory are examined # NodeList $DataDirectory/explorer/nodes.lst # Time after which an Explorer dump is regarded as obsolete. # Unit can be "days", "weeks" or "months" # Default value are "4 Weeks" # MaxAge 4 weeks </module>

   The TLP tool then runs an external analyzer to determine which patches are missing on a given system.

   For TLP 2.3, PatchPro is the analyzer that is used. You can choose to use another analyzer by modifying the analyzer section in the tlp.cfg file.

   Usually, all of the required patches have been installed on the TLP system with the snapshots. However, if the patches are not available, TLP attempts to download them.

4. (Optional) To enable TLP to download patches from an external location, configure the Loader module in the tlp.cfg file.

   There are three Loader modules that you can use:

   • sunsolve

     Configure the sunsolve module to download patches directly from the SunSolve web site. Note that the user and proxy data must be entered correctly in the SunSolve module for TLP to work correctly.

   • swanloader

     Configure the swanloader module to download patches directly through a proxy server. Note that you must have an Internet connection to use this configuration value.

   • dirloader

     If you do not have access to the Internet, use the DirLoader module to load patches from a separate directory. Store missing patches in a directory that is accessible to TLP. Configure the DirLoader to find that directory.

   To use a particular Loader module, uncomment the line for that module in the tlp.cfg file, as shown in the following example:

   # Please be sure, that the sunsolve login and proxy parameters are set # properly.if you want to enable loading of missing patches from # SunSolve. Uncomment the Loader, you want to use. # Loader sunsolve # Loader swanloader # Loader dirloader . . .

   TLP then uses the DirProducer module to store the created patch sets, along with any helper files. Adjust the values in the tlp.cfg file, as appropriate.

5. Check the results

   You will now find the created patch sets for the phase, GREEN, in the data/target/GREEN directory, where for each client system a separate subdirectory has been created. For information on how to install the patch sets on client systems, see How to Install a TLP Patch Set.

6. To view the results and plan system updates across the data center, read the HTML reports that were automatically created below the data/target/reports/ directory.

   For information on how to interpret the HTML reports, see TLP Reporting.

   ---

   Note –

   In some cases, the TLP tool creates results that might not suit your needs. These results occur when the client systems run applications that require certain patch levels, or if third-party hardware is installed on the system. TLP cannot analyze this type of information. In these instances, you can direct the tool to add or remove patches from the patch sets. To do so, modify the results by using the whitelist and blacklist files. For more information on how to modify TLP results by using whitelists and blacklists, see How to Customize Whitelists and Blacklists.

   ---

Example 2–6 Creating a Patch Set

This example shows the output for a single system. The TLP tool completes this process on all client systems for which it finds up-to-date system information.

$ ./tlp main

  TLP - Creating Patch Set
  ------------------------
  
  --- GREEN:2003-05-27:edkclu0  ------------------------------
     * Tlp::Analyzer::PatchPro
       >........>.>>>.>.....>..>.>>...>>>>.>.>...>.>>
     * Tlp::Resolver::PatchDiag
     + Parsing cross-reference
  100% [===========================================]
     * Tlp::Producer::DirProducer (data/target/2003-05-27/edkclu0)
     + Checking patches
       .-.............-......-...
     + 108528-20 ... loading
     + Checking SunSolve CHECKSUM
     + Reloading CHECKSUMS: old size = 802973
     + Loading CHECKSUMS (803750 bytes)
  100% [===========================================]
     * Tlp::Loader::SunSolve
     + Loading 108528-23.zip (27076411 bytes)
  100% [===========================================]
     + Extracting ...
     + 108727-24 ... loading
     * Tlp::Loader::SunSolve
     + Loading 108727-25.zip (375168 bytes)
  100% [===========================================]
     + Extracting ...
     + 108974-28 ... loading
     * Tlp::Loader::SunSolve
     + Loading 108974-33.zip (615134 bytes)
  100% [===========================================]
     + Extracting ...
     + Copying patches
  100% [===========================================]
     + Creating support files

How to Install a TLP Patch Set

TLP creates patch sets for each client system. The tool provides a variety of helper files for easy installation of the patch sets. This task describes how to install the patch sets that were created by the TLP tool. Repeat this procedure for each client system within your data center. If you choose to, you can first install the patch set on a test system to ensure that no problems are encountered.

The TLP tool does not install or distribute patch sets. The TLP tool performs the task of patch set creation. Patch set installation occurs after the patch sets have been created.

Before You Begin

Before you begin the installation:

• Ensure that you have a current backup of the client system by using your data center's backup mechanism.

• Ensure that the TLP patch sets are accessible to the system.

  Depending on the data center environment, you can do one of the following:

  • Make the TLP server directories available to the clients by NFS.

  • Copy the contents to the client system.

Steps

1. Log in to the system as superuser and reboot the system to single-user mode

   # boot -s

2. Change to the directory where the patch sets are stored. See How to Create Individual TLP Patch Sets.

   # cd patch-set-directory

3. Carefully check the Special_Install_Instructions.txt file.

   # more Special_Install_Instructions.txt

4. Install the patches.

   # ./install_all_patches [-R /RootDir]

   You can use the -R option if you want to use an alternate boot environment, for example, Solaris Live Upgrade.

   ---

   Note –

   Use the following command if you want to remove the patches that you installed and return the system to its previous state.

   # ./backout_all_patches [-R /RootDir]

   ---

5. Install firmware and OpenBoot PROM patches.

   Firmware and OpenBoot PROM patches require manual installation. If TLP detects any missing firmware or OpenBoot PROM patches, it stores the patches in the firmware+flashprom subdirectory. (If this directory does not exist, it is an indication that no firmware or OpenBoot PROM patches were missing from the patch set.) To install these patches, carefully follow the instructions that are located in the README files.

6. Reboot the system.

Example 2–7 Installing a Patch Set

This example shows a patch set installation. For the sake of brevity, this example has been truncated.

root@system1# pwd
.../Patchcluster/Server/system1
root@system1# ls
112807-13                         README                            install_all_patches
113244-06                         Special_Install_Instructions.txt  pack_patches
113318-14                         Synopsis.txt                      patch_order
113798-02                         SystemCheck.txt
117171-17                         backout_all_patches
root@system1# ./install_all_patches -R /ABE
Patch cluster install script for PMGT: TLP-Set for
node system11, phase GREEN, snapshot 2005-01-25

!!! Please read first this Special Install Instructions !!!

[Please hit return to continue]
#################################################################
SECTION: PATCHSET INFOS
#################################################################

Host       : system11
OS-Version : SunOS 5.9
tlp			:	tlp.809be70b.system1-2005.03.05.01.03

#################################################################
SECTION: SPECIAL INSTALL INSTRUCTIONS:
#################################################################


112807-13: CDE 1.5: dtlogin patch
=========
NOTE 1:
If the system that this patch is being applied to is a SunRay server, then
a reboot is required after the patch has been installed.
 
NOTE 2:
To get the fix for any bug which affects /usr/dt/bin/dtlogin, all dtlogin
processes including the parent dtlogin process must be stopped and restarted.
On a SunRay server, the recommended procedure is to reboot the server.
For all other workstations or servers, execute the following command as root:
 
/usr/dt/config/dtlogin.rc stop
sleep 60
/usr/dt/config/dtlogin.rc start
.
.
.
Are you ready to continue with install? [y/n]: y
Determining if sufficient save space exists...
Sufficient save space exists, continuing...
Installing patches located in /tlp/system1/Patchcluster/Server/system1
Using patch_order file for patch installation sequence
Installing 112807-13...
Installing 113244-06...
Installing 113318-14...
Installing 113798-02...
Installing 117171-17...

For more installation messages refer to the installation logfile:
  /ABE/var/sadm/install_data/PMGT:_TLP-Set_for_node_system1,_phase_GREEN,
_snapshot_2005-01-25_log

Use '/usr/bin/showrev -p' or '/usr/sbin/patchadd -p' to verify
installed patch-ids.
Refer to individual patch README files for more patch detail.
Rebooting the system is usually necessary after installation.

!!! Please read the logfile for any required action before rebooting !!!

[Please hit return to continue]


*** Install PMGT: TLP-Set for node system1, 
phase GREEN, snapshot 2005-01-25 begins Mar  7 2005 22:10:46 ***
*** PATCHDIR = /tlp/system1/Patchcluster/Server/system1 ***
*** SNAPSHOT = EIS-CD  ***

Installing 112807-13...

Checking installed patches...
Verifying sufficient filesystem capacity (dry run method)...
Installing patch packages...

Patch number 112807-13 has been successfully installed.
See /ABE/var/sadm/patch/112807-13/log for details

Patch packages installed:
  SUNWdtdte
.
.
.
Patch packages installed:
  FJSVhea
  SUNWcar
  SUNWcarx
  SUNWcpc
  SUNWcpcx
  SUNWcsr
  SUNWcsu
  SUNWcsxu
  SUNWhea



*** Install PMGT: TLP-Set for node system1, phase GREEN,
snapshot 2005-01-25 finished at Mar  7 2005 22:20:22 ***


Run CST app_event

DONE
root@system1#

Customizing the TLP Tool

This section contains information on customizing the TLP tool. Included in this section are the procedures for modifying whitelists and blacklists. Information on working with withdrawn patches is also included in this section.

Customizing Whitelists and Blacklists

TLP patch sets are created through the use of analyzers. These analyzers use Sun knowledge and best practices to locate missing patches on a system. However, these analyzers do not analyze third-party applications or hardware. These components might conflict with certain patches, or patch revisions, for a given system. For known conflicts, such as those from the component, from the application vendor, or from previous experience, TLP provides a mechanism for adding or removing these patches from the specific patch sets. This process is accomplished through the use of whitelists and blacklists. A whitelist is a list of all of the patches to be included in the patch set. A blacklist is a list of all of the patches to be excluded from the patch set.

How to Customize Whitelists and Blacklists

This task describes how to configure and modify TLP whitelists and blacklists. Patches in the whitelist file are added to patch sets. Patches in the blacklist file are removed from the patch sets. This procedure shows how to modify the whitelist file. The same steps are applicable when modifying a blacklist file.

Steps

1. Log in to the TLP server as the tlp-user.

2. Using a text editor, open the whitelist file for editing.

   The location of the whitelist and blacklist files is configured in the patchdiag section of the tlp.cfg file. The default locations for these lists are:

   • /opt/SUNWtlp/conf/whitelist.cfg

   • /opt/SUNWtlp/conf/blacklist.cfg

3. Add patches to the list.

   The whitelist and blacklist files include many examples. See TLP Whitelists and Blacklists for more details.

   1. Copy the most appropriate example. Remove the hash mark (#) from the beginning of the line.

   2. Adjust the values accordingly.

   You can add patches for all of the systems in the data center or for a subset of systems. Subsets are selected by keys, which are known by using the uname command. The following information about the operating system is provided:

   • Name

   • Version

   • Architecture

   • System type

4. Save the changes.

   The changes take effect when the next patch sets is created. See How to Create Individual TLP Patch Sets.

Example 2–8 Configuring a Whitelist

The following example shows a whitelist configuration.

<Module patchdiag>
Class Tlp::Resolver::PatchDiag

       # List of patches to be ignored
       BlackList $BaseDirectory/conf/patches.black

       # Default white list of patches which should be always 
       # installed:
       WhiteList $BaseDirectory/conf/patches.white

       # Additional list of patches which should be added for sure
       # WhiteList ./patches.white
</Module>

For an example of a blacklist configuration, see Example 3–1.

Working With Withdrawn Patches

Patches fix problems and install new functionality. However, some patches can create new problems. When a patch creates a problem, Sun withdraws the patch from the SunSolve web site to prevent you from downloading it. Because TLP works with baselines that are installed on the TLP server, Sun cannot withdraw these patches from the TLP server. Therefore, the TLP tool uses a WITHDRAWN patches list to update this information.

How to Update the WITHDRAWN Patches List

The following task describes how to configure the TLP tool to update information about withdrawn patches.

Before You Begin

You must have installed the TLP software to perform this task.

Steps

1. Log in to the system as the tlp-user.

2. Download the TLP metafiles.

   $ tlp download metafiles

   The TLP metafiles contain information about withdrawn patches. Running this command updates the WITHDRAWNPATCHES file with the latest information about withdrawn patches.

   To enable daily updates, add the tlp download metafiles command to the tlp-user crontab file.

3. Ensure that the SunSolve login and proxy parameters are set properly in the tlp.cfg file.

4. Ensure that the sunsolve Loader module is defined in the tlp.cfg file. To set this value, uncomment the line within the configuration file.

5. After you recreate the patch sets, withdrawn patches are removed from all of the patch sets. See How to Create Individual TLP Patch Sets for more information about patch set creation.

Example 2–9 Downloading the TLP Metafiles

This example shows the process for downloading the TLP metafiles.

$ /tlp download metafiles
   + updating TLP Metafiles
   + Loading tlp_metafiles.xml (unknown filesize)
   + Loading tlp_metafiles.tar.gz (586145 bytes)
100% [===========================================]
tar: Read 7168 bytes from -

TLP Reporting

This section describes the reports that are automatically generated by the TLP tool whenever a patch set is created. TLP reports help you review information about the patch sets that were created. The main purpose of the report is to provide an overview about system status, thus enabling you to prioritize patching needs. You can use these reports to plan the rollout of patch sets in your data center.

There are two kinds of reports that are automatically generated when patch sets are created:

• HTML report (Dashboard)

• ASCII text report

This guide does not describe usage of the ASCII text report. Although the text report provides output that is the same as the HTML report, the HTML report is easier to interpret. You can adjust the TLP reports by using report templates. Adjusting report templates is beyond the scope of this guide.

How to Access the HTML Report (Dashboard)

This task describes how access the HTML report that is automatically generated by the TLP tool whenever patch sets are created.

Before You Begin

This procedures assumes that you have installed the TLP server and client software, and that you have successfully run the tlp main command at least once.

Steps

1. Log in to the system.

2. Launch a web browser.

3. In the location field, type:

   file:///target-directory/index.html

   where target-directory is the directory that stores the TLP results, as is specified in the report section of the tlp.cfg file.

   In this section you can also assign color codes to the phases. The defaults for the GREEN and AMBER phases are already predefined. The results that are displayed should look similar to Figure 2–1.

   Figure 2–1 TLP HTML Report (Dashboard)

   
   

   See Interpreting the TLP HTML Report (Dashboard) for more information on how to interpret the HTML report.

Interpreting the TLP HTML Report (Dashboard)

The TLP HTML report presents an overview of all of the systems in the data center that are controlled by TLP. Each row in the report represents one client system. Columns provide specific status details for each system. You can sort systems by clicking the column headers. See Table 2–1 for a more detailed explanation of the contents of a TLP HTML report.

For example, the host, ar-cluster, is missing 35 patches from the GREEN phase. In this example, a second phase, AMBER, is defined. In addition, a snapshot dated, 2004-06-29, was assigned within the tlp.cfg file. TLP enables you to define and install as many snapshots (baselines) as you like. To do so, modify the tlp.cfg file. Within the file, assign names and colors to each phase.

Each row represents one client system and is displayed in the color of the latest phase for which a system is compliant. For example, a line shows up in green if the patches of the GREEN phase were installed on this system. Host, ar-cluster, has an AMBER status because the AMBER patch set was installed, but the GREEN patch set was not installed.

The dashboard assists you in determining each system's status, in relationship to the baselines. The color status, and the number of missing patches, assist you in prioritizing and planning for patch set creation within the data center.

You should continue to read Sun^SMAlert information, even when using the TLP tool to generate patch sets within a data center. Although a system has the latest baseline installed, new critical patches might have been released since the baseline was installed. SunAlert provides timely notifications about critical patches, which can help you determine whether any systems are affected.

To obtain more information about a specific system or its status, click on the number in the patch cell. The report header provides system-specific information. If you click the individual links, you can obtain the following information:

• README – The TLP README file contains information about the created patch sets, additional helper files, and brief instructions on how to install the patch set.

• Special installation instructions –For your convenience, the TLP tool provides a summary of the special installation instructions from all patch README files in this patch set. Read this information carefully before installing the patch set.

• System check - The output of the analyzers that were used on the specific system. This file helps you understand why a specific patch was selected. Some analyzers also provide additional recommendations for making systems more reliable.

Patches to be installed in Phase GREEN

The bottom of the page provides a list of all the patches that were selected for this patch set. Click the patch ID to get to the patch README file for more information.