Chapter 3 Sun Update Connection - Automated Baseline Management Service 1.0 (Reference)

This chapter includes reference information on the TLP 2.3 tool that is used by Sun Update Connection - ABMS 1.0 service offering. The following information is included in this chapter:

• TLP Directories and Files

• TLP Roles and Modules

• TLP Configuration Information

• TLP Whitelists and Blacklists

TLP Directories and Files

The global variable, BaseDirectory, is implicitly set to the TLP installation directory. This variable can be overridden. Note that all relative paths that are given are relative to the current working directory. The BaseDirectory location is /usr/local/tlp. You can define you own variables and refer these variables later. For example, if you define the DataDirectory in /usr/local/tlp, you can later use this directory as the SnapshotDirectory directory, $DataDirectory/repository.

Table 3–1 lists several key TLP directories and their contents.

For more detailed information on these directories, see the default configuration file. The complete TLP configuration file is located in the /opt/SUNWtlp/conf/default/tlp.cfg directory. To access the file, you must have installed the TLP software.

TLP Roles and Modules

This section contains information about TLP roles and modules. There are eight roles that TLP uses. Some of the roles are optional. Other roles are mandatory. For certain roles, more than one module can be used. Table 3–2 describes these roles, and whether they are optional, mandatory, or used for multiple purposes.

How the TLP Tool Uses Roles

The input parameters for the patch set script are the systems for which the patch sets are created, and the ID of the patch, Tlp::Role::Snapshot, from which the patches and analysis tools are fetched. A Tlp::Role::Snapshot is characterized by a date. Multiple snapshots are stored in a single Tlp::Role::repository. For each system, a patch set is created, according to the following scheme:

1. With assistance from Tlp::Role::Collector, the system data for the current system is collected.

   In general, this is the Explorer data, but it can be any data, depending on the module that plays this role.

2. The Tlp::Role::Snapshot is then fetched from the Tlp::Role::Repository.

3. This snapshot, as well as the system data, are handed over to one or more analyzers, Tlp::Role::Analyzer. The analyzer then compiles a list of patches that are missing on the given system.

4. The list of missing patches is passed to the Tlp::Role::Resolver. Patch dependencies are resolved and whitelist and blacklist patch information is applied to the patch set that is created.

5. The complete list of patches is forwarded to Tlp::Role::Producer. This role creates the patch set and all supporting files, such as the README files and the installation scripts.

6. Information about the entire process is collected by Tlp::Role::Report, which processes the information to create the HTML and ASCII text reports.

TLP Server Modules

This section describes the modules that are used by the TLP server. For each role, at least one standard module is provided. Each module is associated with a Class and has a name as a shortcut. Besides playing its role, a module might provide extra commands that are accessible through the module's name from the command line.

In the following list, the TLP server modules are described in detail:

Tlp::Respository::DirRepository(repo)

This implementation of the Tlp::Role::Repository role is used to store the contained Snapshot within a directory in the file system. This module also provides commands for phase handling, such as create, update, and delete. The module checks for withdrawn patches within all snapshots and performs snapshot handling, such listing or deleting snapshots.

Tlp::Snapshot::Snapshot (snapshot)

The snapshot module has replaced the eis-cd module, beginning with TLP 2.2. The snapshot module plays the role of a Tlp::Role::Snapshot, which can be based on one of the following:

• A set of EIS-CDs

• A simple file containing a list of patches

• A patchdiag.xref file

Beside it's role of obtaining patches and analysis tools, this module has commands for copying a set of EIS-CDs to the file system. These commands verify the internal consistency of a snapshot.

Tlp::Loader::SunSolve (sunsolve)

The Tlp::Role::Loader module is used to load missing patches from the SunSolve web site. You can also use this module in stand-alone mode for easy downloading of patches.

Tlp::Loader::Download (download)

The Tlp::Role::Loader module is intended for CLI usage only. The module's main purpose is to provide a simple interface for the user to update the TLP metafiles and the non-standard-patchids. This process is completed by running the command, tlp download metafiles.

---

Note –

This module cannot be used as the only configured Tlp::Role::Loader, as it is just an interface for all the other configured Tlp::Role::Loader modules. To determine whether TLP is able to load missing patches, run the command, tlp download patch 111111. TLP will then try to download the patch ID 111111, with the latest available revision.

---

Tlp::Collector::Explorer (explorer)

The explorer module is Tlp::Role::Collector. This module fetches system information in the form of Explorer dumps that are stored in the file system. In addition, this module provides commands for the maintenance of the Explorer dumps.

Tlp::Analyzer::Checkup (checkup)

The checkup module, Tlp::Role::Analyzer, uses checkup patch analyzing tool. This analyzing tool is now obsolete.

Tlp::Analyzer::SunCheckup (suncheckup)

The Tlp::Role::Analyzer module uses the Sun Checkup patch analyzing tool by default.

Tlp::Analyzer::Withdrawn (withdrawn)

The Tlp::Role::Analyzer module does not use a patch analyzing tool. This module detects installed withdrawn patches on the system and puts the replacement patch, if available, into the patch set.

Tlp::Analyzer::Explominer (explominer)

The explominer is a Tlp::Role::Analyzer module that uses Explominer for patch analysis.

Tlp::Analyzer::External

With the Tlp::Role::Analyzer module, it is possible to call an arbitrary external program to obtain the list of applicable patches for a given system.

Tlp::Resolver::PatchDiag (patchdiag)

The Tlp::Role::Resolver module uses the patchdiag.xref file to resolve patch dependencies and obsolete patches. As an extra command, this module provides a consistency check for a given patchdiag.xref file.

Tlp::Producer::DirProducer (dir-producer)

The dir-producer module produces a complete patch set, according to its role as Tlp::Role::Producer. As an extra command, this module can create a patch set base within a patch category that is independent from a specific system.

Tlp::Report::TextReport (text-report)

The Tlp::Role::Report module creates a text report of the patch set creation. This report can also be sent by email.

Tlp::Report::HtmlReport (html-report)

The Tlp::Role::Report module shows the result of the patch set creation as an HTML document.

TLP Client Modules

This section describes the modules that are used by the TLP client. For each role, at least one standard module is provided. Each module is associated with a Class and has a name as a shortcut. Besides playing its role, a module might provide extra commands that are accessible through the module's name from the command-line.

The following list describes the TLP client modules in detail:

Tlp::Analyzer::PatchPro (patchpro)

This implementation of the TlpClient::Role::Analyzer role is used to run the PatchPro analyzer and store the output in a text file. This text file contains the PatchPro suggested patches. The output file is transferred to the TLP server for further processing and patch set creation, by using the TlpClient::Role::Transfer role.

TlpClient::Collector::TlpExplorer (tlpexplorer)

The tlpexplorer module plays the role of a TlpClient::Role::Collector. This role is used to gather system information that is required for the TLP server.

---

Note –

The TlpExplorer archive that is created is not suitable for other analyzers. You must use the PatchPro analyzer if you use the TlpExplorer module.

---

TlpClient::Collector::Explorer (explorer)

The explorer module plays the role of a TlpClient::Role::Collector. This role used to gather system information that is required for the TLP server and analyzers that are running on the TLP server. This module calls the SUNWexplo binary. By using this Collector, you do not need to run PatchPro on your client, as all of the analysis is done on the server.

TlpClient::Transfer::HTTP (http)

The TlpClient::Role::Transfer module is used to transfer information from the TLP client to the server by using the HTTP protocol.

The script for the creation of patch sets refers only to roles. Hence, the TLP client is flexible to changes in its environment. The following output shows a portion of the TLP client configuration file. In this example, you can see the association between roles and modules.

<Module patchpro>
Class  TlpClient::Analyzer::PatchPro  # Perl Module to use
       ....                           # Module specific config
</Module>

Analyzer patchpro                     # Associate Module with Role

Note that the Analyzer role is associated with the patchpro module, which is associated with the class, TlpClient::Analyzer::PatchPro.

TLP Configuration Information

This section provides additional information about the TLP 2.3 default configuration file. The configuration file is divided into three parts:

• Global configuration

• Command-line configuration

• Module-specific configuration

TLP Global Configuration

The following parameters make up the global configuration that is used by the TLP tool.

BaseDirectory

Specifies the default variable that is set to the TLP installation directory. You can refer to this directory in the default configuration file with the $BaseDirectory value. You can override this variable with any other value.

WithdrawnPatches

Specifies the path to a list of withdrawn patches. Because at least two of these roles are involved in bad patch handling, this configuration information is extracted into the global section. This format is explained in the Tlp::Repository::DirRepository description.

tar, uncompress, gzip, Zzip

Specifies the path to helper programs. If not provided, the corresponding programs are looked up in the system path

TargetDirectory, DataDirectory

Specifies file path variables. These variables are referenced directly, but they can also be referenced by other file path variables that are included in the rest of the configuration file. You can define any variable and then reference it later in the configuration file. An example is the $TargetDirectory.

TLP Default Command-Line Options and Arguments

Along with the automatic selection of the default configuration file that is based on the script name, the default command configuration is an effective mechanism for creating convenient TLP shell commands. You can preselect a default command within the configuration file, along with options and arguments. These default parameters are embedded within a command block, as shown in the following example:

<Command>
# The module to use by default. Can be overriden by the command
       # line 
       Module main

       # Option to be set. They should be provided in the form
       # "option value" as one would give it on the command line 
       # without the '--' prefix. 
       # Relative pathes are relative to the current working directory.
<Options>
 snapshot LATEST
   explorer .
   target $TargetDirectory/Server/%n
		</Options>
</Command>

The following configuration variables are used within this block:

Module

Specifies the default module, or command, to use when no command is given from the command line.

<Options> . . . </Options>

Specifies the block that contains default module options for the default command. These options are only used when the default module is also used. Each option is placed on an extra line, with or without arguments.

TLP Module-Specific Configuration

Module-specific configurations are defined in blocks, according to the following scheme:

<Module name>
Class Tlp::Example

        Var1   Value1
        Var2   Value2
</Module>

The previous example shows how to declare the name module. This module is defined in the Tlp::Example Perl module that is within the default configuration file. The configuration variables, Var1 and Var2, are module-specific. These variables are described in detail in TLP Roles and Modules. Finally, the association of a module with a role is done by using the syntax, Role Module1,Module2. Both modules are now associated with role, Role, and are therefore accessible to the patch set script.

Extending Existing TLP Configuration Files

To avoid duplicated code in configuration files, it is possible that one configuration file can extend another configuration file. For example, a configuration named, cpc.cfg, could contain the following line:

Extends tlp.cfg

In this example, cpc.cfg uses the information that is located in tlp.cfg as fallback. This entry is added on a per-module basis. If cpc.cfg defines a module for the class, dir-producer, then no information from the tlp.cfg dir-producer definition is taken. All paths are relative to the $BaseDir/conf configuration directory.

You can switch off a module in the inherited configuration file by providing the appropriate Role directive. For example, the following entry switches off all reports:

Report

The complete TLP configuration file is located in the /opt/SUNWtlp/conf/default/tlp.cfg directory. Configuration instructions are included in the file. Note that you must have installed the TLP software to access the file in this location.

TLP Whitelists and Blacklists

This section describes the whitelist and blacklist configuration files that are referenced in the TLP configuration file. The whitelist and blacklist files are where you designate those patches that are to be included or exclued during patch set creation. The files are located in the following directories:

• $BaseDirectory/conf/black_list.cfg

• $BaseDirectory/conf/white_list.cfg

For task-related information, see TLP Whitelists and Blacklists.

TLP Whitelist File Configuration

With the whitelist configuration, you can specify patches that should always be included in the patch set. In addition, this configuration can override recommendations from the Analyzer module. If you need to select a particular patch for a specific operating system, you can provide a selector in the second column within the whitelist. Lines starting with a hash mark (#) and empty lines are ignored. The known selectors are the keys of the system information, as returned by the Collector module. For more information on the Tlp::Roles::Collector module, see TLP Server Modules. The most crucial selectors are as follows:

name
name of the system

        os, version, arch
        The operation system's name, version and hardware architecture
            (e.g. 'SunOS', '5.8', 'sparc')

        Example:

          # Select this patch (any rev level allowed), but only for Solaris 8 systems.
          111234     os=>"SunOS",version=>"5.8"
  
          # Select this patch for all operating systems
          115634

          # Select this patch only for host 'eclipse'
          187653     name=>"eclipse"

          # Select a specific revision. This one will always be used. 
          197654-23 

          # Use a regexp for name
          168787-15  name=>'/cores|eclipse\d+/'

You can provide more than one whitelist. Multiple whitelists are merged. A whitelist given later in the configuration overrides any previous whitelist entries. Whitelist patches are moved to the beginning of the patch list. If multiple whitelist entries apply, those that are furthest down on the list are moved to the beginning of the patch list. If a whitelist cannot be found, it is ignored.

TLP Blacklist File Configuration

The blacklist contains those patches that should be excluded during the patch set creation process. It also contains those patches that should be replaced by another patch. This list contains one patch per line, where patches are given a specific revision level, or the patch ID is given by itself. You can also replace a given patch. To do so, provide a second column with the replacement patch ID.

Be mindful that no further dependency checks are performed on the replacement patch.

As with the whitelist configuration, lines beginning with a hash mark (#) and empty lines are ignored. You can use selectors at the end of a line to indicate for which system the specified patch should be replaced or ignored. See the whitelist configuration information for possible selectors to use. The selector must be the last entry on a line. Values of the selectors that are embedded in slashes are treated as regular expressions. You can also list a patch multiple times, with different selectors. In this instance, the first match is taken as black-listed patch.

Example 3–1 Sample Blacklist Configuration

This is an example of a blacklist configuration.

# We don't like this patch at all:
123456

# We don't like this very specific revision
# However, other revision could be included.
789098-24


# We want to replace a specific patch
109320-06   109320-08

# Only ignore this patch on machine "eclipse"
109456-13   name=>"eclipse"

# Patches can be mentioned multiple times with different 
# selectors
109456-13   name=>"sun42"

# The same as above in one single line using regular expressions
109456-13   name=>"/eclipse|sun42/"

# Replace this patch on all Solaris 5.8 machines
109320-06   109320-08     os=>"Solaris",version=>"5.8"

Any additional patches that are dependent on these black-listed patches are excluded from the resulting patch set, as well. For replacement patches, no further check or dependency resolution is performed. You can provide more than one blacklist option in the configuration file. Multiple blacklist entries are merged. If a blacklist cannot be found, it is ignored.