User s Guide for Software Distribution

Transcription

1 IBM Tivoli Configuration Manager User s Guide for Software Distribution Version SC

2

3 IBM Tivoli Configuration Manager User s Guide for Software Distribution Version SC

4 Note Before using this information and the product it supports, read the information in Notices on page 351. Second Edition (December 2003) This edition applies to version 4, release 2, modification level 1 of IBM Tivoli Configuration Manager (program number 5724-C06) and to all subsequent releases and modifications until otherwise indicated in new editions. This edition replaces SC Copyright International Business Machines Corporation 2002, All rights reserved. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

5 Contents Figures vii Tables ix Preface xi Who Should Read This Guide xi What This Guide Contains xi Publications xiii IBM Tivoli Configuration Manager Library.. xiii Related Publications xiv Accessing Publications Online xiv Ordering Publications xv Accessibility xv Contacting Software Support xv Conventions Used in This Guide xvi Typeface Conventions xvi Operating system-dependent Variables and Paths xvi Software Distribution Icons xvii Part 1. Preparing Software Packages 1 Chapter 1. Overview of Software Distribution What Is New in This Version Software Distribution Highlights Software Package Preparation Support for Previous Product Releases Software Package Distributions and Operations..8 Multiplexed Distributions The Software Distribution Environment Source Host Distribution Targets Software Packages Object-related Actions System Actions Program Actions Nested Software Packages Software Package Formats Software Package (.sp) File Software Package Definition (.spd) File Software Package Block (.spb) Software Package Object Choosing a Software Package Format Tivoli Desktop Operations Software Distribution Operations Chapter 2. Launching the Software Package Editor Launching the Software Package Editor on Endpoints From the Desktop From the Command Line Launching the Software Package Editor on Managed Nodes Determining the Type of Package You Will Create 23 Embedding a Native Package into a Software Package Creating a Software Package with AutoPack..23 Creating a Software Package using a Template..23 Customizing a Sample Software Package...23 Creating a Software Package for Mixed Target Types Working with an Existing Software Package..24 Customizing the Software Package Editor GUI..24 Customizing the Welcome Page Creating a New Software Package Sample...26 Creating a New Software Package Template..26 Setting the Default Path Chapter 3. Creating Packages Using the Software Package Editor Creating a Software Package Creating the Appsample Software Package Naming the Appsample Software Package...31 Checking Disk Space Adding Directories and Files Adding Windows Platform Actions to a Generic Container Adding OS/2 Platform Actions to a Generic Container Adding an Execute Program Action Adding a Restart Action The Appsample Software Package Setting Properties on the Package General Properties Server Options Endpoint Options Log File Properties Description Copyright Variable List Nested Packages Editing Software Package Properties Program Actions in the Software Package Editor..75 The InstallShield Program Action The Microsoft Setup Program Action Remove Actions Saving the Software Package Chapter 4. Creating a Software Package for Devices Creating a Device Object Software Package Adding Directories to Devices Adding Files to Devices Running Programs on Devices Customizing Device Settings Copyright IBM Corp. 2002, 2003 iii

6 Distributing the Device Object Software Package to Targets Chapter 5. Using Software Distribution on OS/ Defining Software Packages with OS/400 Objects..91 The OS/400 Native and Integrated File Systems..92 Using the OS/400 Software Package Editor Launching the OS/400 Software Package Editor 93 Adding OS/400 Libraries and Objects Adding OS/400 Objects Removing OS/400 Libraries Removing OS/400 Objects Adding OS/400 Licensed Programs Removing OS/400 Licensed Programs Changing an OS/400 Sysval Using Non-OS/400-Specific Functions Adding Non-Native Objects to the OS/400 Native File System Running an OS/400 Executable Program Saving an OS/400 Software Package Chapter 6. Embedding Native Objects into a Software Package Using the Software Package Editor to Embed Native Objects Benefits of Embedding Native Objects Creating a Software Package that Embeds a Native Object Defining Supported Software Distribution Operations in a Native Installation Using a Wizard Using the Install MSI Product Importer Using the PDF Importer Using Dialogs Using Dialogs to Embed or Edit an AIX Package 121 Using Dialogs to Embed or Edit a Solaris Package Using Dialogs to Embed or Edit a Linux Package Using Dialogs to Embed or Edit an HP-UX Package Using Dialogs to Embed or Edit an MSI Package 135 The Execute CID Program Action The InstallShield Program Action The Microsoft Setup Program Action Making a Native Installation Conditional Defining an Inventory Signature for a Native Package Chapter 7. How Does AutoPack Work? 145 AutoPack Components AutoPack Configuration File Customizing the Configuration File Dealing with Shared Objects Autopack.ini Default for Windows Autopack.ini Default for Windows XP Autopack.ini Default for Windows Autopack.ini Default for UNIX Systems Autopack.ini Default on OS/2 Systems Chapter 8. Generating a Software Package Using AutoPack Running AutoPack Creating the First Snapshot Manual Installation Option Resuming the Second Snapshot The Automatic Installation Option Part 2. Planning and Distributing Software Packages Chapter 9. Preparing a Software Package for Distribution Creating a Software Distribution Profile Setting the Profile Subscribers Importing a Software Package into the Tivoli Environment Creating a New Software Package and Importing it into a Software Package Profile Importing an Existing Software Package into a Software Package Profile Deleting a Software Package Profile Software Package Properties Calculating the Size of a Software Package Converting a Software Package Not-built to Built Built to Not-built Exporting a Software Package Change Management Operations Software Package States Executing Change Management Operations Customizing the GUI Settings Installing the Appsample^1.0 Software Package 196 Advanced Options Installing the Device Object Software Package 210 Distributing Nested Software Packages Things To Consider Checking the Outcome of a Distribution Checkpoint Restart Service for Network Failure or Power Interruptions Example Scheduling a Distribution Chapter 10. Using Data Moving Configuring the Data Moving Service Data Moving Scenarios Sending Data to Multiple Destinations Data Retrieval from Multiple Origins Deleting a File on Multiple Systems Moving Files from Endpoint to Endpoint Defining the Advanced Options Using Pre- and Post-Processing Scripts Examples The Data Moving Service in an OS/400 Environment Chapter 11. Configuring a Network Topology Introducing NoonTide iv IBM Tivoli Configuration Manager: User s Guide for Software Distribution

7 Network Architecture Creating a Repeater Hierarchy Configuring Repeater Sites Setting Repeater Parameters How Software Distribution Works Software Distribution Methods Software Distribution Scenarios Scenario 1: Distributing from a Tivoli Management Region Server through a Gateway. 254 Scenario 2: Distributing from a Source Host/Tivoli Management Region Server to a Repeater Scenario 3: Distributing from a Source Host through Repeater Depots Scenario 4: Distributing from a Tivoli Management Region Server to a Mobile Endpoint Installing Images from a CD-ROM Scenario 5: Performing Data Moving Operations 260 Chapter 12. Integrating the Tivoli Enterprise Console Enabling the Tivoli Enterprise Console Steps to Enable the Integration The tecad_sd.conf File Creating the Software Distribution Console Software Distribution Classes Chapter 13. Integrating Inventory with Software Distribution Configuration Repository Query Facility Describing Software Distribution Tables How the Integration Works Enabling and Disabling the Historical Database and Change Management Status Exchanging Information between Software Distribution and Inventory Defining an Inventory Signature Creating the INVENTORY_QUERIES Running an INVENTORY_QUERY Desktop Command Line Modifying SWDISTDATA_QUERY Desktop Command Line Using the Check_OS^1.0.spd to Verify the Upgrade 287 Chapter 15. Troubleshooting Troubleshooting Process Hints and Tips Improving Performance Setting the Number of Endpoints to Be Handled 293 Setting the Report Timeout for the Server Setting the Number of Threads Checking Configuration Files Base Configuration Information on the Distribution Server and Source Host Base Configuration Information on the Endpoint 294 Software Distribution Logs Software Package Log Data Moving Logs Log Object List Notices and Mail Tivoli Enterprise Console Configuration Repository Examining the SPD File Troubleshooting the Software Package Editor GUI 305 Checking Repeaters, Gateways, and Endpoints Setting Timeout Values for a Distribution Verifying Setup for Endpoints Checking lost-n-found Checking the Default Directory on a Target System 311 Part 3. Appendixes Appendix A. Accessibility Navigating the Interface Using the Keyboard Software Package Editor Magnifying What Is Displayed on the Screen Enabling the IBM Home Page Reader to Function with the Software Package Editor Appendix B. Using Deployment Services with Software Distribution Activity Planner Change Manager Web Interface Resource Manager Enterprise Directory Query Library Pristine Manager Chapter 14. Upgrading Windows 2000 Professional to Windows XP Environment Configuration Creating a Response File Copying the Files That You Need to Perform the Migration to the Tivoli Server Copying the Windows XP Files to the Image Server 285 Customizing the Inst_wXP.spd Software Package Definition File Creating the Software Package on the Tivoli Server 286 Subscribing the Endpoints to the Upgrades Profile Manager Distributing the Software Package to the Tivoli Endpoints Appendix C. Pristine Installations Overview Typical Network Environment Prerequisites Windows Steps Pristine Installation Scenario Step 1: Planning Step 2: Creating and Maintaining Code Server Objects Step 3: Creating and Maintaining Code Server Object Configurations Step 4: Preparing a System Diskette Step 5: Creating a Pristine Boot Diskette Contents v

8 Step 6: Running a Pristine Installation OS/2 Steps Pristine Installation Scenario Step 1: Planning Step 2: Creating and Maintaining a Code Server Object Step 3: Adding System Files to Code Server Objects Step 4: Creating and Maintaining Code Server Object Configurations Step 5: Preparing the System Diskettes Step 6: Creating Pristine Boot Diskettes Step 7: Running a Pristine Installation Appendix D. Authorization Roles Setting Up Software Distribution Profiles Defining and Deleting Profiles Performing Operations Notices Trademarks Glossary Index vi IBM Tivoli Configuration Manager: User s Guide for Software Distribution

9 Figures 1. MDist 2 and change management operations Distribution from Tivoli server through a gateway Distributing from a host through a repeater Distribution from Tivoli server to mobile endpoints Data moving retrieve operation Troubleshooting the distribution of a software package Pristine installation scenario Copyright IBM Corp. 2002, 2003 vii

10 viii IBM Tivoli Configuration Manager: User s Guide for Software Distribution

11 Tables 1. Software Package Editor Directory Structure Supported Software Distribution operations for the MSI package native object Supported Software Distribution operations for the MSI patch native object Supported Software Distribution operations for the AIX package native object Supported Software Distribution operations for the AIX updates native object Supported Software Distribution operations for the Solaris package native object Supported Software Distribution operations for the Solaris patch native object Supported Software Distribution operations for Linux package native object Supported Software Distribution operations for HP-UX package native object Mapping of Software Distribution reinstall mode values to the MSI command line Components monitored by AutoPack and supported platforms Customizing default values for distribution options Software Distribution methods and corresponding operations and commands Software Distribution Tivoli Enterprise Console events Tivoli Enterprise Console event attributes for Software Distribution Location of swdis.ini file Directory assignments in swdis.ini file Keyboard shortcuts for the Software Package Editor Source path location for operating system image on CD-ROM Source path location for operating system image Required roles for setting up software package profiles Required roles for setting software package properties and viewing configuration information Required roles to distribute software packages Copyright IBM Corp. 2002, 2003 ix

12 x IBM Tivoli Configuration Manager: User s Guide for Software Distribution

13 Preface Who Should Read This Guide Software Distribution provides a means of managing and distributing software across a multi platform network. For distributions that encompass wide area networks (WANs), Software Distribution has a built-in, WAN-smart capability that reduces internetwork traffic and ensures an efficient distribution. This guide explains the concepts and procedures necessary for you to effectively use Software Distribution to distribute software over local area networks (LANs) and WANs. This book is intended for system administrators who perform software package preparation and deployment operations. Readers should be familiar with the following topics: v The UNIX and PC platforms v Shell programming What This Guide Contains v Concepts such as directories, files, and symbolic links v Operating systems running on target machines to which software is distributed This guide contains the following sections: Part 1. Preparing Software Packages Part 1 contains the following chapters: v Chapter 1, Overview of Software Distribution, on page 5 Provides an introduction to the application by describing the Software Distribution features and terminology. v Chapter 2, Launching the Software Package Editor, on page 19 Explains how to launch the Software Package editor on endpoints and managed nodes and the tasks you can perform. v Chapter 3, Creating Packages Using the Software Package Editor, on page 29 Using the Appsample scenario, describes the steps required to create a software package using the Java -based Software Package Editor graphical user interface (GUI), including setting software package properties and adding software package actions. v Chapter 4, Creating a Software Package for Devices, on page 83 Describes how to create and distribute software packages for targets that are pervasive devices. v Chapter 5, Using Software Distribution on OS/400, on page 91 This chapter describes the Software Distribution features that are specific for OS/400 operating systems. v Chapter 6, Embedding Native Objects into a Software Package, on page 107 Explains how to embed native installation objects in a Software Distribution software package. Copyright IBM Corp. 2002, 2003 xi

14 Preface v Chapter 7, How Does AutoPack Work?, on page 145 Introduces the underlying concepts of AutoPack technology, including the preparation machine, AutoPack system components, the configuration file, customizing the configuration file to suit particular workstation configurations, the snapshot, the differencing phase, and what AutoPack does to support shared objects. v Chapter 8, Generating a Software Package Using AutoPack, on page 157 Describes the steps required to create a software package using AutoPack from the Software Package Editor window. Using the AutoPack Guided Process, a software package is created that installs the Tivoli desktop application. Part 2. Planning and Distributing Software Packages Part 2 contains the following chapters: v Chapter 9, Preparing a Software Package for Distribution, on page 177 Describes setting up the Software Distribution environment, including defining profile managers within a policy region and associating target machines with software package profiles. Describes Tivoli desktop functions such as using the build and unbuild function, using the import and export functions, and performing change management operations. v Chapter 10, Using Data Moving, on page 221 The Data Moving Service integrates data movement capabilities into the software package distribution process. v Chapter 11, Configuring a Network Topology, on page 235 Introduces a Tivoli management region scenario to illustrate how to configure a network topology. This chapter provides steps for setting up a distribution environment that uses endpoint gateways, repeaters, and repeater depots. It also describes typical distribution scenarios. v Chapter 12, Integrating the Tivoli Enterprise Console, on page 263 Explains how to install and enable the Tivoli Enterprise Console integration product. This chapter also provides a description of the Software Distribution event configuration file and event classes. v Chapter 13, Integrating Inventory with Software Distribution, on page 271 Explains how to integrate Software Distribution with Inventory and how to define an Inventory signature in a software package. This chapter also describes how to create the INVENTORY_QUERIES query library and how to modify the related queries. v Chapter 14, Upgrading Windows 2000 Professional to Windows XP, on page 283 Describes how to upgrade Windows 2000 Professional to Windows XP. v Chapter 15, Troubleshooting, on page 289 This appendix provides sources of information that will help you in solving problems with Software Distribution operations. Part 3. Appendixes Part 3 contains the following appendixes: v Appendix A, Accessibility, on page 315 Accessibility features help users who have physical disabilities, such as restricted mobility or limited vision, to use software products successfully. xii IBM Tivoli Configuration Manager: User s Guide for Software Distribution

15 Preface v Appendix B, Using Deployment Services with Software Distribution, on page 317 This appendix outlines where you can find information related to the IBM Tivoli Configuration Manager, Version services, which are the following: Activity Planner Change Manager Web Interface Resource Manager Enterprise Directory Query Facility Pristine Manager v Appendix C, Pristine Installations, on page 319 The pristine tool provides support for installing new operating systems on Pristine machines, and then maintaining the new computers on the network. v Appendix D, Authorization Roles, on page 349 Describes the roles required to perform Software Distribution tasks. Publications This section lists publications in the IBM Tivoli Configuration Manager library and related documents. It also describes how to access Tivoli publications online and how to order Tivoli publications. IBM Tivoli Configuration Manager Library The following documents are available in the IBM Tivoli Configuration Manager library: v IBM Tivoli Configuration Manager: Introducing IBM Tivoli Configuration Manager, GC Provides an overview of IBM Tivoli Configuration Manager and its components, as well as providing scenarios to highlight various processes. v IBM Tivoli Configuration Manager: Planning and Installation Guide, GC Explains how to install, upgrade, and uninstall the product and its components in a Tivoli environment. v IBM Tivoli Configuration Manager: User s Guide for Software Distribution, SC Explains the concepts and procedures necessary for you to effectively use the Software Distribution component to distribute software over local area networks (LANs) and wide area networks (WANs). v IBM Tivoli Configuration Manager: Reference Manual for Software Distribution, SC Explains advanced features and concepts needed to use and tailor the Software Distribution component. v IBM Tivoli Configuration Manager: User s Guide for Inventory, SC Describes the Inventory component and the management tasks that you can perform. v IBM Tivoli Configuration Manager: User s Guide for Deployment Services, SC Provides information about the Deployment Services of the product. v IBM Tivoli Configuration Manager: Database Schema Reference, SC Provides information about the IBM Tivoli Configuration Manager repository. v IBM Tivoli Configuration Manager: Messages and Codes, SC Details all the error, warning messages and error codes issued by the product. v IBM Tivoli Configuration Manager: Release Notes, GI Preface xiii

16 Preface Contains late-breaking information about the product. Related Publications The following documents also provide useful information: v IBM Tivoli Configuration Manager: User s Guide for Inventory, SC Provides detailed information about managing hardware and software using Inventory. v Tivoli Enterprise: Installation Guide, GC Explains how to install and upgrade Tivoli Enterprise software within your Tivoli region using the available installation mechanisms provided by Tivoli Software Installation Service and Tivoli Management Framework. Tivoli Enterprise software includes the Tivoli server, managed nodes, gateways, endpoints, and RDBMS Interface Module (RIM) objects. This guide also provides information about troubleshooting installation problems. v Tivoli Management Framework: Planning for Deployment Guide, GC Explains how to plan for deploying your Tivoli environment. It also describes Tivoli Management Framework and its services. v Tivoli Management Framework: Maintenance and Troubleshooting Guide, GC Explains how to maintain a Tivoli environment and troubleshoot problems that can arise during normal operations. v Tivoli Management Framework: Reference Manual, GC Provides in-depth information about Tivoli Management Framework commands. This manual is helpful when writing scripts that are later run as Tivoli tasks. This manual also documents default and validation policy scripts used by Tivoli Management Framework. v Tivoli Management Framework: User s Guide, GC Describes the concepts and procedures for using Tivoli Management Framework services. It provides instructions for performing tasks from the Tivoli desktop and from the command line. v IBM Tivoli Enterprise Console: User s Guide and IBM Tivoli Enterprise Console: Adapters Guide Provides detailed information about integrating network, systems, database, and application management with Tivoli Enterprise Console. The Tivoli Software Glossary includes definitions for many of the technical terms related to Tivoli software. The Tivoli Software Glossary is available, in English only, at the following Tivoli software library Web site: Access the glossary by clicking the Glossary link on the left pane of the Tivoli software library window. Accessing Publications Online The documentation CD contains the publications that are in the product library. The format of the publications is PDF, HTML, or both. Refer to the readme file on the CD for instructions on how to access the documentation. The product CD contains the publications that are in the product library. The format of the publications is PDF, HTML, or both. To access the publications using xiv IBM Tivoli Configuration Manager: User s Guide for Software Distribution

17 Preface Accessibility a Web browser, open the infocenter.html file. The file is in the appropriate publications directory on the product CD. IBM posts publications for this and all other Tivoli products, as they become available and whenever they are updated, to the Tivoli software information center Web site. Access the Tivoli software information center by first going to the Tivoli software library at the following Web address: Scroll down and click the Product manuals link. In the Tivoli Technical Product Documents Alphabetical Listing window, click the <Your Product Library Name> link to access the product library at the Tivoli software information center. Note: If you print PDF documents on other than letter-sized paper, set the option in the File-> Print window that allows Adobe Reader to print letter-sized pages on your local paper. Ordering Publications You can order many Tivoli publications online at the following Web site: cgibin/pbi.cgi You can also order by telephone by calling one of these numbers: v In the United States: v In Canada: Contacting Software Support In other countries, see the following Web site for a list of telephone numbers: Accessibility features help users who have physical disabilities, such as restricted mobility or limited vision, to use software products successfully. With this product, you can use assistive technologies to hear and navigate the interface. You can also use the keyboard instead of the mouse to operate all features of the graphical user interface. For additional information, see Appendix A, Accessibility, on page 315. If you have a problem with any Tivoli product, refer to the following IBM Software Support Web site: If you want to contact software support, see the IBM Software Support Guide at the following Web site: Preface xv

18 Preface The guide provides information about how to contact IBM Software Support, depending on the severity of your problem, and the following information: v Registration and eligibility v Telephone numbers, depending on the country in which you are located v Information you must have before contacting IBM Software Support Conventions Used in This Guide This guide uses several conventions for special terms and actions, and operating system-dependent commands and paths. Typeface Conventions This guide uses the following typeface conventions: Bold Italic Monospace v Lowercase commands and mixed case commands that are otherwise difficult to distinguish from surrounding text v Interface controls (check boxes, push buttons, radio buttons, spin buttons, fields, folders, icons, list boxes, items inside list boxes, multicolumn lists, containers, menu choices, menu names, tabs, property sheets), labels (such as Tip:, and Operating system considerations:) v Keywords and parameters in text v Words defined in text v Emphasis of words (words as words) v New terms in text (except in a definition list) v Variables and values you must provide v Examples and code examples v File names, programming keywords, and other elements that are difficult to distinguish from surrounding text v Message text and prompts addressed to the user v Text that the user must type v Values for arguments or command options Operating system-dependent Variables and Paths This guide uses the UNIX convention for specifying environment variables and for directory notation. When using the Windows command line, replace $variable with % variable% for environment variables and replace each forward slash (/) with a backslash (\) in directory paths. The names of environment variables are not always the same in Windows and UNIX. For example, %TEMP% in Windows is equivalent to $tmp in UNIX. Note: If you are using the bash shell on a Windows system, you can use the UNIX conventions. xvi IBM Tivoli Configuration Manager: User s Guide for Software Distribution

19 Preface Software Distribution Icons The following icons represent the Software Distribution profile resource displayed on the Tivoli desktop in different formats: Icon for software package profile icon in built format. Icon for software package profile icon in not-built format. Icon for empty software package profile. Software package profile resources are created in the context of a profile manager and are distributed to subscribing systems or profile managers managed in the Tivoli environment. Preface xvii

20 Preface xviii IBM Tivoli Configuration Manager: User s Guide for Software Distribution

21 Part 1. Preparing Software Packages Chapter 1. Overview of Software Distribution.. 5 What Is New in This Version Software Distribution Highlights Software Package Preparation Support for Previous Product Releases Software Package Distributions and Operations..8 Multiplexed Distributions The Software Distribution Environment Source Host Distribution Targets Software Packages Object-related Actions System Actions Program Actions Nested Software Packages Software Package Formats Software Package (.sp) File Software Package Definition (.spd) File Software Package Block (.spb) Software Package Object Choosing a Software Package Format Tivoli Desktop Operations Software Distribution Operations Chapter 2. Launching the Software Package Editor Launching the Software Package Editor on Endpoints From the Desktop From the Command Line On Windows Endpoints On OS/2 Endpoints On UNIX Endpoints Launching the Software Package Editor on Managed Nodes Determining the Type of Package You Will Create 23 Embedding a Native Package into a Software Package Creating a Software Package with AutoPack..23 Creating a Software Package using a Template..23 Customizing a Sample Software Package...23 Creating a Software Package for Mixed Target Types Working with an Existing Software Package..24 Customizing the Software Package Editor GUI..24 Customizing the Welcome Page Creating a New Software Package Sample...26 Creating a New Software Package Template..26 Setting the Default Path Chapter 3. Creating Packages Using the Software Package Editor Creating a Software Package Creating the Appsample Software Package Naming the Appsample Software Package...31 Checking Disk Space Adding Directories and Files Adding Windows Platform Actions to a Generic Container Adding Windows Operating System Directories and Files Adding Windows Registry Objects Adding Windows Shell Objects Adding Windows Profile Objects Adding Windows Services Adding OS/2 Platform Actions to a Generic Container Adding OS/2 Desktop Objects Adding OS/2 Profile Objects Adding Text File Objects Adding an Execute CID Program Action...56 Adding an Execute Program Action Adding a Restart Action The Appsample Software Package Changing the Order of Objects in the Software Package Setting Properties on the Package General Properties The Dependency Editor Server Options Setting Server Options Setting Advanced Server Options Endpoint Options Before Program Options After Program Options Log File Properties Description Copyright Variable List Nested Packages Editing Software Package Properties Program Actions in the Software Package Editor..75 The InstallShield Program Action The Microsoft Setup Program Action Remove Actions Saving the Software Package Chapter 4. Creating a Software Package for Devices Creating a Device Object Software Package Adding Directories to Devices Adding Files to Devices Running Programs on Devices Customizing Device Settings Customizing Nokia 9200 Communicator Series Devices Customizing Palm and Windows CE Devices 89 Distributing the Device Object Software Package to Targets Chapter 5. Using Software Distribution on OS/ Copyright IBM Corp. 2002,

22 Defining Software Packages with OS/400 Objects..91 The OS/400 Native and Integrated File Systems..92 Using the OS/400 Software Package Editor Launching the OS/400 Software Package Editor 93 Adding OS/400 Libraries and Objects Adding OS/400 Objects Removing OS/400 Libraries Removing OS/400 Objects Adding OS/400 Licensed Programs Removing OS/400 Licensed Programs Changing an OS/400 Sysval Using Non-OS/400-Specific Functions Adding Non-Native Objects to the OS/400 Native File System Running an OS/400 Executable Program Saving an OS/400 Software Package Chapter 6. Embedding Native Objects into a Software Package Using the Software Package Editor to Embed Native Objects Benefits of Embedding Native Objects Creating a Software Package that Embeds a Native Object Defining Supported Software Distribution Operations in a Native Installation Using a Wizard Using the Install MSI Product Importer Using the PDF Importer Using Dialogs Using Dialogs to Embed or Edit an AIX Package 121 Using Dialogs to Embed or Edit a Solaris Package Using Dialogs to Embed or Edit a Linux Package Using Dialogs to Embed or Edit an HP-UX Package Using Dialogs to Embed or Edit an MSI Package 135 The Execute CID Program Action The InstallShield Program Action The Microsoft Setup Program Action Making a Native Installation Conditional Defining an Inventory Signature for a Native Package Chapter 7. How Does AutoPack Work? AutoPack Components AutoPack Configuration File Customizing the Configuration File Notes for Certain User Scenarios Dealing with Shared Objects Autopack.ini Default for Windows Autopack.ini Default for Windows XP Autopack.ini Default for Windows Autopack.ini Default for UNIX Systems Autopack.ini Default on OS/2 Systems Chapter 8. Generating a Software Package Using AutoPack Running AutoPack Creating the First Snapshot Manual Installation Option Resuming the Second Snapshot The Automatic Installation Option IBM Tivoli Configuration Manager: User s Guide for Software Distribution

23 This part describes how to use the Software Package Editor to create software packages. Locating Related Information Information related to this task is available from the following sources: v Introducing IBM Tivoli Configuration Manager. This provides an overview of Software Distribution. v Reference Manual for Software Distribution. This includes information about how to perform this same task from the command line. v Planning and Installation Guide. This includes information about how you install Software Distribution. v Messages and Codes. This provides details of all messages generated by the IBM Tivoli Configuration Manager components and services. Part 1. Preparing Software Packages 3

24 4 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

25 Chapter 1. Overview of Software Distribution With Software Distribution, you can install, configure, and update software on networked systems from a single source system, thereby eliminating the task of manually updating software on numerous systems. You can create and distribute desktop and client/server applications, manage the software life cycle, automate system inventories, and monitor system and configuration changes. Software Distribution can quickly and reliably deploy software across multiplatform networks, which can include UNIX, NetWare, Windows, OS/400, and OS/2 systems at remote sites. Refer to the Release Notes for details about supported platforms for this product. What Is New in This Version Software Distribution features the following enhancements: v Easier to use Software Package Editor When you launch the Software Package Editor graphical user interface (GUI), an initial dialog, Software Package Editor Selector, enables you to filter the objects you use to create your software package so that you work with only the tools necessary to create your particular package. You can also customize the GUI to include your own proprietary templates and welcome page. v HP-UX native packaging support Native packaging support has been extended to include the HP-UX package. v Before and after endpoint programs A program or script can be launched on the endpoint before the execution of the change management operation and after the execution of the operation. Package-level properties and a new command, wdswdvar, have been added to enable this feature. These programs are particularly useful for managing variables with dynamic values. See Before Program Example on page 69 for an example. v Default value customization The wswdmgr command has been modified to enable the customization of default values for some distribution options. v Default path customization Customize the default path used by the Software Package Editor browser dialog. v Software Package Editor customization Create your own templates to modify the icons displayed in the Software Package Editor main window so that only the actions necessary to create your software package are displayed. Define your own sample software packages that you can open and modify to create other software packages saving them with a different name. v Unavailable targets or targets that are no longer valid In previous releases, if one or more targets were not available or not valid, the distribution failed on those targets and the distribution did not continue on the remaining targets. In this release, you can choose to have the distribution Copyright IBM Corp. 2002,

26 Highlights continue on the remaining targets. Information about the targets on which the operation did not complete is written to the Software Distribution log file. v Datamoving retrieve status on mobile endpoints New tags added to swdis.ini permit mobile users to check the status of data retrieve operations. v Reboot action during commit phase A restart action can run during the commit phase of the package. v Checks on shared objects When a package is removed, shared objects are checked to avoid their deletion if these objects were already present on the target prior to the initial installation of the software package. You can choose to check all objects distributed with the software package, only objects marked as shared, or no objects at all. Software Distribution Highlights Software Distribution provides a centralized software-management system with which administrators can use software packages to install and configure new applications, update existing software with newer versions, and synchronize software on distributed systems. The following sections summarize the highlights of Software Distribution. The highlights are grouped under the following topics: v Software Package Preparation v Support for Previous Product Releases on page 8 v Software Package Distributions and Operations on page 8 v Multiplexed Distributions on page 10 Software Package Preparation The Software Package Editor is a graphical interface for creating and customizing a software package. It can be installed on any of your available managed nodes and endpoints. Refer to Release Notes for a list of supported platforms. The Software Package Editor displays a graphical tree view of the software package and its contents. You organize the actions that are contained in the package in the order in which they are to be executed on the target system. The Software Package Editor provides several ways for you to create and edit a software package. It supplies the following features: v Unified software package Software Distribution makes use of a simplified single content packaging format called the software package. All of the techniques used to create software packages are based on this single file format. Therefore, a software package created using AutoPack is identical to a package created manually using the Software Package Editor, and both can be edited using any of the available techniques explained in this chapter. v Application configuration By installing software packages, you can perform actions such as changing the registry, adding desktop icons, adding statements to system files, and creating folders and shortcuts. Software Distribution eliminates the need to create scripts and programs to configure an application. You can package the required action in the software package. v Variables Variables can be used to express any attribute value of type string contained in the software package, making a software package more generic for use on different target systems. For example, it is not necessary to create several 6 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

27 Highlights software packages for different platforms. You can substitute the platform-specific information with variables and use the same software package for distribution to multiplatform networks. Refer to the Reference Manual for Software Distribution for more details on using variables in the software package. v Conditions You set conditions on the actions contained in a software package or on the entire software package. Using conditions, you define the circumstances under which an action is executed. For example, you can specify which actions are to be executed only on Windows 2000 target systems and which are to be executed only on Windows XP. v Inventory signature files Add an object in your software package that defines a signature in the configuration repository so that you can have an up-to-date list of the software installed in your environment. v Device object support You can create a software package containing actions to be performed on pervasive devices. v Third-party and native installation support v Common third-party packaging formats are supported. Existing content prepared in these native formats, and the associated installation utilities and response files, can be packaged within the software package. The following packaging formats are available: Microsoft Setup InstallShield Configuration, installation, and distribution (CID) programs Package Definition File (PDF), a Microsoft Systems Management Server file MSI package, Microsoft Software Installer AIX package Solaris Operating Environment package Linux package HP-UX package Version checks You can define a software package as versionable and specify whether it is a refresh package or a patch. Refreshes are not installed if a later version of the package is already installed. Patches are not installed unless the version to which the patch applies is already installed. v Dependency You can define an expression that makes the installation or removal of a software package dependent on meeting hardware and software prerequisites. v AutoPack Automatic software package generation: AutoPack automatically generates a software package by employing scanning and differencing technology, and comparing two successive "snapshots" of a preparation machine. v OS/400 endpoint support The OS/400 endpoint support extends the capabilities of Software Distribution to managing software packages for OS/400 target systems. Software Distribution includes an OS/400 Software Package Editor. You use the Software Package Editor on a Windows system, which has a TCP/IP connection to an OS/400 system that is used as a software package preparation site. You can build software packages that include OS/400 objects, such as libraries, objects, and Chapter 1. Overview of Software Distribution 7

28 Highlights licensed programs, and changes to OS/400 system values. In addition, a software package for an OS/400 system can include standard actions to add non-os/400 files and directories to an OS/400 system and to execute user programs on an OS/400 system. The data moving service supports movement of files between OS/400 endpoints and Software Distribution source hosts. Support for Previous Product Releases Software Distribution provides the following support for previous product releases: v Support for file packages of previous product releases. File packages and the new software package format can co-exist within the same profile manager as different resource types. v A command (wfptosp) to convert file package objects and file package definition files, respectively, to software package objects and software package definition files. The keywords contained in file packages created with a previous product release are mapped to software package stanzas, attributes, and commands. Refer to the Reference Manual for Software Distribution for more information about migration procedures. Software Package Distributions and Operations Using the Tivoli desktop or command line interface (CLI), you can perform change management operations to fully automate the distribution and installation of software. The operations you can perform include the following: v Automatic undo You can perform an undo operation on the software package so that, if a fatal error occurs during the installation process, the undo operation is triggered automatically and returns the system to its state prior to the execution of the last install or remove operation. This means that any files added by the installation, that did not exist before the distribution, are removed. Files that existed before the distribution and were removed, are added back. Files that existed prior to the distribution and were replaced, are restored to the previous copy. This is also true for any additions, deletions, or changes made to configuration or system information such as registry changes,.ini file entries, folders, and shortcuts. v Verification of installed software packages You can perform a verify operation on a software package to determine that the target objects have been successfully installed on the target system. v Locked file support If a locked file is encountered during a distribution, normally it cannot be updated. Distributing the software package in transactional mode enables you to take advantage of locked file support, which permits the updating of locked files, by specifying that the target system is to be restarted at the time of installation, or at the next regular system start up. v Renaming if locked This function removes the need to reboot a workstation immediately after a distribution when a locked file is encountered. A copy of the file is made and renamed. v Shared object support Because many applications use the same resources, such as files, directories, and registry entries, these shared objects must be identified in the software package. Using a shared attribute, for example, on files and directories, you can share files and directories among multiple applications. If a software package is designed to remove an application from a target system, and one of the objects contained in the software package is identified as a shared resource, the object is removed 8 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

29 Highlights when the last application using this resource is removed. If a shared resource in a software package is found to exist on the target, the latest version of the resource is used. v File version support You can set different properties on objects in the software package to manage their behavior. For example, if an object contained in a software package already exists on the target system, you can configure the object properties so that Software Distribution replaces the existing copy only if the creation date of the copy is earlier than the file or directory contained in the software package. v Source and repair functionality The repair functionality reduces network congestion. It identifies which source and target objects have been modified or corrupted since the last successful installation of a software package, and rebuilds the software package with only these objects rather than installing the entire package again. v Byte-level differencing With byte-level differencing, you create and distribute delta packages for installation, thereby significantly reducing network traffic. A delta package is created from the differences this technology detects between the software package to be installed (version package), and the base package already installed on the target system, and only the delta package is distributed. The delta package is typically smaller than either the version package or the base package. The changes contained in the delta package are applied to the base package thereby upgrading it to the new version. For a detailed explanation of how byte level differencing works, see the Reference Manual for Software Distribution. v Data movement Data movement provides commands to distribute, retrieve, and delete files from machines in a Tivoli Management environment. Using this facility, you can move files from endpoint to endpoint, can move multiple files and directories. Data movement also enables wildcard and ASCII/EBCDIC conversion and code page translation for text files. Data moving operations can be submitted through a graphical user interface (GUI) and command line interface (CLI). v Install from CD and fileserver Enables you to specify that the software package to be installed is to be retrieved from a file server or a CD-ROM rather than from the source host. v Endpoint user notification Notify users of software package distributions on their systems and enable them to accept, reject or defer a distribution. v Operating system upgrades Software Distribution supports an upgrade for Windows 2000 Professional to Windows XP. v Pristine Tool A tool for creating a repository and storing diskette images for installing an operating system remotely on a clean machine. The advantages of using the pristine tool are: Preparation and installation can be performed at different times Installation can be performed almost completely unattended Synchronizing Change Manager reference models can be performed automatically v Integration with other applications and services The following list describes applications and services that work together with Software Distribution: Chapter 1. Overview of Software Distribution 9

30 Highlights You can use Inventory and the Tivoli Management Framework query facility to query a configuration repository to determine the appropriate targets of a distribution. This facility also enables you to track information about software distributions and the change management status of software packages on target systems. Using the Tivoli Management Framework Scheduler, you can schedule jobs at a future time, repeat scheduled jobs indefinitely, or repeat them a specified number of times. Through integration with the Tivoli Enterprise Console Software Distribution sends events to the event console for all distribution operations. The events include information such as failed and successful target exit codes, and messages related to failed distributions. Change Manager aids environment management. With it, you can define a reference model in which you specify the appropriate combination of software packages for a given set of workstation users within the enterprise. Activity Planner enables you to schedule the execution of a group of activities. Activities can be Software Distribution operations that are performed on targets at specified times. Multiplexed Distributions Software Distribution performs distributions of large amounts of data to multiple target systems. It relies on the multiplexed distribution (MDist 2) service, which it uses to simultaneously distribute large amounts of data to targets in an enterprise. The benefits include the following: v Multicast support In environments where there is limited bandwidth, you can send distributions using multicast which enables you to send a single distribution from the source to a group of targets simultaneously. v Asynchronous delivery The MDist 2 service submits distributions and, using a graphical user interface or commands, you can immediately check the status of each distribution on each target system without waiting until the distribution has completed for all targets. v Assured delivery MDist 2 distributions are cached in local files on each repeater. If a connection to a receiver cannot be established or is broken, the distribution is maintained in the cache until the connection is re-established and the distribution can be delivered. This feature includes the ability to resume distributions after network errors caused by machine restarts or power failures. v Checkpoint restart When a distribution is interrupted, the distribution is automatically resumed from a point depending on the cause of the interruption. If the interruption is due to a network error, the distribution is resumed from the point where the interruption occurred. If the interruption is due to a machine restart or power failure, the distribution is resumed from the last successful checkpoint before the interruption. A distribution that you manually terminate restarts from the beginning. Paused distributions also exploit the checkpoint restart feature. A distribution resumes from the point where it was paused. The checkpoint restart feature is a Software Distribution default. See Checkpoint Restart Service for Network Failure or Power Interruptions on page 216 for an example, or refer to the Reference Manual for Software Distribution for more information about this feature. v Distribution control 10 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

31 Highlights You can use the MDist 2 Distribution Status console to access and control data distributions initiated by different applications. The console displays a list of all completed and pending distributions and their status on each endpoint (waiting, successful, failed, in progress, paused, interrupted, unavailable, cancelled, or expired). v Pending distribution queues MDist 2 distributions can have three priority levels: low, medium, or high. Priority levels determine the order in which distributions are handled by repeaters. Distributions with higher priority levels are handled before those with lower priority. Distributions with the same priority level are handled in the order in which they are received by a repeater. MDist 2 also allows a maximum number of available connections to be specified for each priority level. A distribution with a given priority level uses the number of connections reserved for its priority level, plus any connections allocated for lower priority levels. v Depoting A depot is a directory on the repeater site that enables you to temporarily or permanently store data segments (that is, software packages) associated with software package distributions. This enables software distributions to be stored on nodes closer to the targets. You can send software packages from the depot, rather than from the source host, to target systems associated with that depot. v Mobile support This feature enhances the capability to deliver software to mobile users. By means of mobile support, end-users can decide which distributions to download or reject. While downloads are in progress, users can also pause and resume them. v Notification manager A software distribution service that handles message queues. Messages are collected and delivered as soon as the listener is available. Examples of notification activities and listeners follow: Logging results into a log file on a managed node or into a Notice group Sending an to a user Sending an event to the Tivoli Enterprise Console. Events provide information about successful and failed target exit codes, and lists of error message lists related to failed distributions Updating the configuration repository Using the wmsgbrowse command you can do the following: browse the message queue, retrieve messages based on their distribution ID, name, target, or logger; trace reports within messages, and delete a defined report or a whole message. These features enable you to perform rapid and optimal software distributions. For more information about the MDist 2 service, refer to the Tivoli Management Framework: Planning for Deployment Guide. The Software Distribution Environment When you install Software Distribution, you add a profile type, the software package, to the Tivoli environment. You can then manage the software package within the Tivoli Management Framework. Software packages are imported into the Tivoli environment and are associated with profiles. Software package profiles contain references to data, and instructions about how the data is to be distributed. All references to data are resolved at distribution time. Chapter 1. Overview of Software Distribution 11

32 Software Distribution Environment Policy regions, profile managers, and profiles are mechanisms provided by the Tivoli Management Framework to help organize resources hierarchically. You use this hierarchy to associate software packages with target machines. As with other Tivoli profile-based applications, Software Distribution functions in the context of a profile manager. Software packages are created in a profile manager, which contains profiles, and links subscribers to profiles. Source Host The source host is the system on which the software package block is stored, and where the resources referenced in the software package and software package definition file are located. Any UNIX, Linux, OS/2, or supported Windows operating system in your Tivoli environment can be a source host after Tivoli Management Framework and Software Distribution are installed. The effects of distributing a software package profile are different from those of other Tivoli profiles: actions are performed on the endpoints and resources are distributed. For example, when you distribute a software package profile, you execute actions, such as adding files and directories from the source host to the target, removing files and directories from the target, checking disk space on the target, and adding Windows registry keys. For more information about profiles refer to the Tivoli Management Framework: Planning for Deployment Guide. Distribution Targets Software Distribution enables you to distribute software packages to subscribers. A subscriber is an endpoint or a profile manager that is the target of the distribution. In the same category as profile managers, you can also select resource groups containing either pervasive devices or users as targets of a distribution. Refer to the User s Guide for Deployment Services for more information about resource groups. Software Packages In the Tivoli environment, an endpoint is a Tivoli client that receives Tivoli operations. An endpoint, is a managed node with the Tivoli Management Framework endpoint agent installed and is a possible target of a software distribution. Each endpoint is assigned to an endpoint gateway, which provides all communication services between a group of endpoints and the rest of the Tivoli environment. The gateway includes the multiplexed distribution (MDist 2) function, enabling this gateway to act as the fanout point for distributions to many endpoints. Refer to the Tivoli Management Framework: Planning for Deployment Guide for detailed information about how endpoints and gateways can be configured and used in the Tivoli environment. Software Distribution supports mobile endpoints. This enables mobile computer users to view a queue of all the distributions pending for their machine, and control when and in what order they receive their distributions. Refer to the Tivoli Management Framework: Planning for Deployment Guide for more information about configuring mobile endpoints. A software package contains a collection of actions to be performed on a workstation. After you create a software package and catalog it at the Software Distribution server, you can use change management operations to manage how the package actions are to be executed. The Software Package Editor provides 12 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

33 Software Distribution Environment several ways for you to create and edit software packages. It organizes actions into three categories: add and remove object-related actions, system actions, and program actions. Object-related Actions The add and remove object actions drive the Software Distribution engine to add the specified object to the system, or to remove it from the system. Objects can be files, directories, registry keys, registry values, and so on. The types of add and remove actions and their objects include: v Text file objects Lines Command lines Tokens v File system objects Files Directories File system links v OS/400 objects OS/400 libraries OS/400 objects OS/400 licensed programs v Windows registry objects Keys Values v Windows shell objects Folders Links v Windows profile objects Sections Items v OS/2 desktop objects Generic objects Folders Programs Shadows v OS/2 profile objects Profiles Items v Windows services You can also perform add actions on target devices. A software package for target devices can include the following actions: v Adding directories v Running execute programs v Adding files v Performing device customizations System Actions These actions include the following: v Check disk space. Include this check in your software package to be sure there is sufficient disk space on the target machine. Chapter 1. Overview of Software Distribution 13

34 Software Distribution Environment v Restart. Insert this action in your software package if a computer or operating system restart is necessary with the installation of an application. v OS/400 system value. Use this action to change OS/400 system values (SYSVAL). v Inventory signature. If you are creating a software package that installs images using one of the native installation tools available from the Software Package Editor, you can use this object in your software package to define a signature in the configuration repository. Program Actions Program actions involve the execution of generic programs or the use of third-party packaging utilities on a target system. They include the following: v Install MSI Product v Install MSI Patch v Install AIX Package v Install Solaris Package v Install Solaris Patch v Install Linux Package v Install HP-UX Package v Execute program v Execute CID program v InstallShield program v Microsoft Setup Program v Package Definition File (PDF), a Microsoft Systems Management Server file You can further organize and define actions in the software package as follows: v By using conditions, you can define the circumstances under which an action should be executed. For example, you can set a condition on the add Directory action specifying that this action be executed only on Microsoft Windows target systems of a particular release. You can set conditions on individual objects, or on the entire software package. v You can use a generic container to group actions together that must satisfy the same condition, so that change management operations can be executed on the actions as a group. You can include this container in the software package and nest other containers and actions inside it. v To make software packages more generic for use on target workstations with different configurations and operating systems, you can use several types of variables. Refer to the Reference Manual for Software Distribution for more information about using variables in the software package. A software package can also be created by defining its contents in a text file known as the software package definition (SPD) file. You create a software package in this file format either using the Software Package Editor GUI, manually by using a text editor, or by exporting an existing software package and modifying it. You can also use the CLI to create and manage software packages. Refer to the Reference Manual for Software Distribution for more information about using software package definition files and CLI commands. 14 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

35 Software Distribution Environment Nested Software Packages By adding a software package as an entry to another software package, you can create a nested software package. The software package that contains the nested software package is the primary package. You specify nested software packages when you create the primary package, or you can nest them using the drag-and-drop method from the Tivoli desktop. When Software Distribution distributes a software package that contains nested software packages, it also distributes the nested software packages. Nested packages are installed in the order in which they are listed in the primary package, however, if you remove a nested software package, the software packages are removed in the reverse order in which they were originally installed. By default, the nested software packages are processed after the primary software package. There is no limit to the number of levels of nested software packages contained in the primary package. In addition, you can nest software packages that belong to different Tivoli management regions. Software Package Formats When software packages are nested in a primary package, the change management operations performed on the primary software package are also performed on the nested software packages. The nested software packages inherit most of the properties from the primary package. For example, nested software packages inherit the default change management operation, operation mode, and distribution targets of the primary package. However, there are certain properties specified in the nested software package that condition the primary software package. For example, if the committable option is specified in the nested software package, the primary software package must be installed in transactional mode. If the undoable option is specified in the nested software package, the primary software package must be installed in undoable mode. For instructions on nesting software packages, see Nested Packages on page 73. For information about distributing nested software packages, see Distributing Nested Software Packages on page 212. Regardless of the method used to create a software package, the output can be saved in any of the following formats: v Software package file (.sp) v Software package definition file (.spd) v Software package block (.spb) A software package can be opened in the Software Package Editor regardless of the format. You can then choose to resave it in any of the other file types available. For more information about software package definition parameters, keywords, and formats, refer to the Reference Manual for Software Distribution. Software Package (.sp) File A software package saved in this format is the zipped format of an.spd file. It contains only a description of the actions to be performed on the target system and not the files and resources necessary to execute the actions. The files and resources reside on the source host. The software package file format is the default format used by the Software Package Editor. Because the software package in this format is only a description of the software package, it is in the not-built format. Chapter 1. Overview of Software Distribution 15

36 Software Package Formats Software Package Definition (.spd) File The software package definition file is the text version of a software package. An.spd file contains only a description of the objects contained in the package, that is, a sequential list of actions to be executed on the target system and not the actual objects or resources themselves. It consists of a sequence of stanzas, each of which describes an action to be executed. Using a text editor, you can modify an.spd file by manipulating the stanzas, then reopen the file in the Software Package Editor and save it in another format. For example, the.spd file for Microsoft Office 2000 is very long. In the software package file format it is compressed to a much smaller size. A software package in this format is in the not-built format. Software Package Block (.spb) A software package block bundles all the resources necessary to execute the actions contained in the software package into a standard zipped format. At distribution time, the resources do not need to be collected from the source host; they are already contained in the software package block. However, the software package block must reside on the source host. When the software package block is distributed to an endpoint, it is not stored on the endpoint, but is unzipped in the target directory. By unpacking the zipped file immediately, there is no need for additional disk space on the endpoint for the.spb file. A software package that contains all its resources is in the built format. The maximum size of a software package block is 2 GB. Software Package Object A software package object is a software package in either the built (.spb) or not-built (.sp,.spd) format that has been imported into the Tivoli environment. If the software package is in the not-built format, the data to be distributed resides on the source host and is resolved at distribution time. If the software package is in the built format, the software package block must reside on the source host. The software package is catalogued at the Software Distribution server as a software package object in the Tivoli database. Choosing a Software Package Format If you have created a software package using the Software Package Editor on an endpoint or on a managed node, you must choose one of the following software package formats: v The built format (a software package block, using the files on the local machine) v The not-built format (a software package file or software package definition file) Each format has its advantages. For example, if you maintain the software package in the not-built format, you can revise the software package until the moment of distribution. The consolidation of the actions with the files and resources does not occur until distribution, and the most current files on the source host are used to build the package. Also, because a software package in the not-built format does not contain the files and resources to be distributed, it occupies a smaller amount of disk space than a software package block. Alternatively, if you build the software package to create a software package block, you ensure that the data in the software package remains static between distributions at different times. 16 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

37 Tivoli Desktop Operations Tivoli Desktop Operations Policy regions, profile managers, and profiles are mechanisms provided by the Tivoli desktop to help organize resources hierarchically. You use this hierarchy to associate software packages with target systems. Profiles are the resources that are distributed. From the Tivoli desktop, you import a software package into the Tivoli environment by associating it to a Software Distribution profile contained in a profile manager. From the Tivoli desktop you can perform tasks on software packages, such as calculating software package size, converting the software package to different formats, exporting the software package to the.spd file format, and editing the software package by launching the Software Package Editor. You can also perform change management operations such as install, remove, undo, accept, commit, and verify, or perform data moving operations such as send, retrieve, and delete. The interface drives the execution of all the operations supported by the server CLI. See Chapter 9, Preparing a Software Package for Distribution, on page 177 for information about the Tivoli desktop and its functions. Software Distribution Operations Change management and data moving operations are operations you can use on software package objects to fully automate the distribution and installation of software. You can launch operations from any managed node where the necessary components are installed. After you create a software package and catalog it at the Software Distribution server, you can use the following operations to manage how package actions are executed. Software Distribution performs the following change management operations: Install Performs the actions listed in a software package. Remove Uninstalls a software package. Undo Accept Returns the system to its state prior to the last install or remove operation. Deletes the backup package, so the previous operation can no longer be undone. Commit Causes all the updates performed in the preparation phase to take effect. Verify Load Verifies the consistency of the software package and the object on the target system. If the verify operation fails, the software package is placed in an error state. Loads software packages on a repeater depot for subsequent distribution. This operation is valid for only built software packages. Unload Removes software packages from a repeater depot. This operation is valid for only built software packages. These Software Distribution operations can be executed in different modes. See Change Management Operations on page 191 for more information about change management operations and modes. Software Distribution provides the following data moving operations to distribute, retrieve, and delete files from machines in a Tivoli Management environment: Chapter 1. Overview of Software Distribution 17

38 Tivoli Desktop Operations Send Transfers a file from a Tivoli source host to a set of specified Tivoli endpoints in your Tivoli environment. Retrieve Transfers a file from each specified Tivoli endpoint to a Tivoli source host. Delete Deletes a specified file from one or more endpoints. 18 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

39 Chapter 2. Launching the Software Package Editor The Software Package Editor is the Software Distribution software packaging facility. It is a Java-based graphical user interface (GUI) used to create and customize a software package. The Software Package Editor main window displays a graphical tree view of the software package and its contents. Initially, a welcome page is displayed and can be customized according to your company needs. See Customizing the Welcome Page on page 25. For information about installing the Software Package Editor, refer to the Planning and Installation Guide. You can use the Software Package Editor on either endpoints (disconnected mode) or managed nodes (connected to the Tivoli Management Region). On endpoints, you install the Software Distribution Java Endpoint Package Editor and all of the options of the Software Package Editor are enabled. With this component you can create and customize software packages. On managed nodes, although the GUI is identical, not all of the options of the Software Package Editor are available. You use this editor primarily for customizing existing software packages. This section describes how to launch and use the Software Package Editor to create software packages. It includes the following topics: v Launching the Software Package Editor on Endpoints v Launching the Software Package Editor on Managed Nodes on page 21 v Determining the Type of Package You Will Create on page 23 v Customizing the Software Package Editor GUI on page 24 For troubleshooting topics, see Troubleshooting the Software Package Editor GUI on page 305. Launching the Software Package Editor on Endpoints You can launch the Software Package Editor from either the desktop or command line. From the Desktop To launch the Software Package Editor from the desktop on a Windows or OS/2 endpoint double-click the icon labelled Software Package Editor on your desktop, or click Start->Programs->Software Distribution->Software Package Editor. The Software Package Editor Selector dialog is displayed. Copyright IBM Corp. 2002,

40 Launching the Software Package Editor See Determining the Type of Package You Will Create on page 23 for more information about this dialog. You can return to this dialog from the Software Package Editor main window by selecting File->Return to Software Package Editor Selector. From the Command Line To launch the Software Package Editor from the command line complete the following steps: On Windows Endpoints 1. Double-click the icon labelled SWDIS ENV on your desktop to open the Software Distribution disconnected command line window. 2. Type speditor.bat from the command line and press Enter. The Software Package Editor Selector dialog is displayed. See Determining the Type of Package You Will Create on page 23 for more information about this dialog. On Windows endpoints, if you also have the Tivoli desktop installed, you can also launch the editor as described in Launching the Software Package Editor 20 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

41 Launching the Software Package Editor on Managed Nodes. Both methods access the same component with the full Software Package Editor functions for creating and customizing software packages. On OS/2 Endpoints 1. Double-click the icon labelled SWDIS ENV on your desktop to open the Software Distribution disconnected command line window. 2. Type speditor.bat from the command line and press Enter. The Software Package Editor Selector is displayed. See Determining the Type of Package You Will Create on page 23 for more information about this page. On UNIX Endpoints 1. Locate the speditor.sh script located in the speditor_dir/interp_type/classes path where, speditor_dir Is defined in the swdis.ini file. See Base Configuration Information on the Endpoint on page 294 for more information about the swdis.ini file. interp_type Identifies the interpreter type of the endpoint. 2. Type sh. /speditor.sh. The Software Package Editor Selector dialog is displayed. See Determining the Type of Package You Will Create on page 23 for more information about this page. Launching the Software Package Editor on Managed Nodes To launch the Software Package Editor on a managed node (connected to a Tivoli Management Region), complete the following steps: 1. Click the Launch Software Package Editor button on the Software Package Properties dialog. See Software Package Properties on page Select an option from the Software Package Editor Selector dialog. Only the Software Package Templates and General Package options are available on managed nodes. Chapter 2. Launching the Software Package Editor 21

42 Launching the Software Package Editor See Determining the Type of Package You Will Create on page 23. You can return to this dialog from the Software Package Editor main window by selecting File->Return to Software Package Editor Selector. Some of the options on the Software Package Editor GUI installed on managed nodes are not available. The following list details the options that are not available: v The AutoPack menu options v The native installation objects from the Tools menu v The browse (...) buttons. If you edit a software package on a managed node that is not the source host of the software package, you cannot access the source host files by clicking the browse button. If you are launching the Software Package Editor from an empty software package profile, the Create Software Package dialog is displayed first, before the Software Package Editor Selector. Enter the source host name and click Set & Close. The Software Package Editor main window is displayed. If you are launching the Software Package Editor from a software package profile containing a software package in either the built or not-built format, the Software Package Editor main window is displayed. From the Software Package Editor on managed nodes you can view the contents of a software package in the built format, but you cannot edit and save the changes. To edit a software package block using the Software Package Editor, perform the following steps: 1. Convert the software package block to a software package. 2. Edit the software package using the Software Package Editor. 3. Save the changes and select File->Return from the Software Package Editor menu. 4. Convert the software package back to a software package block. If you use this procedure on a system from which the original source files are not accessible, you must convert the software package block to the not-built format. This option saves the source files to a staging directory on the local system, so that the software package block can be rebuilt without access to the original directory. See Converting a Software Package on page 189 for more information. 22 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

43 Determining the Type of Package You Will Create Determining the Type of Package You Will Create This section provides information to help you determine how to get started based on the type of software package you want to create. Before you begin using the Software Package Editor to create your package, determine the answers to the following questions: v Do you want to use AutoPack differencing technology to generate a software package by comparing two successive snapshots of a preparation machine? v Do you want to embed a native packaging object into your software package? v Will your software package be installed on targets of a particular operating system? v Do you want to work with a sample software package and customize it? v Will your software package be installed on targets of several different operating systems? v Do you want to work with an existing software package? Embedding a Native Package into a Software Package To embed native operating system installation images into a software package, select Native Package Technology from the Software Package Editor Selector dialog. This option enables you to select the type of native package technology you want to embed in your software package. The types available depend on the operating system on which the Software Package Editor is running. See Chapter 6, Embedding Native Objects into a Software Package, on page 107 for supported types of native packages. Creating a Software Package with AutoPack To launch a wizard that automatically generates a software package by employing scanning and differencing technology, and comparing two successive snapshots of a preparation machine, select AutoPack Technology from the Software Package Editor Selector dialog. See Chapter 8, Generating a Software Package Using AutoPack, on page 157 for more information about AutoPack. Creating a Software Package using a Template You can filter the main window of the Software Package Editor to include only actions that apply to the type of software package you want to create. Select Software Package Templates from the Software Package Editor Selector dialog, then select the template from the drop-down list. The drop-down list contains target system templates by default. Selecting one of these templates, the Software Package Editor main window displays only the actions relative to the target system selected. You can also create your own template and have it appear in the drop-down list. See Creating a New Software Package Template on page 26. Customizing a Sample Software Package You can view or customize sample software packages categorized by target system type. Select Software Package Samples from the Software Package Editor Selector dialog, then select a sample software package from the drop-down list. You can also create your own sample software package and have it appear in the drop-down list. See Creating a New Software Package Sample on page 26. The creation of the Appsample software package available in the sample drop-down list is described in Creating the Appsample Software Package on page 29. Chapter 2. Launching the Software Package Editor 23

44 Determining the Type of Package You Will Create Creating a Software Package for Mixed Target Types If your software package will be distributed to different types of target systems then select General Package from the Software Package Editor Selector dialog. This options allows you to work with all of the objects and methods available to create your software package. See the scenario Creating the Appsample Software Package on page 29 for an example of this type. Working with an Existing Software Package To open and work with an existing software package, select Open an Existing Software Package, and click the browse (...) button to navigate to and select an existing software package. You can view and modify the contents in the Software Package Editor main window. You can open existing software packages of the following formats: software package (.sp), software package definition (.spd) file, or software package block (.spb). The main window displays all the objects and actions defined in the package in a graphical tree view. Edit the software package and save it with another name so that both the original software package and the edited software package can be used for distribution. You can also choose to save the software package in a different file format (.sp,.spd,.spb). See Saving the Software Package on page 79 for more information about software package formats. All of the methods for creating a software package described in this section are available when you select General Package from the Software Package Editor Selector dialog. Customizing the Software Package Editor GUI There are several ways in which you can customize the Software Package Editor to adapt to your company needs. The following topics are ways you can customize the GUI: v Customizing the Welcome Page on page 25 v Creating a New Software Package Sample on page 26 v Creating a New Software Package Template on page 26 v Setting the Default Path on page 27 To perform any of these tasks, ensure that you are familiar with the directory structure on your system. You may have to modify one or more files. After installing the Software Package Editor, the following files and directories are created on your system: 24 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

45 Customizing the Software Package Editor GUI Table 1. Software Package Editor Directory Structure Path File Description speditor_dir \classes\config SDGui_as400Tem.cfg SDGui_device.cfg SDGui_OS2.cfg SDGui_unix.cfg SDGui_win.cfg nnew_templates.cfg SDGuiTemplate.cfg SPTemplates.cfg Template displays only OS/400 actions in Software Package Editor main window. Template displays only device actions in Software Package Editor main window. Template displays only OS/2 actions in Software Package Editor main window. Template displays only UNIX actions in Software Package Editor main window. Template displays only Windows actions in Software Package Editor main window. Save any new templates you create to this path. See Creating a New Software Package Template on page 26. Template displays all actions in the Software Package Editor. Modify to create your own template. Define any new templates you create in this file in the format: New_Template_Name, NewTemplate_File_Name.cfg SPExamples.cfg See Creating a New Software Package Template on page 26. Define any new samples you create in this file in the format: Sample_Name, Sample_Template.cfg, Sample_Package.sp SDGui_as400Tem.sp SDGui_device.sp SDGui_os2.sp SDGui_unix.sp SDGui_win.sp welcome.html nnew_samples.sp See Creating a New Software Package Sample on page 26. Sample package containing OS/400 actions. Sample package containing device actions. Sample package containing OS/2 actions. Sample package containing UNIX actions. Sample package containing Windows actions. Content of the welcome page is defined in this file. See Customizing the Welcome Page. Save any new sample packages you create to this path. See Creating a New Software Package Sample on page 26. where, speditor_dir represents the directory where the Software Package Editor is installed as defined in the swdis.ini file. See Table 17 on page 295 for more information about the speditor_dir. Customizing the Welcome Page The welcome page is the page of text displayed in the Software Package Editor main window after you launch the Software Package Editor. To modify the welcome page, perform the following steps: 1. Open the welcome.html file located in the path speditor_dir\classes\config with an html file editor. For example, on a Microsoft Windows XP system, this file is located in the following path: Chapter 2. Launching the Software Package Editor 25

46 Customizing the Software Package Editor GUI c:\swdis\speditor\w32-ix86\classes\config\newtemplate.cfg 2. Customize the file as desired and save the file to the same location and with the same name. The customized welcome page will be displayed the next time you launch the Software Package Editor. To not display the welcome page, delete the welcome.html file from the speditor_dir\classes\config path, or rename the file. Creating a New Software Package Sample To create a new sample that can be accessed from the Software Package Editor Selector dialog, perform the following steps: 1. Select the template with which you want to create your sample software package and click OK. Note: The template selected determines the actions you can use to create your sample software package. If you want all actions available to create your sample software package, select General Package from the Software Package Editor Selector dialog, then click OK. The General Package option corresponds to the SDGuiTemplate.cfg file. 2. Create the sample software package and save it to the following location: speditor_dir\classes\config with either the.sp,.spd, or.spb file extension. For example, on a Microsoft Windows XP system, the software package is saved as follows: c:\swdis\speditor\w32-ix86\classes\config\newsample.sp 3. To display NewSample.sp sample software package among the other samples in the Software Package Editor Selector dialog, modify the SPExamples.cfg file located in the config folder. Insert a new line in the file with the name that will appear on the Samples drop-down list, the name of the template.cfg file, and the name of the software package file, each separated by a comma. For example: NewSample Software Package, SDGuiTemplate.cfg, NewSample.sp 4. Launch the Software Package Editor and verify that the NewSample software package is displayed in the Software Package Samples drop-down list. 5. Select the NewSample software package and launch the Software Package Editor main window. Verify that the window correctly displays the sample software package. The sample software package is displayed in the General Package view, that is, with all software package actions displayed. To display the sample software package in the view that corresponds to the template used to create the sample software package, you must create a software package template using the sample created. See Creating a New Software Package Template. You can no longer modify the software package, you must save the package with a different name. Creating a New Software Package Template To create a new template that can be accessed from the Software Package Editor Selector dialog, perform the following steps: 1. Copy the SDGuiTemplate.cfg file located in the speditor_dir\classes\config folder and paste it to the same location. The SDGuiTemplate.cfg file contains all the actions you can use to create a software package. Rename the file, for example, NewTemplate.cfg. 26 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

47 Customizing the Software Package Editor GUI 2. Edit the NewTemplate.cfg file located in the config folder, deleting all the actions that you do not want displayed in the Software Package Editor main window. Only the lines that correspond to the actions you want to be displayed in the Software Package Editor remain. For example, to create a template that allows you to access only Add Directory objects (directories, files, and links) and Add Windows Registry objects (registry keys and values), the NewTemplate.cfg file should contain only the following lines: // // package descriptor // #CmPackage CmAddFSObjectsContainer, A CmAddWinRegistryObjectsContainer, A #CmAddFSObjectsContainer!CmAddFSObjectsContainer, A!CmAddFile, A!CmAddDirectory, A!CmAddLink, A #CmAddWinRegistryObjectsContainer!CmAddWinRegistryObjectsContainer, A!CmAddWinRegistryValue, A 3. Save the file. 4. Edit the SPTemplates.cfg file located in the speditor_dir\classes\config folder by inserting a new line containing the name of the new template, and the name of the.cfg file you just created, separated by a comma. For example: New Template, NewTemplate.cfg 5. Launch the Software Package Editor and verify that the new template is available from the Software Package Templates drop-down list. 6. Select the new template and launch the Software Package Editor main window. Verify that the window correctly displays the objects specified in the template. Setting the Default Path You can set the default path that the Software Package Editor uses when the browse button (...) is clicked from Software Package Editor panels, or when you open or save software packages. Follow these steps to modify the default path: 1. From the Software Package Editor main window, select Default Path from the Settings menu. 2. Enter the default file path in the Default file path text box, or use the browse button to navigate to it. 3. Click OK to save your changes and close the dialog. When you modify the default path the first time, the speditor.ini file is created in the speditor_dir/classes/config path. After the creation of this file, you can alternatively modify the default path by setting the default_file_path key defined in this file. Chapter 2. Launching the Software Package Editor 27

48 28 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

49 Chapter 3. Creating Packages Using the Software Package Editor Creating a Software Package Software Distribution can quickly and reliably deploy software across multi platform networks, which can include UNIX, NetWare, Windows, OS/400, and OS/2 systems at remote sites. Refer to the Release Notes for details about supported platforms for this product. Software package preparation begins at the Software Package Editor window. The window displays a graphical tree view of the software package and its contents. The left pane displays the software package icon. Any actions added to the software package are nested directly below the package icon in hierarchical form. You organize the actions contained in the package in the order in which they are to be executed on the target system. Use the up and down arrow buttons to the right of the toolbar to rearrange the order of the objects in the right pane. The right pane displays the objects contained in the selected object in the left pane. The tabbed toolbar displays additional actions and objects that can be added to the selected item in the tree view. An exclamation mark (!) in the right pane indicates that a condition exists on that particular action. A software package contains a number of actions to be executed on a target machine. These actions can be divided into the following categories: v The add object and remove object actions drive the engine to add the specified object to the system or to remove it from the system. Some objects include adding or removing registry keys, directories, files, and OS/2 desktop objects. For information about adding device objects to the software package, see Chapter 4, Creating a Software Package for Devices, on page 83 v System actions, such as checking disk space, restarting the target machine, adding a signature file to the configuration repository. v Program actions, such as executing a user-defined program; configuration, installation, and distribution (CID) program; InstallShield program; Microsoft Setup program; AIX, Solaris, Linux, and HP-UX package installations. You may have the task of solely preparing software packages and, therefore, are not involved in the distribution process. In this case, you can work from a standalone packaging facility. Software Distribution, makes use of a simplified single-content packaging format called the software package. All of the techniques used to create software packages are based on this single file format. Therefore, a software package created using AutoPack is identical to a package created manually using the Software Package Editor, and both can be edited in the same way. Creating the Appsample Software Package In this section, you will create a sample software package called Appsample on a Windows 2000 system. The Appsample software package consists of typical actions that take place when installing an application on a Windows and OS/2 workstation. Because the package will include mixed actions, that is, actions to be Copyright IBM Corp. 2002,

50 Creating the Appsample Software Package performed on different target operating systems, the General Package option is selected from the Software Package Editor Selector dialog. See Determining the Type of Package You Will Create on page 23 for more information about how to begin creating your package. The Appsample software package is available as a sample software package from the sample package drop-down list on the Software Package Editor Selector dialog. You can select to open it and view it from this dialog. The Appsample software package is also available as a sample package you can select from the Software Package Samples drop-down list on the Software Package Editor Selector dialog. See Customizing a Sample Software Package on page 23. Windows and OS/2 operating system actions are organized in two separate generic containers. Generic containers are used to group actions together that must satisfy the same condition. You add actions to the software package in the order in which they should be executed. The first action in the sample software package is the Check disk space action. This action is executed before all other actions because the execution of the other actions depends on whether there is sufficient disk space on the target machine. If the space requirements are met, the distribution proceeds. If the space requirements are not met, the distribution does not take place and an error event is logged and the administrator is notified. In this scenario, you will add the following actions to create the Appsample software package: 1. Check disk space. 2. Add all files contained in a directory called Appsample. 3. Create a generic container to house various Windows platform-related actions, such as the following: a. Add two system.dll files, one of which is a shared file, and define an inventory signature for it. b. Add a new Windows registry key and value for Windows XP and Windows 2003 target systems. c. Add a new Windows shell folder containing a shortcut on the Windows desktop. d. Make changes to a Windows profile by modifying an.ini file. e. Add a Windows service action. 4. Create a generic container to house various OS/2-related actions, such as the following: a. Create a folder on the desktop containing a program and a shadow. b. Create an OS/2 profile object which adds an item containing a new section and key by modifying an.ini file. c. Add a line of text, two tokens, and a device to the config.sys file. d. Add an execute CID program action. 5. Create an Execute program object whose purpose is to create a log file at the end of the install operation to store information such as a timestamp or version number. 6. Add a restart action that restarts the target system after the install operation of the software package is complete. 30 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

51 Creating the Appsample Software Package These items represent the changes that take place or the actions that are executed on the target machine when the software package is distributed. Some actions require conditions to be set on the execution of the action. For example, certain actions are performed on only particular operating systems. The same software package can have certain actions that are performed on only Windows XP systems and other actions that are performed on only Windows 2003 systems. A condition governs whether an action will be performed or whether it will be skipped for a specific target system. The following sample scenario illustrates how to apply these conditions using the Software Package Editor. Naming the Appsample Software Package When you launch the Software Package Editor, it displays an empty software package icon whose default name is Noname. Begin by naming the software package Appsample. The name of the software package is a property of the software package. You can replace Noname by clicking it and typing Appsample over it, or you can complete the following steps: 1. Right-click the software package icon to display a pop-up menu, then select Properties. OR Select the software package icon, then click the Properties icon from the left toolbar. (To view the name of an icon in the Software Package Editor GUI, hover the mouse pointer over the icon for a few seconds.) OR Select the software package icon, then from the menu click Edit->Properties. The Package Properties dialog is displayed. 2. Specify the name of the software package in the Package name text box of the General properties page. This name is displayed beside the software package icon in the Software Package Editor window. For the purpose of this scenario, enter Appsample in the Package name text box. Chapter 3. Creating Packages Using the Software Package Editor 31

52 Naming the Software Package 3. Leave 1.0, the default value, in the Package version text box. 4. In the Title text box, enter a short description of the package. The remaining tabs in the Package Properties dialog are described in Setting Properties on the Package on page Click OK to return to the Software Package Editor window. 6. Save the software package. You can use the package name as the file name or use a different name. 7. To begin adding actions to the Appsample software package, you can perform one of the following actions: a. Click Edit->Insert to select one of the categories of actions. OR b. Select the appropriate category from the tabbed toolbar and select an icon associated with the tab. OR c. Right-click the software package icon in the left pane then select Insert and the appropriate category from the pop-up menu. Checking Disk Space The necessary disk space required is a parameter of the software package. You can use this action to check the disk space on the endpoint. If the space requirements are met, the distribution proceeds. If the space requirements are not met, the distribution does not occur, an error event is logged, and the administrator is notified. Complete the following steps to add the check disk space action to the Appsample software package: 1. Select the System action tab from the tabbed toolbar, then click the Check disk space icon. The Check Disk Space Properties dialog is displayed. 2. In the Drive text box, specify the drive to be checked in one of the following formats: 32 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

53 Checking Disk Space v drive_letter: v drive_letter:\ v /unix_fs_name On UNIX systems, the check disk space action searches for the file system beginning with the final token of the path specified, and moves to the previous token, until it finds the file system. By default, if no file system is detected, the disk space is checked on root. No warning is issued for those tokens where no file system is detected. 3. In the Volume text box, enter the disk space requirement as an integer and specify the appropriate units of measure in the adjacent list box. 4. Click Add to add the action to the list. You can add more than one check disk space action to the same list. To remove a check disk space action from the list, select it then click Remove. 5. Click Condition to display the Condition Editor dialog. In this dialog, you can apply a restriction to the execution of the check disk space action by defining the circumstances under which the action should be executed. Conditions can be applied as follows: v On individual actions and objects contained in the software package v On the entire software package (package level) For example, to limit the execution of the check disk space action to Windows XP systems only, specify the following expression in the Condition Editor dialog (the single quotes are optional in this example): ($(os_name) =='Windows_NT') AND ($(os_release)==5.1). Note: Single quotes are required for values that contain special characters. The following is an example of required single quotes: $(os_name) =='Win*'. For information about valid values of the os_name variable, refer to the appendix in the Reference Manual for Software Distribution. Click OK to apply the Chapter 3. Creating Packages Using the Software Package Editor 33

54 Checking Disk Space condition to the action and to return to the Check Disk Space Properties dialog. See Setting Properties on the Package on page 61 for information about setting conditions at the package level. Refer to Built-in Variables in the Reference Manual for Software Distribution for a table containing descriptions and accepted values for built-in variables. 6. Click OK to return to the Software Package Editor window. The package contains the check disk space action displayed in the right pane. Adding Directories and Files Use the add directory object action to add directories, files, and links and to set file system object attributes related to the target operating system. In this scenario, you will add an action that adds all files contained in a directory called Appsample to the software package. Begin by adding an add directory action to the Appsample software package: 1. Select the Appsample software package icon in the left pane. 2. Select the Add object tab from the right toolbar and click the Directory icon. The Add Directory Properties dialog is displayed: 3. Enter the following information in the Source group box: a. In the Location text box, enter c:\appsample or click browse (...) to display a file system browser dialog. See Setting the Default Path on page 27 for information about customizing the default path used by the browser dialog. b. In the Name text box, enter *.* to specify that all files contained in the Appsample directory are to be added to the package. The files are installed with their original name into the target directory at installation time. Note: When you specify the name of a source or target file, file and directory names may contain wildcard (pattern-matching) characters. The supported wildcard characters include (*), which matches any string, and (?), which matches any single character. For more information 34 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

55 Adding Directories and Files about specifying file and directory names with pattern-matching characters, refer to the Reference Manual for Software Distribution. 4. In the Destination group box, you find the same information you entered in the Source group box. The destination represents where the specified directory is created on the target system. Delete c:\appsample in the Location text box and use a variable to render this operation more generic for use on different operating systems. Right double-click the Location text box to display the Variable List Editor. 5. Define a new variable and assign a default value. a. In the Name text box, enter target_dir. b. In the Value text box, enter $(system_drive)\appsample. c. Click Set to add the new variable and its value to the list. You can reuse this variable anywhere in your software package. To modify the variable, update it in the Variable List Editor and it will change all occurrences in the software package. Refer to the Reference Manual for Software Distribution for more detailed information about using variables. To render the value of this variable dynamic, see Before Program Example on page 69 for an explanation of how you can change the value of the target_dir variable on individual endpoints by defining a before program that runs on the endpoint. 6. Click OK to return to the Add directory properties dialog. Delete *.* in the destination Name text box, as it is unnecessary in this case. The files are installed with their original name into the target directory at installation time. 7. Set the check boxes in the Add Directory Properties dialog: v The Stop on failure check box is selected by default. Leave it selected to stop the execution of the action if the action fails or if the condition is not met. The execution of the remaining actions in the package continues, Chapter 3. Creating Packages Using the Software Package Editor 35

56 Adding Directories and Files provided that the stop on failure option at the package level is not selected. If the Stop on failure check box is selected at the package level and an error occurs, the remaining actions are not performed and the execution of the package is not completed. v Select the Replace if target is newer check box to replace a target object even if the target object is newer than the source object. On Windows platforms, to determine which file is newer, Software Distribution evaluates the version of the file. If the version of the target file is newer than the source file, the target file is replaced. If the version is not set, or on platforms other than Windows, Software Distribution evaluates the modification time. If the modification time of the target object is more recent than the source object, the target object is replaced. File version support is available if the source host is a Windows machine or if the software package containing the file in question has been built on a Windows machine and imported in the software package block (built) format. v The Replace if existing check box is selected by default. Leave it selected to replace an object that already exists on the target. v Select the Remove if modified check box to flag this object for a subsequent remove operation. During a remove operation of the same software package, the flag indicates to remove the object even if the target object has been modified since the last install operation. v Select the Create if not existing check box to create the directory if it does not already exist on the target system. 8. Click Advanced to specify platform-specific file system attributes. The Add File System Objects Properties - Advanced notebook is displayed. 9. Leave the Create directories check box selected to create directories if they do not already exist on the target system. If you know that the directory already exists, clear this check box so that during an install the directory is not created and during an undo operation the directory is not removed. 36 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

57 Adding Directories and Files 10. Leave the Remove empty directories check box selected to remove empty directories when performing a subsequent remove operation of this software package. 11. Select the Descend directories check box to add the entire directory tree to the software package. If it is not selected, only the files listed below the top-level directory are added. Note: If the Descend directories check box is selected and Is inventory signature is set to Restricted, in the case the files selected as signatures are not valid, you will receive a warning message for each invalid file present in the nested directories. 12. Select the Rename if locked check box to temporarily rename files that are in use by another application. For Windows platforms, during an install an attempt is made to replace or rename the file under the same directory as the locked file and the distribution completes successfully without having to wait for a reboot of the system. The temporary file is removed during the next system reboot. During a remove operation, the locked file is removed during the next system reboot. For OS/2 systems, only.exe and.dll files are supported. The locked file is closed so that it can be replaced with the file bundled in the software package. During a remove operation, the locked file is closed so that it can be removed from the target system. If the file cannot be renamed or replaced, the distribution fails. The Rename if locked attribute is not supported on OS/400 endpoints. 13. Click OK to confirm the file system object properties selected. For more information about the file system attributes in this dialog, refer to the online help documentation or the Reference Manual for Software Distribution. 14. Click OK to add this action to the software package. Select the software package icon in Software Package Editor window to display the Add directory object action. Adding Windows Platform Actions to a Generic Container The following actions to be added to the Appsample software package are all Windows platform-related actions. You can group related actions together in a generic container and set a condition on the entire container that governs the execution of the contained actions. Complete the following steps to add a generic container to the software package that contains Windows platform-related actions. 1. Select the Appsample software package icon in the left pane of the Software Package Editor window. 2. Click Container on the tabbed toolbar and select the Generic container icon. The Generic Container Properties dialog is displayed. Chapter 3. Creating Packages Using the Software Package Editor 37

58 Adding Windows Platform Actions to a Generic Container 3. In the Name text box, enter a descriptive string such as Windows platform actions. Before you add this container to the software package, you must set a condition on the entire container. Click Condition to display the Condition Editor. 4. Enter the following expression to satisfy all Windows actions that will be added to this container: $(os_name) LIKE Win* then click OK. Click OK to add the generic container to the software package. An exclamation mark in the right pane indicates that a condition has been set on the generic container. Adding Windows Operating System Directories and Files Next, you will add an action that adds two system.dll files found on the source machine. One of the files is a shared file. Because many applications use the same resources, shared files and directories must be identified in the software package to prevent them from being removed when an application is removed. If a shared resource in a software package is found to exist on the target, the default is to maintain the latest version of the shared resource. 1. Select the Windows platform actions icon in the left pane, then click Add object->directory from the right toolbar. The Add Directory Properties dialog is displayed. 38 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

59 Adding Windows Directories and Files 2. In the Source group box, enter the parent directory c:\winnt in the Location text box. Enter the subdirectory system32 in the Name text box. 3. In the Destination group box, delete the text in both the Location and Name text boxes. Right double-click the Location text box to display the Variable List Editor dialog. Select the $(system_dir) variable to represent the directory where the file will be installed on the target machine. Click OK. 4. Click OK to add the add directory action to the software package. Select the Windows platform actions generic container icon in the left pane to display the add directory action it contains. 5. Specify the file to be added to the target system by nesting an Add file action in the add directory action. Select the Add directory action in the left pane, then select the File icon from the Add object tab on the toolbar. The Add File Properties dialog is displayed. Chapter 3. Creating Packages Using the Software Package Editor 39

60 Adding Windows Directories and Files 6. In the Source group box, enter App32.dll in the Name text box. 7. To define an inventory signature for the App32.dll file, select one of the following options from the Is inventory signature pull-down: Restricted Select this option if you want to consider the file as a signature, but only if the signature has already been created in the Inventory database. Some files cannot be specified as signatures. A check is performed to verify whether the file system object is valid for an inventory signature, a warning message is returned if it is not. The file is a valid signature if it meets the following criteria: Yes No v It is an executable or a DLL. v It is not a temporary file. v It is not a shared file. v It does not belong to a system directory or a common files directory. Consider the file as a signature and create it if it is not already present in the Inventory database. The file is not an inventory signature (default). For more information about inventory signatures, see Exchanging Information between Software Distribution and Inventory on page If you set Is inventory signature to Yes, then you can also define a description and the version number of the software to be installed in the Description and Version text boxes. 9. To mark this file as shared complete the following steps: a. Click Advanced and select the Is shared check box from the General page of the Add File System Objects Properties - Advanced notebook. This 40 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

61 Adding Windows Directories and Files option specifies that the file is shared between multiple software packages. It prevents the deletion of the file when one of the software packages in which it is contained is removed. b. Click OK to return to the Add File Properties dialog, then click OK again to save the changes and close the dialog. The Add File action is added to the software package. When you select the add directory action in the left pane, the add file action is displayed in the right pane of the Software Package Editor main window. 10. To manage how shared files contained in the software package will be handled when the installed package is subsequently removed, define a sharing control option as follows: a. Select the software package icon in the left pane, and click the Properties icon from the toolbar. The General page is displayed by default. See General Properties on page 62 for more information about general package properties. b. Select the Only_shared option from the Sharing control drop-down list. If the software package is subsequently removed, files flagged by the Is shared option, that were already present on the target prior to the distribution of the software package, are not removed. For an explanation of all the sharing control options, see General Properties on page 62. Click OK to save the changes and close the dialog. 11. Add a second.dll file to the same directory. You can either repeat the same process and select the Add file icon from the Add object tab on the toolbar, or you can use the following timesaving procedure: a. Right-click the add file action just added in the right pane, then select Copy from the pop-up menu. b. Right-click system32, the add directory action, in the left pane, then select Paste. An identical add file action is added to the add directory action. c. Select the second add file action and select the Properties icon from the left toolbar. Chapter 3. Creating Packages Using the Software Package Editor 41

62 Adding Windows Directories and Files The Add File Properties dialog is displayed. You can also add more than one file or directory at the same time by right-clicking the Add directory action and selecting Insert->Multiple file/directory. A file system browser is displayed. Select any number of files and directories and click Add. Click OK to add the add file and directory actions to the software package. 12. Change the file name from App32.dll to Apprun32.dll. Click Advanced, then deselect the Is shared check box, as this is not a shared file. 13. Click OK to add the second file to the add directory action, then select it to display the files in the right pane. Adding Windows Registry Objects In more recent Windows versions,.ini files have been replaced by the Windows registry to store configuration information regarding the user, the hardware, and the programs installed. Many applications continue to use.ini files for backward compatibility. Windows operating systems refer to the registry during operation. The Appsample software package scenario demonstrates modifying settings in the system registry. For the purpose of this example, information regarding the installation directory for the Appsample application will be stored using the Windows registry action. Complete the following steps to add Windows registry objects to the software package: 1. Select the Windows platform actions generic container icon in the left pane of the Software Package Editor window. 42 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

63 Adding Windows Registry Objects 2. From the Add object tab on the toolbar, click the Windows registry key icon. The Add Windows Registry Key Properties dialog is displayed. 3. Select HKEY_LOCAL_MACHINE in the Hive drop-down list. 4. Specify the Parent Key and the Key. Enter SOFTWARE\Tivoli in the Parent key text box and enter Appsample in the Key text box. 5. Select the Override permissions check box to temporarily override access permissions for adding or removing protected registry keys and values. Access permissions are restored after the operation is completed. 6. Apply a condition to this particular action so that it is only performed on Windows 2003 and Windows XP machines. Click Condition in the upper right corner of the dialog to display the Condition Editor dialog. Enter the following expression to satisfy the restriction: ($(os_name) == Windows_NT) AND ($(os_release) >=5.1). For information about valid values of the os_name variable, refer to the appendix in the Reference Manual for Software Distribution. Click Check to verify that the expression is valid. Click OK to set the condition on the object. Chapter 3. Creating Packages Using the Software Package Editor 43

64 Adding Windows Registry Objects 7. Click OK to add the Windows registry object to the software package. The Software Package Editor displays the Windows registry key. 8. To add a subkey to the Appsample Windows registry key, select the Appsample Windows registry key icon. From the tabbed toolbar, click the Windows registry key icon from the Add object tab. The Add Windows Registry Key Properties dialog is displayed. 9. Enter 1.0 as the subkey name in the Key text box. 10. Click OK to add the subkey to the Appsample key. 11. To assign a value to the subkey, select the 1.0 subkey, then select Value from the Add object tab. The Add Windows Registry Value Properties dialog is displayed. 12. Enter InstallationDirectory in the Name box. 13. From the Type drop-down list, select the appropriate type of value (String, Binary, DWORD, Multistring, or Expand String). Select Expand String from the drop-down list. 14. To enter the value in the Data text box, click Edit. The Data editor dialog is displayed. Use the same variable defined in Adding Directories and Files on page 34 by right double-clicking the Value text box. Select the $(target_dir) variable from the Variable List Editor dialog and click OK to save the data 44 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

65 Adding Windows Registry Objects and return to the Data editor dialog. To add this value to the Data text box, click OK. To modify this value, click Edit. 15. In the Position drop-down list, specify where the new value should be placed in the system registry. Select Replace to substitute the value on the target system. 16. Leave the Replace if existing check box selected to replace the value if it already exists in the system registry. 17. Click OK to display the Software Package Editor window and view the value added to the key. Adding Windows Shell Objects Adding Windows shell objects involves creating folders and links to programs. You can use this action to configure a target machine s desktop. Complete the following steps to create a shortcut or link to the Appsample application in a new folder, Tivoli Appsample, located on the desktop. 1. From the Software Package Editor window, select the Windows platform actions generic container icon. 2. From the Add object tab on the toolbar, select the Windows shell folder icon. The Add Windows Shell Folder Properties dialog is displayed. 3. Use a built-in variable to specify the location of the folder. Right double-click the Location text box to display the Variable List Editor dialog. 4. Select the $(all_users_shell_desktop) variable and click OK to place the variable in the Location text box. 5. Enter TivoliAppsample in the Folder text box. This will be the name of the folder on the target system. 6. In the Folder type group box, select Common if the folder and all its contained commands are common to all users. Select Personal, to specify that the folder and its contents apply to the logged-on user only and to install them at the next user logon by the user profile update program. 7. Select the Create if not existing check box to create the new folder if it does not already exist on the target system. 8. Before you add the folder to the software package, set a condition on this particular action so that it is performed only on Windows 2000 and Windows 2003 systems. Click Condition in the upper right corner of the Add Windows Chapter 3. Creating Packages Using the Software Package Editor 45

66 Adding Windows Shell Objects Shell Folder Properties dialog to display the Condition Editor dialog. 9. Enter the following expression in the dialog: ($(os_name) == Windows_NT) AND ($(os_release) ==(5.0 OR 5.2)). Click OK to set the condition on the Windows shell folder. 10. Click OK to add the Windows shell folder to the software package. 11. Add a link to the Windows shell folder. Select the Tivoli Appsample folder icon in the left pane of the Software Package Editor window, then click the Link icon from the Add object tab on the toolbar. The Add Windows Shell Link Properties dialog is displayed. 12. In the Display name text box, enter Appsample 1.0 as the name contained in the new folder, Tivoli Appsample, on the desktop. 13. In the Command text box, indicate the full path to the executable file that launches the application. Specify part of the path using the variable defined in Adding Directories and Files on page 34. Right double-click the Command text box to display the Variable List Editor dialog. Select the $(target_dir) 46 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

67 Adding Windows Shell Objects variable, then click OK to insert the variable in the Command name text box. Complete the full path to the command as follows: $(target_dir)\bin\appsample.exe 14. Click OK to add the link to the folder and return to the Software Package Editor window. Adding Windows Profile Objects You can use the Windows profile objects to update Windows.ini files. Windows.ini files store configuration and default settings, such as the computer s hardware, or environment preferences such as fonts and background color. You update.ini files by manipulating sections that contain values associated to keys. In the following example, you create a new section containing an installation directory key. Complete the following steps to add Windows profile objects to the software package. 1. Select the Windows platform actions generic container icon. 2. From the Add object tab on the tabbed toolbar, click the Windows profile icon. The Add Windows Profile Properties dialog is displayed. 3. Enter the full path to the appsample.ini file in the File name text box. Use a built-in variable to specify part of the pathname by right double-clicking the File name text box. Select the $(system_root) variable and click OK to add the variable to the text box. Complete the file name entry as follows: $(system_root)\appsample.ini. 4. Set a condition on this action to restrict its execution to Windows 2000, Windows 2003, and Windows XP targets. Click Condition in the upper right corner of the dialog to display the Condition Editor. Chapter 3. Creating Packages Using the Software Package Editor 47

68 Adding Windows Profile Objects 5. Enter the following condition: $(os_name) == Windows_NT. Click OK to set the condition and return to the Add Windows Profile Properties dialog. 6. Click OK to add the Windows profile to the software package. 7. To add a new section to the appsample.ini file, select the Windows profile icon and click the Section icon from the Add object tab on the toolbar. The Add Windows Profile Section Properties dialog is displayed. 8. In the Section name text box, enter 1.0 as the name of the section. Click OK to add the section to the Windows profile. 9. To add items to the section, select the 1.0 section icon, then select the Item icon from the Add object tab on the tabbed toolbar. The Add Windows Profile Item Properties dialog is displayed. 48 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

69 Adding Windows Profile Objects 10. In the Key text box, enter InstallationDirectory as the key contained in the section. 11. Enter the $(target_dir) variable defined in Adding Directories and Files on page 34 in the Value text box, which represents the value associated with the key. 12. Leave the Duplicate check box selected to update the value of the key if it should already exist on the target system. 13. Click OK to add the key to the software package. Adding Windows Services The Windows service action can either install or remove a service from a Windows target operating system. To install the Tivoli Appsample Service on the target system, complete the following steps: 1. Select the Windows platform actions generic container icon in the Software Package Editor window. 2. From the Add object tab on the tabbed toolbar, click the Windows service icon. The Add Windows Service Properties dialog is displayed. 3. Enter the name of the service to be installed on the target system. In the Name text box, enter TivoliAppsample. Chapter 3. Creating Packages Using the Software Package Editor 49

70 Adding Windows Services 4. In the Path text box, enter the path to the service. Use the variable defined in Adding Directories and Files on page 34 to express part of the pathname. Right double-click the Path text box. The Variable List Editor dialog is displayed. Select the target_dir variable from the list, then click OK to enter the variable in the Path text box. Complete the pathname as follows: $(target_dir)\bin\appsrv.exe. 5. In the Display name text box, enter Tivoli Appsample Service. 6. Click OK to add the Windows service action to the software package. The Software Package Editor window displays the action in the right pane. Adding OS/2 Platform Actions to a Generic Container You can group OS/2 platform-related actions together in a generic container and set a condition on the entire container that governs the execution of all of the contained actions. You created a similar container for Windows-related actions in Adding Windows Platform Actions to a Generic Container on page Select the Appsample software package icon in the left pane of the Software Package Editor. 2. Click Container on the tabbed toolbar and select the Generic container icon. The Generic Container Properties dialog is displayed. 3. Enter OS/2 platform actions in the Name text box. 4. Click Condition and set the following condition on the generic container using the Condition Editor: $(os_name) == OS/2. Click OK. 5. Click OK to add the OS/2 platform actions generic container to the software package. The Software Package Editor window displays the empty container. Adding OS/2 Desktop Objects OS/2 desktop folders function much like containers that are used to organize objects, programs, documents, and other folders. The folders on the desktop represent the directories in the file system. To add a folder to the desktop containing a program and a shadow, complete the following steps: 1. Select the OS/2 platform actions icon. Select the OS/2 desktop folder icon from the Add object tab on the tabbed toolbar. The Add OS/2 Desktop Folder Properties dialog is displayed. 50 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

71 Adding OS/2 Desktop Objects 2. Right double-click the Location text box to express the location of the folder using a built-in variable. Select the $(os2_desktop) variable from the Variable List Editor, then click OK. 3. Enter Tivoli Appsample in the Title text box. 4. Enter <TIVOLI_APPSAMPLE> in the OID text box. 5. Click OK to add the OS/2 folder action to the software package. 6. To add a program to the folder, select the Tivoli Appsample OS/2 folder in the left pane and select the Program icon from the Add object tabbed toolbar. The Add OS/2 Desktop Program Properties dialog is displayed. 7. Enter Appsample as the title of the program. 8. In the Command text box, enter the path to the program. Express part of the path using the variable defined in Adding Directories and Files on page 34 so that the entry is $(target_dir)\bin\appsample.exe. 9. In the Working directory text box, enter the working directory of the program. Enter $(target_dir)\bin. 10. Click OK to add the program action to the OS/2 folder action. 11. To add a shadow object to the OS/2 folder, select the Tivoli Appsample icon in the left pane. From the Add Object tab on the toolbar, select Shadow. The Add OS/2 Desktop Shadow Properties dialog is displayed. Chapter 3. Creating Packages Using the Software Package Editor 51

72 Adding OS/2 Desktop Objects 12. This particular shadowed object does not have an associated object identification (OID); therefore, select the Title radio button and complete the Location and Title text boxes. a. In the Location text box, use the variable, $(target_dir) defined in Adding Directories and Files on page 34. b. In the Title text box, enter README.TXT for the title of the shadowed object. 13. Click OK to add the shadowed object to the OS/2 folder. The Software Package Editor displays the shadowed object action. Adding OS/2 Profile Objects You can use OS/2 profile objects to update.ini files that contain configuration information. In the following example, you add a new item containing installation information to the Appsample.ini file. Complete the following steps to add OS/2 profile objects to the software package. 1. Select the OS/2 platform actions generic container icon. 2. From the Add object tab, click the OS/2 profile icon. The Add OS/2 Profile Properties dialog is displayed. 3. Enter the path to the.ini file in the File name text box. Use the $(system_root) variable to express a portion of the pathname by right double-clicking the text box. Select the variable and click OK. Complete the entry to read 52 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

73 Adding OS/2 Profile Objects $(system_root)\appsample.ini. Click OK to add the OS/2 profile to the software package. The Software Package Editor displays the OS/2 profile action. 4. To add an item to the OS/2 profile, select the OS/2 profile icon in the left pane. From the Add object tab, select the Item icon. The Add OS/2 Profile Item Properties dialog is displayed. 5. Enter 1.0 in the Section text box. 6. Enter InstallationDirectory as the key name in the Key text box. 7. In the Value text box, use the variable $(target_dir), defined in Adding Directories and Files on page Use the String default value selected in the Type group box. The key value, InstallationDirectory, is a string-type value. 9. Select Replace from the Position drop-down list to replace the item in the appsample.ini file. 10. Click OK to add the item to the OS/2 profile. The Software Package Editor displays the OS/2 profile item. Adding Text File Objects Adding text file objects to a target system enables you to manipulate any type of text file, including DOS configuration files such as autoexec.bat and config.sys, by adding lines, command lines, or tokens to the file. The following example illustrates how to modify the config.sys file on an OS/2 target machine by adding a text line to the file, adding a token to the SET PATH and LIBPATH keys, and adding a command line to the file. Complete the following steps to add text file objects to the software package: 1. Select the OS/2 platform actions icon in the left pane, then from the Add object tab, click the Text file icon on the toolbar. The Add Text File Properties dialog is displayed. Chapter 3. Creating Packages Using the Software Package Editor 53

74 Adding Text File Objects 2. Express part of the file name using a built-in variable. Right double-click the File name text box and select the $(system_drive) variable from the Variable List Editor dialog. Click OK to add the variable to the text box, then complete the file name as follows: $(system_drive)\config.sys. 3. Click OK to add the text file object to the software package. The Software Package Editor window displays the text file object contained in the software package. 4. To add a text line to the config.sys file, select the text file icon in the left pane, then select the Line icon from the Add Object tab on the toolbar. The Add Text File Line Properties dialog is displayed. 5. In the Text text box enter the following line of text to be added to the config.sys file: REM - BEGIN TIVOLI APPSAMPLE SECTION. 6. Indicate that the line should be placed at the end of the text file by selecting End from the Position drop-down list. 7. Click OK to add the text line action to the text file object. The Software Package Editor displays the text file line action. 8. To add a token to the text file, select the text file icon in the left pane, then select the Token icon from the Add Object tab on the toolbar. The Add Text File Token Properties dialog is displayed. 54 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

75 Adding Text File Objects 9. In the Text text box, specify the token value to be added to the SET PATH key. Use the variable $(target_dir), defined in Adding Directories and Files on page 34, then complete the entry in the Text text box to read $(target_dir)\bin. 10. In the Key text box, enter SET PATH. This value instructs the operating system to include $(target_dir)\bin in its search. A semicolon is automatically inserted before this value. 11. Use the End default value in the Position box to specify that the token will be inserted at the end of the corresponding line of the config.sys file. 12. In the Token separator text box, enter the character to use as the token separator. The default value is semicolon (;). 13. Click OK to add the token action to the software package. The Software Package Editor displays the add token action. 14. Add a second token that adds a directory to the LIBPATH key. The OS/2 target operating system will include the directory in its search when loading dynamic link libraries. Select the text file object in the left pane, then select the Token icon from the Add object tab on the toolbar. The Add Text File Properties dialog is displayed. 15. In the Text text box, enter $(target_dir)\dll. In the Key text box, enter LIBPATH. Use the End default value in the Position box and click OK to add the second token to the text file. The Software Package Editor displays the two tokens in the right pane. 16. Next, add a driver to the DEVICE command. Select the text file icon in the left pane and select the Command line icon from the Add object tab on the toolbar. The Add Text File Command Line Properties dialog is displayed. Chapter 3. Creating Packages Using the Software Package Editor 55

76 Adding Text File Objects 17. In the Text text box, enter DEVICE=$(target_dir)\sys\Appsamp.sys, which is the line of text to be added to the config.sys file that contains the path to the driver file. Use the $(target_dir) variable defined in Adding Directories and Files on page 34 to express part of the text. 18. In the Key text box, enter the file name of the driver file. Enter Appsamp.sys in the text box. 19. In the Command text box, enter DEVICE. 20. In the Position text box, use the End default value to add this command to the end of the config.sys file. 21. Click OK to add the command line action to the text line action. The Software Package Editor displays the command line action. Adding an Execute CID Program Action The IBM configuration, installation, and distribution (CID) architecture provides for the remote, unattended installation and configuration of OS/2 applications. The following example defines an execute CID program action that installs the perl open-source language on an OS/2 system. To add an execute CID program action, complete the following steps: 1. Select the Appsample software package icon in the left pane and click the Program tab. 56 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

77 Adding Text File Objects 2. Click the Execute CID Program icon from the toolbar. The Execute CID Program Properties dialog is displayed. 3. In the Caption text box, enter Perlinstall. The caption is the descriptive name of the program to be installed. If you do not specify a name, the default value is the file name entered in the Path text box. 4. With the Install tab selected, enter $(system_drive)\perl.exe in the Path text box. 5. Click OK to add the execute CID program action to the software package. The Software Package Editor displays the program action. Adding an Execute Program Action You can specify user-defined executable programs to be executed during particular change management operations. Software Distribution returns standard error and standard output to the log file. This example adds a user program action that, when executed, creates a log file at the end of the install operation. For more information about change management operations, see Change Management Operations on page 191. To add an execute program action, complete the following steps. 1. Select the Appsample software package icon in the left pane and click the Program tab. Chapter 3. Creating Packages Using the Software Package Editor 57

78 Adding an Execute Program Action 2. Select the Execute program icon to display the Execute Program Properties dialog. 3. In this dialog, configure the software package to execute the user program log_aft.exe after the install operation is complete. In the Caption text box, enter a program name. If you do not specify a name, the default value is the file name entered in the Path text box. 4. With the Install tab selected, enter the pathname to the executable file in the Path text box. Use the $(temp_dir) built-in variable to express a portion of the path name. Right double-click the Path text box and select the $(temp_dir) variable from the Variable List Editor dialog. Click OK to add the variable to the Path text box. Complete the pathname as follows: $(temp_dir)\log_aft.exe. 5. Select Bootable to manage programs that can execute a reboot. Specify the maximum number of times the program must be re-executed after it reboots in the Retry text box. 6. In the Corequisite Files box, click Add to specify one or more files or directories that must be downloaded together with the program during execution. After execution, these files are deleted. 7. The exit code settings control the execution of the subsequent action in the software package. In the Exit Code box, the range of program completion codes are specified as a minimum and maximum value in hexadecimal format. The minimum and maximum values can range from 0 to (0x0, 0xffff). For a SUCCESS exit code, the default is 0. To set the minimum and maximum range, click the text box in the Min or Max column and type a valid hexadecimal value. To set an exit code, click the text box in the Exit Code column and select an option from the scrolling list. To add 58 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

79 Adding an Execute Program Action an exit code to the list, click Add. Ensure the minimum and maximum range is set to an available interval between 0 and Refer to the execute user program action in the Reference Manual for Software Distribution for information about the various exit codes that can be returned and their effect on program operations. See also Adding an Execute Program Action on page 57 for information about software packages containing execute program actions that are distributed to devices. See also User Program Timeout on page 308 for information about specifying a timeout value for user programs. 8. Click OK to add the execute program action to the software package. The Software Package Editor displays the program action. Adding a Restart Action To complete the Appsample software package, add a restart action as the final action in the package. Software package actions are executed sequentially, in the order displayed in the Software Package Editor window. In this example, add a restart action that will restart the target computer after the install operation of the software package is complete. For more information about operations you can perform on software packages, see Change Management Operations on page Complete the following steps to add the restart action. 1. Select the Appsample software package icon in the left pane. Click the System action tab from the right toolbar, then click the Restart icon. The Restart Properties dialog is displayed. 2. The restart action is executed in relation to four change management operations: install, remove, undo, and commit. In the Restart Properties dialog, you can select an option in one of the operation group boxes or select options from all three group boxes. For example, in the Restart during install box, you select None so that the target system is not restarted during an install operation. You select After to perform the restart after the execution of the last action contained in the software package. You select Immediately to perform the restart action immediately, the remaining sequential actions contained in the software package are executed after the restart action is complete. Keep the default selection and click OK to return to the Restart Properties dialog. Select the Force check box to specify that the reboot action on the endpoint must be forced. This option is valid only on Windows systems. This option interacts with the timeout option, as described in the following list: Chapter 3. Creating Packages Using the Software Package Editor 59

80 Adding the Restart Action v If the timeout is set to -1 and the Force check box is not selected, a soft reboot is invoked and, if it fails, Software Distribution retries for an infinite time. v If the timeout is set to -1 and the Force check box is selected, a hard reboot is performed immediately. v If the timeout is set to 0 and the Force check box is not selected, a soft reboot is invoked. If the reboot fails, the distribution fails after the timeout expires. v If the timeout is set to 0 and the Force check box is selected, a soft reboot is invoked and, in case it fails, a hard reboot is performed after the timeout expires. The Timeout box specifies the number of seconds Software Distribution must wait before the reboot fails. If a retry interval occurs during this timeout, the distribution interrupts and the checkpoint and restart feature is used to retry later. The default value is -1. See Checkpoint Restart Service for Network Failure or Power Interruptions on page 216 for more information about the checkpoint and restart feature. See Setting Timeout Values for a Distribution on page 307 for more details about the timeout. Note: The restart action is ignored on all UNIX platforms, and for transactional operations on all other platforms. 3. Click OK to add the restart action to the software package. The Appsample software package scenario is complete. The Appsample Software Package The complete Appsample software package includes the following actions and objects: 1. Check disk space 2. File system objects 3. Windows generic container v File system objects v Windows registry objects v Windows shell objects v Windows profile objects v Windows service action 4. OS/2 generic container v OS/2 desktop object v OS/2 profile object v Text file objects v Execute CID program 5. Execute program 6. Restart action 60 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

81 Adding the Restart Action To save the software package, see Saving the Software Package on page 79. If you have all the source files on the endpoint machine, you can build the software package (save in.spb format) and then perform a test by issuing the wdinstp disconnected command line interface command to install the package locally. Then use the wdlssp command which produces a list of software packages installed on the endpoint to check if the Appsample software package installed successfully. Refer to the Reference Manual for Software Distribution for more information about disconnected command line interface commands and software package change management states. Changing the Order of Objects in the Software Package You can control the order in which the actions contained in a software package are executed during the distribution to the target system. To rearrange the order of the actions to be executed, select the action in the right pane and use the up and down arrows to the right of the right pane. It may be necessary to use the up and down arrows when adding a new action to an existing software package. The new action is automatically added to the bottom of the sequential list of actions in the Software Package Editor and, therefore, will be the last action to be executed on the target system. Use the arrows to move the action to the appropriate point of execution. Setting Properties on the Package To set package-level properties, use the Software Package Editor or the command line. From the Software Package Editor window, select the software package icon in the left pane and select Properties from the Edit menu or toolbar, or right-click to display a pop-up menu. For instructions on setting software package properties from the command line, refer to the Reference Manual for Software Distribution. Software package properties define the following information about the software package to be distributed: Chapter 3. Creating Packages Using the Software Package Editor 61

82 Setting Properties on the Package v General options, including the name, version, versioning and package types, dependency rules, creation time, and modification time of the software package. v The source host from which the source files and directories are distributed. v Programs you can run before and after the change management operation is processed on the endpoint. v Programs to be run before or after the build operation for different target platforms. v Server execution modes, default operations, and operation modes. v Log information and notification behavior about the software package distribution and platform-specific options to handle user and group ownership of files on the UNIX platform. v A description and copyright information about the software package. v Built-in and user defined variables to be used in the objects contained in the software package. v Nested software packages contained in the primary software package. You can also set conditions at the package level. The Condition button on the Package Properties dialog enables you to set a condition at the package level. Package-level conditions are considered before lower-level conditions. If a package-level condition is not met, the package is not installed and an error message is sent. If the package-level condition is met, but a lower-level condition is not met, the package will install successfully except for those objects whose conditions were not met. Refer to the Reference Manual for Software Distribution for more detailed information about using conditions. General Properties On the General page, specify unique information that defines and identifies the software package. 1. Enter a unique name in the Package name text box. 62 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

83 Setting Properties on the Package 2. In the Package version text box, enter the version string. The version string can contain up to 16 alphanumeric characters and can be separated into substrings using dots (.). The dots are included in the total length of the string. Refer to the Reference Manual for Software Distribution for more information about software package name and version syntax. 3. Select a Version check. SWD turns version checking on. None turns version checking off. 4. If you selected SWD for the Version check, you must select a Package type which determines the method of version checking, as follows: Refresh The package cannot be installed if a later version of the package is already present on the target. Patch The package cannot be installed if the product installed on the target does not have the same base version as the patch to be applied. See software package version checking in the Reference Manual for Software Distribution. 5. If you want to define hardware and software prerequisites for the software package, click Dependency. See The Dependency Editor on page Enter a title for the package in the Title text box. The title is a longer name associated with the package and is used mainly for display purposes. 7. Select the History reset check box to erase the software history of all software packages already installed on the endpoint, if the package is installed successfully. 8. Leave the Stop on failure check box selected to stop the distribution to a target if the execution of an action fails. (The distribution continues for other targets.) If you do not select this box, errors are logged as specified in the Log file page of the Package Properties dialog, and the distribution continues, if possible. 9. Software Distribution can perform checks on the existence of shared files. Use the options in the Sharing control drop-down list to manage how shared objects are handled when an installed software package is subsequently removed: None A check is not performed on objects that are already present on the target system and distributed with the software package. When the software package is subsequently removed, all the distributed objects are removed. Only_shared A check is performed only on objects that have the Is shared option selected. When the software package is subsequently removed, the objects are not removed if they were already present on the target prior to the distribution of the software package. Auto A check is performed on all objects distributed with the software package. When the software package is subsequently removed, objects contained in the software package that were already present on the target prior to the distribution are not removed. 10. Creation time and Modification time are automatically generated and assist in identifying the software package. Chapter 3. Creating Packages Using the Software Package Editor 63

84 Setting Properties on the Package The Dependency Editor Using the Dependency Editor, you can create an expression that defines prerequisites for executing install, remove, and undo actions defined in the software package. You can build a complex expression that includes any number of Hardware-discovered variables and multiple occurrences of the $(installed_software) variable. See Defining Dependency and Conditions in the Editing the Software Package Definition File chapter of the Reference Manual for Software Distribution. To build a dependency expression, perform the following steps: 1. Define a variable. To define Hardware-discovered variable, enter the names of the Hardware-discovered table and of the field within the table in the Table and Field text boxes, then click Add. To define a $(installed_software) variable, click Add installed software The variable you specified appears in the expression box at the top of the dialog. 2. Click one of the operators shown in the lower section of the dialog. 3. Click in the expression box and enter a constant. You add the boolean constants, True and False, to the expression, by clicking the appropriate button in the lower section of the dialog. 4. If you want to define a complex expression, click AND, OR, AND and NOT, or OR and NOT, then add another variable, operator, and constant. Note: You can check the syntax of the expression, by clicking Check. 5. When the expression defines all the software and hardware prerequisites you want to include, click OK to return to the Package Properties dialog. Server Options On the Server options page, set the source host and program options. See Software Package Properties on page 186 for more information about 64 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

85 Setting Properties on the Package server-related properties. To set server options from the command line interface, refer to the wsetspgs command in the Reference Manual for Software Distribution. Setting Server Options To set the server options, select the Server options tab from the Package Properties dialog. The following dialog is displayed: 1. In the Name text box, specify the source host machine on which the source files referenced in the software package reside. 2. In the SPB path text box, specify the complete path where the software package block resides. This option is enabled only if you are running the Software Package Editor on an endpoint. 3. In the Stage area text box, specify the complete path to the stage area, which is the working directory of the distribution server. This directory is created during the distribution and erased after the distribution is complete. 4. In the Before build group box, specify any programs to be run on the source host machine before the building of the package takes place. The program is executed on the source host prior to the install operation on the target machine. In the After build group box, specify any programs to run on the source host after the build has taken place. For example, if some files required to perform the build are located on a remote drive, use a before build program to mount the remote drive before the build takes place. a. Enter the path and file name in the Program name text box. b. Enter files that the program requires input from, during execution, in the Input file name text box. c. Set the user identification under which to run the before and after programs in the UID text box. d. In the Environment text box, specify the environment variables for the programs specified in the Before build or After build group boxes. e. Select the Skip distribution on error check box to skip distributing the software package to a subscriber if the Before build program fails and returns a non-zero exit code. Chapter 3. Creating Packages Using the Software Package Editor 65

86 Setting Properties on the Package Setting Advanced Server Options Click the Advanced button on the Server options page to display the Server options - Advanced dialog. In this dialog, set default values for software package properties relating to change management operations and operation modes. When you carry out change management operations on the software package, these default values will be used, unless you choose to change them at the time of defining the change management operation. The different groups of values are described fully in the relevant sections of this guide, as detailed below: Default operation mode See Executing Change Management Operations on page 192. Extended attributes The following list details the check box options in the Extended attributes group box: No check on source host If this check box is selected, when the software package is imported into the object database, no check is made on whether the managed node and the software package contents actually exist. Move SPO removing host Leave this check box selected to move the software package to the lost-n-found collection if the log host or source host of the software package is removed. See Checking lost-n-found on page 310 for more information about lost-n-found. No check on remove If this check box is selected, when a remove operation is executed, all objects included in the software package are located and removed, regardless of the state of the software package. 66 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

87 Setting Properties on the Package Default operation See Executing Change Management Operations on page Default server mode See Executing Change Management Operations on page 192. Web view mode These options are not applicable for new software packages created using the Software Distribution component of Configuration Manager, and only apply to software packages created using former versions of Software Distribution. Endpoint Options The Endpoint Options page on the Package Properties notebook, enables you to define before and after programs that run before the change management operation is processed and after the processing of the change management operation on the endpoint. These options are only valid for install change management operations and for remove operations on endpoints where the software package has not been previously installed. If the before program fails, the change management operation is not submitted. The program ends, and an error is written to the log file. Consequently, the after program does not run. If the before program runs successfully, the change management operation and the after program run sequentially. The change management status of the package is independent of the result of the after program. If the change management operation fails, the operation ends with an error, but the after program runs and the result is written to the log file. New options have been added to the commands, wsetspgs and wgetspgs, to set and retrieve information about before and after programs. You can use before and after programs to manage variables defined in the software package by specifying the wdswdvar command in the program path. See Before Program Example on page 69 for an example. Refer to the Reference Manual for Software Distribution for more information about these commands. Chapter 3. Creating Packages Using the Software Package Editor 67

88 Setting Properties on the Package Note: When defining a before or after program on OS/2 machines, use.cmd or.exe files, as.bat files are not supported. You can also specify arguments for the program to be executed. Some arguments are passed to the program by default. The following is a list of the default arguments passed to the program: operation_type Valid values are either install or remove. Remove operations can only be performed on endpoints where the software package has not been previously installed. endpoint_label The label for the endpoint. machine_id The machine identifier. endpoint_guid The hardware system identifier of the machine stored in the Inventory database region_number The region number. distribution_id The distribution identifier operation_result For the after program only. The result of the change management operation, successful 0, failed -1. Before Program Options To run a program on the endpoint before the change management operation is submitted on the software package, define the following information in the Before program group box. 68 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

89 Setting Properties on the Package 1. In the Path text box, enter the pathname to the program to be run. You can use a variable to express part or all of the path. The variable used must be a system variable or must already be defined in the swdis.var file on the endpoint on which the program runs. The program must already be present on the target system on which it is run. 2. In addition to the default arguments passed to the program, you can define others in the Arguments text box. Separate each argument with a blank space. You can use a variable to express part or all of the argument. The variable used must be a system variable or must already be defined in the swdis.var file on the endpoint on which the program runs. 3. In the Timeout text box, enter the time, expressed in seconds, to wait for the completion of the before program. The value of this attribute can be set to either a number of seconds or to -1. If you set the timeout to a number of seconds and the program does not complete before the timeout expires, Software Distribution kills the program process and the distribution ends with error status. If the timeout is set to -1, the distribution waits for a number of seconds equal to the send_timeout value specified in the swdis.ini file. Before Program Example: This example demonstrates how to use a before program to replace the value of a user-defined variable in the software package at the moment it is installed on the endpoint. The program uses the wdswdvar command to modify the value. In the Appsample scenario explained earlier in this chapter, a variable named target_dir was defined, and the value $(system_drive)\appsample was assigned to it (see step 5 on page 35). On most targets, this value will resolve in c:\appsample or d:\appsample. However, you can use a before program that runs a script that changes the value of the variable, provided that the script is already present on the endpoint. For example, the value can be changed to $(system_drive)\appsample\patches on selected targets as follows: 1. Create a script file, newvar.bat, that modifies the value of the target_dir variable. The script file contains the following command: wdswdvar -s target_dir=$(system_drive)\appsample\patch Refer to the Reference Manual for Software Distribution for more information about the wdswdvar command. 2. Copy the newvar.bat script to the endpoints where you want the value of the target_dir variable modified. For example, copy it to the following path $(system_drive)\scriptdir\newvar.bat 3. In the software package to be distributed to the endpoints, define a before program on the Endpoint Options page. In the Path text box of the Before Program group box enter the following path: $(system_drive)\scriptdir\newvar.bat When the software package is distributed to the specified endpoints, before the change management operations is processed, the newvar.bat script is run and the value of target_dir variable is changed. You can also define an after program to perform clean-up activities such as removing variables. After Program Options To run a program after the change management operation has been processed on the endpoint, define the following information in the After program group box. 1. In this text box, enter the pathname to the program to be run. You can use a variable to express part or all of the path. The variable used must be a system Chapter 3. Creating Packages Using the Software Package Editor 69

90 Setting Properties on the Package variable or must already be defined in the swdis.var file on the endpoint on which the program runs. The program must already be present on the target system on which it is run. 2. In addition to the default arguments passed to the program, you can define others in the Arguments text box. Separate each argument with a blank space. You can use a variable to express part or all of the argument. The variable used must be a system variable or must already be defined in the swdis.var file on the endpoint on which the program runs. 3. In the Timeout text box, enter the time, expressed in seconds, to wait for the completion of the after program. The value of this attribute can be set to either a number of seconds or to -1. If the timeout is reached and the program has not yet completed, an error message is written to the Software Distribution log for the failed program and the program process is killed. Even if the program fails, it does not affect the final state of the change management operation. If the timeout is set to -1, the distribution waits for a number of seconds equal to the send_timeout value specified in the swdis.ini file. For nested software packages, only the before and after programs specified for the primary package are run regardless of the order of the primary package. Only one program is run at the beginning of the change management operation, and one after program is run after all of the nested software packages and primary package are executed. Log File Properties Use the following options to configure information logging on the managed node selected as the log server. Software Distribution can issue a report of the success or failure of the software package operation using , the notice group, or a log file. However, specific information about errors encountered during an operation is available only in the log file. It is recommended that you always specify a log file. Software Distribution creates the log file on the Tivoli management region server (Tivoli server). You can create it on a managed node or target by setting the information in this dialog. It is created by default with the name package-name^package-version.log in the path $BINDIR/../SWDIS/WORK. 70 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

91 Setting Properties on the Package 1. In the Path text box, specify the desired directory for the log file on the target. If the directory does not already exist, it is created. The name of the log file is in the format package-name^package-version.log (such as, Office97^1.0.log). By default, Software Distribution overwrites the log file for each distribution of the software package. For more information about logs, see Software Distribution Logs on page Select the Notice to software distribution group check box in the Log information options group box to have Software Distribution post a notice to the Software Distribution 4 group when a software package operation is performed. The notice includes an indication of success or failure of the operation for each target. You must subscribe to the Software Distribution 4 notice group to view the notices. Note: In addition to selecting this check box, to successfully post a notice to the Software Distribution 4 notice group, you must also run the following command: wsetspop P true spobj_name Refer to the Reference Manual for Software Distribution for information about the wsetspop command. 3. Type an address in the to text box to have Software Distribution send , including an indication of success or failure of the operation for each target, to the specified address when a software package operation is performed. You can specify multiple addresses by separating each domain name with a comma. The path and the alias must be valid on the Tivoli server of the Tivoli management region in which the software package was created. Refer to the Tivoli Management Framework: Planning for Deployment Guide for more information about configuring in your Tivoli management region environment. Chapter 3. Creating Packages Using the Software Package Editor 71

92 Setting Properties on the Package 4. In the Log to host text box, type the name of the managed node on which you want the log file to be located. The log host must be a managed node. If you do not specify a host, the Tivoli server is the default. Indicate the complete path to the log file in the Path text box, or click browse (...) to browse the local file system. 5. Set the UNIX file mode of the generated log file in the Mode text box. 6. Set the UNIX user identification number in the UID text box. 7. Click UNIX attr. to display the Package Properties - UNIX Attributes dialog. You can specify log file permissions for UNIX target machines in the Package Properties - UNIX Attributes dialog. a. To set the ownership for a particular group, enter the numeric group identification in the Group UID text box. The group identification is a number that corresponds to a specific group name. The default permissions for groups are Read and Execute. b. To set the ownership for a particular user, enter the numeric user identification (UID) in the User UID text box. The user identification is a number that uniquely identifies a user to the system. The defaults for users are selected in the Owner group box: Read, Write, and Execute. c. Specify log file permissions for other types of users in the Others group box. The default does not support any type of file permission. Description Select the Description tab from the Package Properties dialog. You can enter a more detailed description of the software package on this page. If the software package is going to be made available from the Software Distribution Web Interface, the text should be entered in HTML format; otherwise, plain text is acceptable. The Web Interface uses the information displayed in this dialog to give a more detailed description of the software package block being installed. Click browse (...) to browse the file system and import an existing file into this dialog. Copyright Select the Copyright tab and type copyright information directly in the text box. Alternatively, click the browse (...) button to select an existing text file containing the copyright information. This information, like the description, is used to help you identify software packages. 72 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

93 Setting Properties on the Package Variable List The Variable list page contains all the built-in variables supported by Software Distribution. From this page you can also create variables. To create a variable on the Variable list page, enter a variable name in the Name text box, assign it a value in the Value text box, then select Add. Check the Save default variables check box to make the default variables persistent for future use. The default variables are saved as user variables and are added to the swdis.var file on the target system during the software package installation, so that the same variables can be used for installing upgrades or additional software package features. Refer to the Reference Manual for Software Distribution for more detailed information about using variables. Nested Packages Select the Nested packages tab to specify existing software packages within the current software package. The current software package is called the primary software package and the packages specified within it are called nested software packages. Chapter 3. Creating Packages Using the Software Package Editor 73

94 Setting Properties on the Package To nest software packages in the primary software package, perform the following steps: 1. Double-click the text box in the Package name column and type the name of the first nested software package. Nested software packages and the primary package must have the same source host but can reside in different policy regions. 2. Double-click the text box in the Package version column and type the version of the nested software package. The version can be one to three numerical strings separated by a period (.). There is no limit to the number of digits you can specify in each string. 3. Specify additional nested software packages by clicking Add. At distribution time, the nested software packages are executed in the order in which they are listed in this dialog. You can also specify the primary package itself in this list. The order of execution is determined by the position of the software packages specified in the list. For example, if the primary package is specified in the third position in the list, the first two nested packages are installed before the primary package. If the primary package is not present in the list, it is installed before all nested software packages. You can also nest software packages using the Tivoli desktop. Drag-and-drop a software package icon from the Profile Manager dialog onto another to nest a software package. See Distributing Nested Software Packages on page 212 for more information about the distribution behavior of primary software packages containing nested software packages. Editing Software Package Properties You can modify a software package by selecting Properties from the Edit menu or toolbar, or by using the right mouse button to display a pop-up menu. You can edit the properties set on the following: v The entire software package v The individual objects contained in the package 74 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

95 Editing Software Package Properties To set or edit properties of the software package itself, select the software package icon in the left pane of the Software Package Editor window, then select Properties to display the dialogs outlined in Setting Properties on the Package on page 61. To edit the properties of an object contained in the software package, select the object in the right or left pane, then select Properties to open the properties dialog. You can also edit the properties of objects created using the automated processes such as AutoPack, the Importer tools, and the Program Builder tools in the same way. The following procedure describes how to modify the link properties contained in the Add Windows shell folder action contained in the Appsample software package. 1. Select the Tivoli Appsample Windows shell folder icon in the left pane of the Software Package Editor window, then right-click Link under the Object type column in the right pane. A pop-up menu is displayed. 2. Select Properties to reopen the Add Windows Shell Link Properties dialog displayed at step 11 on page Make any necessary changes, then select OK to confirm the changes. Note: After modifying properties of an object, the Software Package Editor Java interface does not always refresh to display the changes. Save the software package and reopen it to display the correct information. Program Actions in the Software Package Editor In addition to the actions that you added to the Appsample software package earlier in this chapter, the Software Package Editor supports a number of program actions which execute the following types of native packages on target systems: v InstallShield program. See The InstallShield Program Action on page 76. v Microsoft Setup program. See The Microsoft Setup Program Action on page 78. Chapter 3. Creating Packages Using the Software Package Editor 75

96 Other Software Package Actions v Microsoft Software Installer (MSI) program. See Chapter 6, Embedding Native Objects into a Software Package, on page 107. v AIX native packages in an IBM AIX environment. See Using Dialogs to Embed or Edit an AIX Package on page v Solaris native packages or patches, in a Solaris operating environment. See Using Dialogs to Embed or Edit a Solaris Package on page v RPM native packages, in a Linux environment. See Using Dialogs to Embed or Edit a Linux Package on page v HP-UX native packages. See Using Dialogs to Embed or Edit an HP-UX Package on page 130. The following sections are a few examples of some program objects. See Chapter 6, Embedding Native Objects into a Software Package, on page 107 for more information. Also, refer to the online help documentation for a more detailed explanation of these program objects or the related software package definition file stanza in the Reference Manual for Software Distribution. The InstallShield Program Action The InstallShield program action enables you to create a program object that runs installations of applications that use the InstallShield installation program. You can use this program action to install an application whose installable files are located on a network drive. Software Distribution uses the application s native installation (InstallShield) to perform a redirected installation. For example, to install the Tivoli desktop application whose installable files are located on a network drive, perform the following steps: 1. Set the software packages properties at the package level. a. Right-click the software package icon in the left pane and select Properties from the pop-up menu. b. On the General page, enter the software package name and version and a descriptive title. c. Click Condition on the Software Package Properties dialog in the upper right corner of the dialog. Enter the following expression in the dialog: os_name LIKE Win*, then click OK. d. Select the Variable list tab. Enter net_dir in the Name text box and the path to the installation images \\aquarius\images\desktop in the Value text box, then click Set. e. Click OK to save the software package property settings and close the dialog. 76 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

97 Other Software Package Actions 2. Select the Program tab, then click the InstallShield program icon from the toolbar. The InstallShield Program Properties dialog is displayed. a. In the Caption text box, enter Tivoli desktop installation. b. In the Path text box, use the net_dir variable to define part of the path to the setup executable. Right double-click the Path text box to display the Variable List Editor dialog. Select the net_dir variable, then click OK to enter the variable in the text box. Complete the entry in the Path text box to read as follows: $(net_dir)\setup.exe. 3. Click Advanced to set the response and log files. The InstallShield Program Properties - Advanced dialog is displayed. a. In the Timeout text box, enter the time, expressed in seconds, to wait for the program to complete. See Setting Timeout Values for a Distribution on page 307 for more details. b. In the Response file text box, enter the InstallShield response file $(net_dir)\setup.iss. c. In the Log file text box, enter the pathname of the InstallShield log file. Use the $(system_drive) variable to express part of the path by entering the following: $(system_drive)\tmp\install.log. d. Leave the Silent check box selected to perform an unattended installation. Chapter 3. Creating Packages Using the Software Package Editor 77

98 Other Software Package Actions e. Click OK to save the values and return to the InstallShield Program Properties dialog. 4. Click OK to add the InstallShield program action to the software package. 5. Save the software package in the.spd format. You can proceed with the distribution and installation of the software package by importing it into a software package profile from the Tivoli desktop on the Tivoli server. See Chapter 9, Preparing a Software Package for Distribution, on page 177 for more information about creating profiles and importing and distributing software packages. The Software Package Editor also provides the InstallShield tool to guide you through the creation of an InstallShield program object. To launch the InstallShield tool, select Tools->Program Builder->InstallShield from the menu bar. Refer to the online help about this tool for more information. The Microsoft Setup Program Action The Microsoft Setup program action enables you to create a program object that runs installations of Windows applications that use the Microsoft Setup installer. Select the Program tab, then click the MS Setup program icon from the toolbar. The Microsoft Setup Program Properties dialog is displayed. Remove Actions The Software Package Editor also provides an MSSetup tool to guide you through the creation of an MSSetup program object. To launch the MSSetup tool, select Tools->Program Builder->MSSetup from the menu bar. During a typical installation process, in addition to adding objects such as files, directories, registry entries, and shell folders, some objects must also be removed. Every object-related action described in this chapter that adds an object to a target machine also has a corresponding remove object-related action. For example, to uninstall an application that is not equipped with an uninstall utility, you can add 78 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

99 Remove Actions a series of remove actions to the software package to remove the folders, files, directories and registry entries related to the installation of the application. Click the Remove object tab from the toolbar to display the possible remove actions. For example, to remove a value assigned to a Windows registry key, complete the following steps: 1. Select the Windows registry key icon to display the Remove Windows Registry Key Properties dialog. 2. Enter the Hive, Parent Key, Key, and Class. 3. Select the Remove if existing check box if you want Software Distribution to remove the Windows registry key containing the value. 4. Click OK to add the Remove Windows registry key action to the software package. 5. Right-click the Remove Windows registry key action and select Insert -> Value. The Remove Windows Registry Value Properties dialog is displayed. Saving the Software Package 6. Enter the name of the value to be removed, then click OK. The Appsample software package created in the Software Package Editor displays only a description of the objects contained in the package. That is, it contains a sequential list of actions to be executed on the target machine and not the objects or resources themselves such as files and programs to be executed. Actions require resources to be executed. When the actions are consolidated with the actual resources (files, directories, registry keys, and so on), the software package is considered to be in a built format (.spb). A software package that consists solely of a description of the actions and objects contained in the package and not the objects or resources themselves, is considered to be in a not-built format (.sp,.spd). To consolidate the actions with the resources Chapter 3. Creating Packages Using the Software Package Editor 79

100 Saving the Software Package into a zipped file, you save the software package as a software package block, selecting.spb as the file type. The software package, in this format, is in the built format. To create a software package block, complete the following steps: 1. Select Save as from the File menu. The Save dialog is displayed. To customize the path or folder to which your software package is saved, see Setting the Default Path on page Select the appropriate directory, then enter a file name in the File name text box. The file name can be different from the package name. 3. In the Files of type list, select Software Package Block (.spb), then click Save. Saving the software package in this format performs a local build of the software package. All source files must reside on the local machine for the build to be performed successfully. Depending on the size of the package, this operation may take several minutes. Upon completion of the build operation, Software Distribution asks if you would like to reload the package in the Software Package Editor main window. The procedure to reload the software package can take several minutes if the software package contains an add directory action with the Descend directories option selected. When the software package is reloaded, the structure may be different because Software Distribution must add the entire directory tree to the software package by creating the related actions (add directory, add file). For more information about the Descend directories option, see step 11 on page 37. Note the other two formats available. You can also save the Appsample software package as a software package file by selecting Software Package (.sp) from the Files of type list. 4. To transform the software package file or software package block into a software package definition file, open the file in the Software Package Editor, then save it in software package definition format by selecting this option from the Files of type drop-down list. This procedure transforms the software package into text file format. The text file consists of a sequence of stanzas, each of which describes the actions contained in the software package. You can use the.spd file as the basis to create a new software package or to edit an existing one. Refer to the Reference Manual for Software Distribution for more information about editing the.spd file. 80 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

101 Saving the Software Package The.spd file is the text version of the information that the Software Package Editor tree view displays. Using a text editor, you can view the.spd file, modify it, and then reopen it in the Software Package Editor and save it in another format. To view the Appsample software package in the software package definition file format (Appsample.spd), refer to the.spd file examples in the Reference Manual for Software Distribution. To import a software package definition file into the Tivoli Management Framework environment, see Importing a Software Package into the Tivoli Environment on page 182. Chapter 3. Creating Packages Using the Software Package Editor 81

102 Saving the Software Package 82 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

103 Chapter 4. Creating a Software Package for Devices This chapter explains how to create a software package for targets that are pervasive devices. You can include the following actions in the software package for devices: Task See Page Adding Directories to Devices 84 Adding Files to Devices 86 Adding an Execute Program Action 57 Customizing Device Settings 88 To perform these tasks, you must do the following: 1. Launch the Software Package Editor and select Software Package Templates, then Device Software Package from the pull-down list. 2. Create a software package that contains the actions that you want to perform on the devices. 3. Distribute the software package to the target devices. For details about working with pervasive devices, refer to the Managing Resources part of the User s Guide for Deployment Services. Creating a Device Object Software Package For any task that you want to perform on devices, you must first create a device object software package, which is a software package that can be distributed to targets that are devices. The device object becomes the container for the actions that you want to perform on the devices. You can create a device object for each device sub-type. Then, you must add the actions that you want to perform on the devices to the device object. The software package can include a device object for each device sub-type but must contain only device objects. To create the software package for devices, do the following: 1. When you launch the Software Package Editor, it displays an empty software package icon whose default name is Noname. Name the software package by clicking it and typing the desired name over it. 2. From the Add object tab of the Software Package Editor, click the Add Device Object icon. Copyright IBM Corp. 2002,

104 Creating a Device Software Package 3. The Add Device Object Properties dialog is displayed: Caption Enter a descriptive name for the action. Subtype Select the type of device for which the action is prepared. The action will be performed only on devices of the type specified. Nokia9200Series For Nokia 9200 Communicator series devices Palm For Palm devices WinCE For Windows CE devices 4. Click OK. The new device object is listed in the tree under the software package icon in the left pane and in the list of objects in the main pane when the software package icon is selected in the tree in the left pane. Now, you are ready to add the actions that you want to perform on the devices to the device object. Note: Do not add actions other than device actions to the device object. For actions on targets other than devices, you must create another software package that does not contain device objects. Adding Directories to Devices You can add directories to Windows CE devices only. To add directories to the target devices, do the following: 1. Select the device object icon in the left pane. 2. Select the Add Device Directory icon from the Add object tab of the Software Package Editor. 84 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

105 Adding Directories to Devices 3. The Add Device Directory Properties dialog is displayed. Enter the following information in the Source group box: Location Enter the parent folder where the source directory is located. Name Notes: Enter the name of the source directory. Enter an asterisk to specify that all files contained in the source directory are to be added to the package. The files are installed with their original name in the target directory. 1. When you specify the name of a source or target file, file and directory names may contain wildcard (pattern-matching) characters. The supported wildcard characters include an asterisk (*), which matches any string, and a question mark (?), which matches any single character. For more information about specifying file and directory names with pattern-matching characters, refer to the Reference Manual for Software Distribution. 2. Ensure that filenames are valid for the Nokia 9200 Communicator series devices. For example, the following characters are not valid: " *? \ / < > : In the Destination group box, you find the same information you entered in the Source group box. The destination represents where the specified directory is created on the target system. The files are installed with their original name into the target directory at installation time. Do not specify a drive in the Destination Location field. Select the Descend directories check box to add the entire directory tree to the device object. If it is not selected, only the files listed below the top-level directory are added. 4. Click OK to add this action to the device object. Select the device object icon in the left pane of the Software Package Editor window to display the Device Directory object. Chapter 4. Creating a Software Package for Devices 85

106 Adding Files to Devices Adding Files to Devices You can add files to Palm devices or Nokia 9200 Communicator series devices using the following steps. To add files to Windows CE devices, you must add the directories that contain the files to the device object (see Adding Directories and Files on page 34). To add files to the target devices, do the following: 1. Select the device object icon in the left pane. 2. Select the Add Device File icon from the Add object tab of the Software Package Editor. 3. The Add Device File Properties dialog is displayed. Enter the following information in the Source group box: Location Enter the parent folder where the source file is located. Name Enter the name of the source file. The file is installed with its original name on the target. Note: When you specify the name of a source or target file, the filename can contain wildcard (pattern-matching) characters. The supported wildcard characters include an asterisk (*), which matches any string, and a question mark (?), which matches any single character. For more information about specifying filenames with pattern-matching characters, refer to the Reference Manual for Software Distribution. Destination In the Destination group box, you find the same location (for Nokia 9200 Communicator series devices only) and filename entered in the Source group box. The destination represents where the specified file is created on the target system. Notes: 1. The Location text box is displayed for Nokia 9200 Communicator series devices only. The dialog for Palm devices displays the Name text box only. 86 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

107 Adding Files to Devices 2. For Nokia 9200 Communicator series devices, always specify the drive. If applicable, you must specify a directory that already exists in the Destination group box. The default drive is typically the C: drive. A memory card is typically the D: drive. Use a backslash ( \ ) as a path delimiter. 3. If you add a SIS file to Nokia 9200 Communicator series devices, it is treated as a Nokia 9200 Communicator series software installation file. For each SIS file, an installation window opens on the host PC and prompts the device owner to supply specific installation information. If the user chooses to install the software, the SIS file directs installation of the software on the device. The software is installed in the directory specified by the software installation file or the installation window can supply a prompt that allows the user to select a location on the device. To complete the installation of the SIS file, click Finish. It is not recommended that you click Add Component because this action changes the installation flow of the software package. If there are additional SIS files in the software package, these steps are repeated. Click Finish after the installation of each SIS file. 4. To treat a file with a JPG, BMP, or GIF extension treated as a Nokia 9200 Communicator series background image file, specify the Nokia 9200 Communicator series system directory for background image files, which is typically C:\Documents\Photo gallery. To change the desktop background to the newly downloaded image file, the device owner must select that file from the list of background image files that are available for use as the desktop background. 5. To treat a file with a WAV, AU, or MP3 extension as a Nokia 9200 Communicator series ringer tone file, specify the Nokia 9200 Communicator series system directory for ringer tone files, which is typically C:\Documents\Tones. To change the ringer tone to the newly downloaded ringer tone file, the device owner must select that file from the list of ringer tone files that are available for use as the ringer tone. Space required Enter the space required on the device for the file. The device is checked for the specified space before the action begins. This text box is not available for Nokia 9200 Communicator series devices. From the Bytes drop-down list, click a unit of measurement: Kilobytes or Megabytes. Replace if existing Select the check box to overwrite the file on the target device if it already exists. 4. Click OK to add this action to the device object. Select the device object icon in the left pane of the Software Package Editor window to display the Device Directory object. Running Programs on Devices You can distribute a software package that runs executable programs on Windows CE devices only. Software Distribution returns standard error and standard output to the log file. Chapter 4. Creating a Software Package for Devices 87

108 Running Programs on Devices Before you start, ensure that the program file is distributed to the devices before this action is. You can do this by including the add file action in the same software package as the execute program action is or in a separate software package that was distributed previously. To run programs on devices, do the following: 1. Select the device object icon in the left pane. 2. Select the Device Execute Program icon from the Add object tab of the Software Package Editor. 3. The Device Execute Program Properties dialog is displayed. Complete the following information: Caption Enter a name for the program in the Caption text box. The default value is the program entered in the Path text box. Program path and name Enter the path and name of where the program to be run is located on the Windows CE device. Specify the same path and filename that you specified in the Destination Name text box of the Add Device File Properties dialog (on page 86). Arguments Enter the arguments of the program being run. 4. Click OK to add this action to the device object. Select the device object icon in the left pane of the Software Package Editor window to display the Device Execute Program object. Customizing Device Settings You can customize the settings on devices, for example, the date or time format. The following sections describe how to customize devices using the Software Package Editor. You can also create software package definition (SPD) file by hand and distribute it to devices. Editing the Software Package Definition (SPD) File in the Reference Manual for Software Distribution describes how to create an SPD file. Device Customization Parameters in the User s Guide for Deployment Services provides the keywords and values for your reference. After device settings have been installed on the device, the inventory data is automatically updated in the database. Customizing Nokia 9200 Communicator Series Devices To customize Nokia 9200 Communicator series devices, do the following: 88 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

109 Customizing Nokia 9200 Communicator Series Devices 1. Use the Administrator Suite application provided by the device manufacturer to select device settings and generate an XML file. The configuration file is saved in the \AdministratorSuite\Configurations Files directory. 2. In the Software Package Editor, select the device object icon in the left pane. 3. Select the Device Customization icon from the Add object tab of the Software Package Editor. 4. The Device Customization Properties dialog is displayed. In the Caption text box, enter a name that identifies the customization for the device. 5. Click OK to add this action to the device object. Select the device object icon in the left pane of the Software Package Editor window to display the Device Customization object. 6. Right-click the Device Customization Properties object and select Insert-> Device Settings. 7. The Device Settings dialog is displayed: Keyword The drop-down list is set on Configuration File and is not enabled. Value Enter the path and name of the configuration file. The file must be on the system on which you are creating the software package. Click OK. The setting is listed in the right pane of the Software Package Editor when the Device Settings object is selected. Customizing Palm and Windows CE Devices To customize Palm and Windows CE devices, do the following: 1. Select the device object icon in the left pane. 2. Select the Device Customization icon from the Add object tab of the Software Package Editor. Chapter 4. Creating a Software Package for Devices 89

110 Customizing Palm and Windows CE Devices 3. The Device Customization Properties dialog is displayed. (See page 89.) In the Name text box, enter a name that identifies the customization for the device. 4. Click OK to add this action to the device object. Select the device object icon in the left pane of the Software Package Editor window to display the Device Customization Properties object. 5. Right-click the Device Customization Properties object and select Insert-> Device Settings. 6. The Device Settings dialog is displayed: Keyword From the drop-down list, select the setting you want to define. Value Enter the value that you want to assign to the setting. Refer to the online help in this dialog for an explanation of keywords and the accepted values. Click OK. The setting is listed in the right pane of the Software Package Editor when the Device Settings object is selected. Repeat the previous two steps for each setting that you want to customize. Distributing the Device Object Software Package to Targets After you create the device object software package, you must import it into a software package profile and distribute it to the target devices just as you would any other software package. Ensure that the target devices are part of a resource group, so that the resource group will be listed among the available subscribers. See Managing Resources in the User s Guide for Deployment Services for instructions about grouping resources. When the package is installed on the devices, the actions included in the device object software package are performed on the devices. See Chapter 9, Preparing a Software Package for Distribution, on page 177 for instructions. You can cancel distributions or list information about pending distributions to devices using the wwebgw command. See Using Commands in the Reference Manual for Software Distribution for details. 90 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

111 Chapter 5. Using Software Distribution on OS/400 This chapter provides a summary of the Software Distribution features that are specific for OS/400 operating systems. It includes the following information: v An overview of the Software Distribution features that are available for OS/400 systems. See Defining Software Packages with OS/400 Objects. v An overview of the file systems used on OS/400 systems. This section includes guidelines on how to define file locations on the OS/400 native system and the Integrated File System (IFS). See The OS/400 Native and Integrated File Systems on page 92. v Instructions for adding OS/400-specific objects to a software package using the OS/400 Software Package Editor. See Defining Software Packages with OS/400 Objects. v Information about adding objects to an OS/400 native file system using the standard Software Distribution Add Directory and Add File actions. See Adding Non-Native Objects to the OS/400 Native File System on page 102. v Information about using the standard Software Distribution Execute User Program action to run programs on an OS/400 system. See Running an OS/400 Executable Program on page 104. Notes: 1. AutoPack technology is not available from the OS/400 Software Package Editor. 2. Due to limitations in the way date information is handled on OS/400 systems, the preview and the repair options are not supported for packages installed in the OS/400 native file system. See also The Data Moving Service in an OS/400 Environment on page 233 for OS/400-specific information about the Software Distribution Data Moving Service which enables you to move data in both OS/400 native file systems and IFS. Defining Software Packages with OS/400 Objects Software Distribution includes a Software Package Editor for OS/400 systems. This is a Java-based GUI that you use to create and customize software packages for distribution to OS/400 systems. You install and use the Java-based OS/400 Software Package Editor on a Windows machine that has a TCP/IP connection to an OS/400 machine that is used as a preparation site for software packages. Installation and use of the Software Package Editor requires the installation of the following SPB files that are located in the CD3\SPB\ CD-ROM: v Tivoli_JRE_NT.spb on the Windows machine v Tivoli_SWDEP_NTAS400.spb on the Windows machine v Tivoli_SWDEP_400PS.spb on the OS/400 machine Refer to the Planning and Installation Guide for more information about installing the SPB files. You define and save software packages on the Windows machine, but you select the objects that are to be included in the package from the file system of the OS/400 machine. The software packages created in this way can be imported into Copyright IBM Corp. 2002,

112 Defining Software Packages on with OS/400 Objects the Tivoli management region in the same way as other software packages. Refer to Planning and Installation Guide for information about installing these SPB files. The OS/400 Software Package Editor uses the Integrated File System (IFS) to browse for files to be included in the software package. This allows you to use the standard Software Package Editor actions, for example, Add Directory and Add File, when defining the OS/400 software package. The OS/400 Software Package Editor also includes additional actions that allow you to include OS/400 native objects and programs in the software package. See The OS/400 Native and Integrated File Systems for an explanation of how file locations are defined using the OS/400 native system and the IFS. The OS/400 Software Package Editor allows you to perform the following specific OS/400 tasks: v Add and remove OS/400 libraries and objects. v Add and remove OS/400 licensed programs. v Change OS/400 system values. For instructions on performing these tasks, see Using the OS/400 Software Package Editor on page 93. In addition, you can use many standard features of the Software Package Editor, as follows: v Distribute directories and files to both OS/400 Native and Integrated File Systems. v Distribute text files that are ASCII encoded on the source host and that could be translated in EBCDIC on the OS/400 target. v Execute programs on the target, including OS/400 CL programs. The use of the Software Package Editor to perform these tasks is described in Chapter 3, Creating Packages Using the Software Package Editor, on page 29. Adding Non-Native Objects to the OS/400 Native File System on page 102 and Running an OS/400 Executable Program on page 104 provide examples of how to define the destinations of software package objects on OS/400 native file systems. If you are using IFS, the objects can be edited and managed in the same way as UNIX objects. This means that you can add files, directories, and links to achieve the same results as you would in a UNIX environment. The OS/400 Native and Integrated File Systems The OS/400 file system is an integrated database containing objects instead of files. The integrated file system provides you with a typical hierarchical file system interface that is analogous to a UNIX system. A QSH shell interface supports the standard pathname syntax for files and directories that are offered by UNIX shell systems. The native file system can also be referred to in a UNIX-like path name convention using the IFS. For example, it is possible to refer to the QGPL library with: /QSYS.LIB/QGPL.LIB To a default printer output queue QGPL/QPRINT with: /QSYS.LIB/QGPL.LIB/QPRINT.OUTQ 92 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

113 OS/400 Native and Integrated File Systems Native objects are generally mapped into: /QSYS.LIB /<LIB_NAME>.LIB/<OBJ_NAME>.<TYPE> The object type is identified by a.<type> name suffix. IFS maps physical files with members into directories; therefore a physical file member is referred to thus: /QSYS.LIB/<LIB_NAME>.LIB/<OBJ_NAME>.FILE/<MBR_NAME>.MBR Navigating the IFS by means of the Software Package Editor FileChooser graphical user interface (GUI), you can install, remove, and manage software packages containing UNIX objects on an OS/400 system. Using the OS/400 Software Package Editor The OS/400 Software Package Editor is based on the standard Software Package Editor. Therefore, operations that you can perform from either the standard Software Package Editor or the OS/400 Software Package Editor are not repeated in this section. For information about these common operations, see Chapter 3, Creating Packages Using the Software Package Editor, on page 29. This section describes how you use the OS/400 Software Package Editor to perform the following software package operations from a Windows preparation site: v Add an OS/400 library v Add an OS/400 object v Remove an OS/400 library v Remove an OS/400 object v Add an OS/400 licensed program v Remove an OS/400 licensed program v Change an OS/400 system value Launching the OS/400 Software Package Editor From a Windows machine with the OS/400 Software Package Editor installed and a TCP/IP connection to an OS/400 machine, start the OS/400 Software Package Editor logon, as follows: 1. Double-click the Software Package Editor OS400 icon on your desktop. Notes: 1. Before you use the OS/400 Software Package Editor, perform the following actions on the AS/400 preparation site machine: v Make sure that all host server daemons have been started. See command strhostsvr *all. v Install the OS/400 Software Package Editor provided in the Tivoli_SWDEP_400PS.spb file. 2. The build of a package runs in a job under the specified user profile. Chapter 5. Using Software Distribution on OS/400 93

114 Using the OS/400 Software Package Editor The OS400 Logon dialog is displayed. 2. Type the OS/400 host machine name, user ID, and password for the machine to which you want to connect. This is the information related to the machine where the object to build the package are located. To build software packages containing OS/400 objects, your user ID should have *ALLOBJ authority on the AS/400 system. 3. Click OK to return to the Software Package Editor main window. Adding OS/400 Libraries and Objects You use the Add OS/400 Library and Add OS/400 Object commands to specify the OS/400 objects that are to be installed on the target systems. An OS/400 Object can only be added within a library, therefore, even if the library already exists on the target system, you must specify it in the software package, and then specify the objects within that library that are to be added on the target system. You can specify which objects from the library are to be included, as follows: v All objects in the library are to be included. v Only objects that have changed since a specified reference data and time are to be included. v Selected objects, specified using the Add OS/400 Object command, are to be included. To add an OS/400 library to a target system, perform the following steps: 1. In the Software Package Editor window, select the Add object tab. 94 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

115 Using the OS/400 Software Package Editor 2. Select the OS400 Library icon. The Add OS400 Library Properties dialog is displayed. 3. In the source Location text box, type the location of the parent library where the library to be added is located or use the browse (...) button to locate the library. The path cannot contain wildcards. The location you specify is duplicated in the destination Location text box. 4. In the source Name text box, type the name of the library to be added. You can use wildcards in this text box. This name is duplicated in the destination Name text box. 5. In the destination Location text box, specify the location of the OS/400 parent library to which the package is to be added, or use the browse (...) button to locate the library. 6. In the destination Name text box, type the name of the library to which you want the package to be added. 7. If you do not want to add all library objects, leave the Descend check box cleared. This is the default. 8. If you want to add all library objects, or changed objects, select the Descend check box and then define the library contents you want added to the software package. You do this by selecting one of the following option buttons: All Objects Selecting this option button adds all the objects that the library contains. Changed Objects Only Selecting this option button adds only the objects that were changed after a specified reference date and time. 9. If you selected the Changed Objects Only option button, you must specify the reference date and time in the Reference Date and Reference Time text boxes. The format for the time must be HH:MM:SS. Though the separator can change according to the setting of the QTIMSEP system value, which supports the following separators: Chapter 5. Using Software Distribution on OS/400 95

116 Using the OS/400 Software Package Editor v Colon (:) v Period (.) v Comma (,) v Blank 10. From the Replace Options drop-down list, select the appropriate replace option, as follows: ALL NEW All the objects contained in the library are added to the target system. This is the default. Only objects that do not already exist in the target library are added to the target system. OLD Only objects that already exist in the target library are added to the target system to replace the old ones. 11. In the Target Release text box, type the release of the target OS/400 system. The target release can be specified as follows: *CURRENT This indicates the current release. *PRV This indicates the previous release with modification level 0. VxRyMz This indicates the target release. Where x is a valid version number, y is a valid release number and z is a valid modification level. For example, V4R4M0. Note: If the target release of the AS/400 endpoint is not consistent with this value, the object is not installed. You can use the OS_VERSION attribute to condition your installation based on the version of the package that is installed on the target system. 12. Define on which machine the selected library objects are to be collected at execution time, in either of the following ways: v On the OS/400 preparation machine when the package is created: leave the Remote check box cleared. This is the default. This creates a *SAVF. v On the target machine at execution time: select the Remote check box. This does not create a *SAVF. The objects are collected directly from the target machine. 13. To insert a condition check, click the Condition button and make your selections in the Condition Editor dialog displayed. 14. Click OK to activate the operation. Adding OS/400 Objects If you did not select the Descend check box in the Add OS/400 Library dialog, you must use the Add OS/400 Object action to add individual OS/400 objects to the OS/400 library that you have added. Each Add object has a green plus sign (+) in its icon. To add an OS/400 object to a library, perform the following steps: 1. In the left pane of the Software Package Editor window, select the OS/400 library object to want to add the object to. 2. In the Add object tabbed page, click the OS400 Object icon. The Add OS400 Object Properties dialog is displayed. Alternatively, you can right-click the OS/400 library object and select Insert to insert another library object, an 96 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

117 Using the OS/400 Software Package Editor OS/400 object, or multiple libraries and objects. 3. In the source Location text box, specify the path name of the library that contains the object to be added to the software package. The path cannot contain wildcards. This path name is duplicated in the destination Location text box. 4. In the source Name text box, specify of the name of the library object to be added. You can use wildcards in this name. 5. In the destination Location text box, specify the destination path name of the library to which the object is to be added. 6. In the destination Name text box, specify the name of the object to be added. 7. Specify where the object is to be collected, as follows: v Select the Remote check box if you want the object to be collected on the target machine at run time. v Clear the Remote check box if you want the object to be collected on the OS/400 preparation machine when the package is created. 8. If you want to insert a condition check, click the Condition button and make your selections in the Condition Editor dialog. 9. Click OK to activate the operation. Removing OS/400 Libraries To remove a library from a target OS/400 machine, perform the following steps: 1. In the Software Package Editor window, select the Remove object tab. Chapter 5. Using Software Distribution on OS/400 97

118 Using the OS/400 Software Package Editor 2. Select the OS400 Library icon. The Remove OS400 Library Properties dialog is displayed. 3. In the Location text box, specify the location of the parent library of the OS/400 library to be removed. 4. In the Name text box, specify the name of the library you want to remove. 5. If you want to remove the library and its contents from the target system, select the Descend check box. Clear this check box if you want to remove an empty library from the target system. Cleared is the default. 6. If you want to insert a condition check, click the Condition button and make your selections in the Condition Editor dialog displayed. 7. Click OK to activate the operation. Removing OS/400 Objects The Remove OS/400 Object action enables you to remove individual objects from a library. Each remove object has a red minus sign (-) in its icon. To remove an OS/400 object, perform the following steps: 1. In the left pane of the Software Package Editor window, select the OS/400 library from which you want to remove the object. 2. In the Remove Object page, select Remove object. The Remove OS400 Object Properties dialog is displayed. 3. In the Location text box, specify the location of the OS/400 library containing the object to be removed, if the location is not already shown. 4. In the Name text box, specify the name of the OS/400 object to be removed. 5. If you want to insert a condition check, click the Condition button and make your selections in the Condition Editor dialog displayed. 6. Click OK to activate the operation. 98 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

119 Using the OS/400 Software Package Editor Adding OS/400 Licensed Programs Using the Add OS/400 Licensed Program action, you can add an action to a software package to install a licensed program on an OS/400 system. The following options are available for retrieving the licensed program to be installed: v From an existing LICPGM. This is a local operation where you provide the ID of the licensed program already installed at the preparation site. At build time, the program is retrieved from the source machine, saved in a *SAVF, and included in the package. At install time, the program is installed on the target machine. v From a device. This is a remote operation where you specify the device, for example, a CD-ROM, from which the program will be installed. At build time, no *SAVF is included in the package. At install time, the program is installed on the target system from the specified device. v Note: To successfully install a software package that installs a license program, some products require that the user profile running the installation process must be included in the system distribution directory. In this case, add the QTIVROOT user profile to the system distribution directory. Refer to the product installation manual for more information. From an existing save file. This is a remote operation where you specify the path name of the *SAVF that to be used to install the program at installation time. At build time, no *SAVF is included in the package, but at install time, the program is installed on the target system from the specified *SAVF file. To add an OS/400 licensed program, perform the following steps: 1. In the Software Package Editor window, select the Add object tab. 2. Select the OS400 Licensed Program icon. The Add OS400 Licensed Program Properties dialog is displayed. dialog. 3. In the text boxes, type the required information about the licensed program, as follows: Name Type the alphanumeric code of the licensed program to be installed, in the OS/400 format (5763XD1). Chapter 5. Using Software Distribution on OS/400 99

120 Using the OS/400 Software Package Editor Option Type the name of the optional parts for the specified licensed program. The default is *ALL. Language Type the language option of the specified licensed program. The default is *ALL. Release Type the release of the licensed program to be installed. This is not necessary if the specified product contains only one release. The default is *ONLY. Target Release Type the release of the target OS/400 system. The default is *CURRENT. 4. From the Type drop-down list, specify the object type to be restored, as follows: *ALL Installs both the licensed program and the language components. This is the default. *PGM Installs only the program. You use this type, for example, if you have upgraded the program but not the language component. *LNG Installs only the language component. You use this type, for example, if you are adding a new language to a previously installed licensed program. 5. If the device containing the licensed program to be added is already located on the target machine, select the Remote check box and locate the program in either one of the following ways: v Specify in the Source text box the SAVF in which the licensed program is located. Use the format /QSYS.LIB/MYLIB.LIB/SAVF.FILE. v Specify in the Device text box the device name on which the program is located, for example, the optional device name. 6. If you want to insert a condition check, click the Condition button and make your selections in the Condition Editor dialog displayed. 7. Click OK to activate the operation. Removing OS/400 Licensed Programs The Remove OS/400 Licensed Program action enables you to specify the ID of the program to be removed from the target system. At install time, the specified program is removed from the target system. To remove an OS/400 licensed program, perform the following steps: 1. In the Software Package Editor window, select the Remove object tab. 100 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

121 Using the OS/400 Software Package Editor 2. Select the OS400 Licensed Program icon. The OS400 Licensed Program Properties dialog is displayed. 3. In the text boxes, type the required information about the licensed program to be removed, as follows: Name Type the alphanumeric code of the licensed program to be removed, in the OS/400 format (5763XD1). Option Type the name of the installation option for the specified licensed program. The default is *ALL. Language Type the language option of the specified licensed program. The default is *ALL. Release Type the release of the licensed program to be removed. This is not necessary if the specified product contains only one release. The default is *ONLY. 4. If you want to insert a condition check, click the Condition button and make your selections in the Condition Editor dialog displayed. 5. Click OK to activate the operation. Changing an OS/400 Sysval The Set OS/400 System value action enables you to specify a new value for an OS/400 SYSVAL name/value pair. To change a system value, perform the following steps: 1. In the OS/400 Software Package Editor window, select the System action tab. 2. Select the Set OS400 system value icon. The OS400 System Value Properties dialog is displayed. Chapter 5. Using Software Distribution on OS/

122 Using the OS/400 Software Package Editor 3. In the Name text box, type the name of the system value to be changed. 4. In the Value text box, type the new value of the system value you specified. For more information about OS/400 system values, refer to OS/400 Work Management, SC If you want to insert a condition check, click the Condition button and make your selections in the Condition Editor dialog displayed. 6. Click OK to save the information and close the dialog. Using Non-OS/400-Specific Functions In addition to the OS/400 specific functions, you can use standard functions of the Software Package Editor when you are defining a software package for distribution to an OS/400 system, as follows: v The Add Directory and Add File functions, to add a non-native file, for example from a Unix system, to an OS/400 system. See Adding Non-Native Objects to the OS/400 Native File System. v The Execute User Program action, to run a program, for example, a C, CL, REXX, exec, or batch job script. See Running an OS/400 Executable Program on page 104. The purpose of this section is to clarify how to specify the destination paths for files in an OS/400 native file system. Examples are provided that show the stanzas that define the add directory, add file, and execute user program actions in the SPD file. Note: If the destination file system is OS/400 IFS, files are specified in the same way as for a Unix file system. Adding Non-Native Objects to the OS/400 Native File System You can use the Software Package Editor to add objects in a software package that will add non-native objects to an OS/400 file system. In this way, you can take files from a non-os/400 file system, for example Windows or Unix, and add them to the OS/400 native file system as physical files or file members. You add the objects to the software package using the Add Directory and Add File actions included in the standard Software Package Editor. See Adding Directories and Files on page 34. To add a directory or file to an OS/400 native file system, you specify an OS/400 native physical file as the destination path. At installation time, Software Distribution adds the file to the native physical file as a file plus member, or as an additional member of an existing file. Notes: 1. If the target physical file already exists on the target system, it maintains its attribute, for example, PF_DTA. If the physical file does not exist on the target system, a new physical file is created with attribute PF_SRC (Source Physical File). 2. When adding members to a physical file, ensure that the maximum number of members (MAXMBRS) and the file size (SIZE) are sufficient to accept the new members. 3. You cannot add a group of files with the same name and different extensions. OS/400 does not use extensions to differentiate between files. OS/ IBM Tivoli Configuration Manager: User s Guide for Software Distribution

123 Using Non-OS/400-Specific Functions extensions are assigned to the files when they are added to the file system and the original extensions are lost. This means that files with the same name will overwrite each other. 4. When adding an object to an OS/400 target system, the last modified date is set to the current date. However, the date used to determine whether the object should be added is the last modified date on the source system. When specifying an OS/400 file system path, use the convention described in the section The OS/400 Native and Integrated File Systems on page 92. For example, to add files of directory /usr/sd/source to library mylib.lib, use the following:... add directory location = /usr/sd name = source destination = /QSYS.LIB/MYLIB.LIB add = y descend_dirs = y translate = y end... At installation time, these actions add the files (collected at build time on a Windows or UNIX source host) as files of the library MYLIB.LIB. Each file contains a member that has the name on the physical file (/QSYS.LIB/MYLIB.LIB/FILE_1.FILE/FILE_1.MEMBER). By default, the files are created as OS/400 source physical files (PF_SRC). To add files FILE1.DAT and FILE2.DAT to an existing OS/400 physical file, use the following:... add directory location = /usr/sd name = source destination = /QSYS.LIB/MYLIB.LIB/DATA.FILE add = y descend_dirs = n file name = FILE1.DAT destination = FILE1.MBR translate = y end file name = FILE2.DAT destination = FILE2.MBR translate = y end end end... At installation time, this commands adds the FILE1.DAT and FILE2.DAT (collected at build time on a Windows or UNIX source host) as members of an existing OS/400 physical file (/QSYS.LIB/MYLIB.LIB/DATA.FILE/FILE1.MBR... FILE2.MBR). In the example, the translate attribute is set to y. This enables translation from ASCII to EBCDIC and code page translation. Translation is performed before the file is added to the OS/400 physical file. Chapter 5. Using Software Distribution on OS/

124 Using Non-OS/400-Specific Functions Running an OS/400 Executable Program You can use the Software Package Editor to add an Execute User Program action to a software package that includes an OS/400 program, such as C, CL, REXX, an exec, or batch job script. At installation time, Software Distribution runs the program on OS/400 subscribers. Note: If the program to be executed is not already on the target machine, you can install it by using the add OS400 object action. An example definition for an installation of an OS/400 program followed by its execution is given at the end of this section. The locations of the user program to be executed, its output and error files are specified in the path, output_file, and error_file attributes of the execute_user_program stanza. When specifying a path, use the convention described in the section The OS/400 Native and Integrated File Systems on page 92. For example, the following stanza adds an action to execute the CL program outmsg:... execute_user_program name = outmsg transactional = n during_install exit codes success = 0,0 failure = 1,65535 end path = \qsys.lib\mylib.lib\outmsg.pgm arguments = first second timeout = -1 unix_user_id = 0 unix_group_id = 0 user_input_required = n output_file = \qsys.lib\mylib.lib\output.file\output.mbr error_file = \qsys.lib\mylib.lib\output.file\error.mbr output_file_append = y error_file_append = y end... At installation time, this action runs the program located at /QSYS.LIB/MYLIB.LIB/OUTMSG.PGM. Program output and error files are created on the OS/400 target system as members of /QSYS.LIB/MYLIB.LIB/OUTPUT.FILE/ ERROR.MBR...OUTPUT.MBR. The following example runs the CL post program that uses the corequisite FILE.DAT file.... execute_user_program transactional = n during_install 104 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

125 Using Non-OS/400-Specific Functions exit codes success = 0,0 failure = 1,65535 end path = \qsys.lib\mylib.lib\post.pgm corequisite_files file name = \usr\sd\target\file.dat destination = \usr\sd\target\file.dat translate = y end end... At build time, this command adds the corequisite file FILE.DAT (collected at build time on a Windows or UNIX source host) to the package. At installation time, this package runs the program located at /QSYS.LIB/MYLIB.LIB/POST.PGM, and uses the corequisite file included in the package. In the example, the translate attribute for the corequisite file is set to y. This enables translation from ASCII to EBCDIC and vice versa or code page translation. Translation is performed before the file is added to the OS/400 target. The following example runs the native C program myprog. This program is included in the software package. As the example shows, the program is added to the OS/400 file system using the Add OS/400 Library and Add OS/400 Object actions. Therefore, the software package that contains these stanzas must be defined using the OS/400 Software Package Editor connected to an OS/400 preparation machine. This is not necessary for the non-native objects shown in the other examples.... add os400_lib location = \qsys.lib name = mylib.lib destination = \qsys.lib\mylib.lib descend = n remote = n os400_obj name = myprog.pgm destination = myprog.pgm target_release = *CURRENT* remote = n replace_option = *ALL end end execute_user_program name = myprogram transactional = n during_install exit_codes success = 0,0 failure = 1,65535 end Chapter 5. Using Software Distribution on OS/

126 Using Non-OS/400-Specific Functions path = \qsys.lib\mylib.lib\myprog.pgm end end... At build time, this command adds the program MYPROG.PGM collected on the OS/400 preparation site) to the package. At installation time, this package adds the program MYPROG.PGM to /QSYS.LIB/MYLIB.LIB and executes it. Saving an OS/400 Software Package When saving software packages from the Software Package Editor, the software packages should be stored on the system database in the built (.spb) format. You should not save packages in an unbuilt format as they cannot be built later. You can then upload such packages, through a gateway, to the Tivoli management region server, which routes the packages to target OS/400 systems. For information about saving software packages in the built format, see Saving the Software Package on page 79. Note: When you build a software package that contains an add action that refers to a native OS/400 object, a *SAVF file containing the source object is created on the OS/400 preparation site and added to the software package block file. For this reason, Software Distribution manages all the OS/400 native objects that can be saved in, and restored from a *SAVF file, including licensed programs. 106 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

127 Chapter 6. Embedding Native Objects into a Software Package This section explains how to use Software Distribution to create a software package that embeds a native installation package. Software Distribution currently supports the following third-party package formats: v Microsoft Setup, in a Microsoft environment v InstallShield, in a Microsoft environment v Microsoft Software Installer (MSI) package, in a Microsoft environment v Package Definition File (PDF), a Microsoft Systems Management Server file v Configuration, installation, and distribution (CID) programs, in an OS/2 environment v AIX, in an IBM AIX environment v Solaris packages and Solaris patches, in a Solaris operating environment. v RPM package, in a Linux environment. v HP-UX package, in an HP-UX environment. Using the Software Package Editor to Embed Native Objects To embed native objects into a software package, use one of the following methods integrated in the Software Package Editor: A Wizard You can use this method on endpoints. It guides you through the creation of a software package that contains a native object. It takes input from a specified native object file. With this method, many of the parameters are taken directly from the object. This method cannot be used to install patches. You use this method if both of the following conditions are met: v The Software Package Editor is running on the operating system to which the native packages belongs. v The Software Package Editor is running on a workstation from where you can access images of the native package. See Using a Wizard on page 112 for a detailed explanation on how to use a wizard. A Step-by-step method You can use this method on endpoints and managed nodes. It uses a series of dialogs to specify values for the parameters needed for the creation of a software package that contains a native object. This method can be used if the native object is not present on the machine where the Software Package Definition file is being edited. You can also use these dialogs to edit objects created using the wizard, to change the default values set in the native object. You use this method if both of the following conditions are met: v The Software Package Editor is running on an operating system different from the one to which the native packages belongs. v The Software Package Editor is running on a workstation from which the images of the native package are not available. Copyright IBM Corp. 2002,

128 Embedding Native Objects in a Software Package See Using Dialogs on page 120 for a detailed explanation on how to use the dialogs. Benefits of Embedding Native Objects Using Software Distribution, you can create and then deploy a software package that contains a native object. This method of distribution has many benefits. For example, you can do the following: v Deploy the software package to a large number of target systems without user interaction, thereby avoiding the complexity of a preliminary deployment to network file servers. v Store information at a central repository regarding the status of the deployed package for each system on the network. v Perform the installation of a native object on a target system. v Define an inventory signature, including a description and version of the product to be installed. See Chapter 13, Integrating Inventory with Software Distribution, on page 271 for a detailed explanation. v Define conditions. See Making a Native Installation Conditional on page 142 for a detailed explanation. v Use the verify operation to identify any problems with the installation. The verify operation for software packages that contain native objects reports the following conditions: When the product is not in a valid install state. In an MSI environment, when features have not been installed with the state specified in the software package. When the components are missing. Note: The verify operation for MSI packages does not identify situations where a later version of a component has been overwritten by the installation. v In MSI and AIX environments, use the repair installation option to repair corrupted elements of a product already installed. For MSI products, when you define the Install MSI Product dialog, you can select Reinstall Mode, which determines the type of repair to be made. Creating a Software Package that Embeds a Native Object A software package object for the installation of a native object defines the following information: v The native package that is to be used for the installation of the product on the target. Using the native object importer tool from the Software Package Editor, you can read information required for creating the software package object directly from the native object if this file is present on the system where you are creating the software package. v The location of product images to be used in the installation. If the product images are not located on a drive that can be accessed by the target systems, they must be included in the software package distribution and then stored in a local directory on the target systems. This is called a bundled installation. Note: Bundled installations require a large amount of disk space to be free on the target. This is because they create an image of the product to be 108 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

129 Embedding Native Objects installed in a specified directory on the target system. These images can be retained or deleted after the installation is complete. For bundled installations, the input native package that you use to install the product on the target must be defined in the directory you indicated in the Source Image Path text box. For MSI packages, the directory structure where the MSI file is located must contain only the images necessary to successfully install the product. If the location of the product images is accessible from the target systems, the software package needs only to contain the path where they can be accessed. This is called a redirected installation. For redirected installations, the input native package that you use to install the product on the target must be defined in the directory you indicated in the Target Image Path text box. The directory structure where the MSI file is located must contain only the images necessary to successfully install the product. v Logging options. v In an MSI environment: Reinstall options, to be used if the package is applied in repair mode. Instructions for installation or non-installation of individual product features. Windows installer properties. Defining Supported Software Distribution Operations in a Native Installation The following tables indicate the supported Software Distribution operations for the following native installation objects: v Microsoft PDF: supports all Software Distribution operations. v MSI package and patch: see Table 2 and Table 3. v AIX package and updates: see Table 4 on page 110 and Table 5 on page 110. v Solaris package and patch: see Table 6 on page 110 and Table 7 on page 110. v Linux package: see Table 8 on page 111. v HP-UX package: see Table 9 on page 111. Table 2. Supported Software Distribution operations for the MSI package native object Software Distribution Operations Install Install transactional Commit Verify Repair Remove Table 3. Supported Software Distribution operations for the MSI patch native object Software Distribution Operations Install Install transactional Commit Chapter 6. Embedding Native Objects into a Software Package 109

130 Embedding Native Objects Table 3. Supported Software Distribution operations for the MSI patch native object (continued) Software Distribution Operations Remove Note: Software Distribution does not perform any action on the object. The entry created in the catalog is removed. Table 4. Supported Software Distribution operations for the AIX package native object Software Distribution Operations Install Install repair AIX Installp Command Options installp -ac Remove installp -u Software Distribution performs a check of the installed filesets and reinstalls them if they are not found. Table 5. Supported Software Distribution operations for the AIX updates native object Software Distribution Operations AIX Installp Command Options Install undoable installp -a Undo installp -r Accept installp -c Notes: 1. When you run an install undoable on a software package that contains an AIX update native object, the path for backup or alternate save directory, if specified, is not created. 2. The Software Distribution force option cannot be used with software packages containing an AIX update native object. Table 6. Supported Software Distribution operations for the Solaris package native object Software Distribution Operations Install Install transactional Commit Verify Remove Undo (rollback of an IP--- package) Solaris Package Command Options pkgadd pkgadd -s spool_dir pkgadd -d spool_dir pkginfo [other options] package instance pkgrm -s package instance pkgrm -s spool_dir Table 7. Supported Software Distribution operations for the Solaris patch native object Software Distribution Operations Solaris Patch Command Options Install patchadd -d Install undoable patchadd Undo patchrm patchid 110 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

131 Embedding Native Objects Table 8. Supported Software Distribution operations for Linux package native object Software Distribution Operations Install rpm -i rpm -f rpm -u Remove rpm -e Verify rpm -v Linux RPM Command Options Table 9. Supported Software Distribution operations for HP-UX package native object Software Distribution Operation Install Install and accept Accept Install undoable Verify Undo Remove Install repair HP-UX Command Options swinstall -s depot software_selection Supported only against patches. Results in the following sequence of commands: 1. swinstall -s depot -x patch_save_files=true software_selection 2. swmodify -x patch_commit=true software_selection Supported only against patches. swmodify -x patch_commit=true software_selection Supported only against patches. swinstall -s depot -x patch_save_files=true software_selection Results in the following sequence of commands: 1. swlist -R software_selection 2. swverify software_selection Supported only against patches. swremove software_selection If the object is a patch that has been accepted, Software Distribution does not perform any action on the object. The entry created in the catalog is removed. Otherwise, the operation results in the following command: swremove software_selection swinstall -s depot -x reinstall=true software_selection Note: The undo operation is allowed only on packages that contain HP-UX native patches. According to the HP-UX behavior, when a patch is committed (In the Software Distribution environment when a patch is accepted), it cannot be removed from the system unless you remove the related application. For this reason, when you remove a software package that contains an HP-UX patch already accepted, Software Distribution removes only the related entry in the catalog. If you want to maintain the capability to remove HP-UX patches you must create a software package to install the application and a software package to install the related patches. Chapter 6. Embedding Native Objects into a Software Package 111

132 Embedding Native Objects: Using a Wizard Using a Wizard Depending on the operating system on which the Software Package Editor is running, you can use a wizard to create a software package that contains a native object. You can create a software package containing native packages for the following platforms: v AIX v Solaris operating environment v Linux v HP-UX v Windows. In a Windows environment you can choose between the following native objects: Microsoft PDF MSI InstallShield MSSetup Note: The wizard cannot be used to create objects for installing native installation patches. Use the appropriate native object dialog. You can use this method if you have access to the native object for the product you want to include in the software package. The wizard prompts for the native object and reads it to set most of the parameters required to define the native object stanza in the software package definition file. The following section contains the following: v An example to create a software package that embeds an MSI installation package using the Install MSI Product Importer wizard. See Using the Install MSI Product Importer on page 113. This procedure is similar for all native installation objects. v An example to import definitions from a PDF file to produce a software package using the PDF Importer wizard. See Using the PDF Importer on page 116. This procedure differs from the others. To launch a wizard to create a software package that embeds a native object, perform the following steps: 1. Launch the Software Package Editor. The Software package Editor Selector dialog is displayed. 2. Select Native Package Technology and click OK. Depending on which operating system you are running the Software Package Editor, you are prompted with one of the following dialogs:. v In a non-windows environment, with the Native Package Technology dialog. Select the type of native object you want to use and click OK. The selection you make in this dialog launches a wizard that guides you in embedding the selected native package into a software package. v In an environment different from Windows, with the Welcome panel of the wizard appropriate for the operating system. You can also launch the MSI Wizard by selecting Tools -> from the menu bar on the Software Package Editor GUI. 112 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

133 Using the Install MSI Product Importer Using the Install MSI Product Importer This section describes how to create a software package that embeds an MSI installation package using the Install MSI Product Importer wizard. An MSI package contains all the information that the Microsoft Windows Installer requires to install or uninstall software products. Usually, each MSI package comprises the following: v An.msi file containing the installation database v Internal, external, or cabinet files required for the installation of the MSI package For detailed information about the Microsoft Windows Installer and related options, refer to the Microsoft Platform SDK documentation. To embed an MSI product in a software package, perform the following steps: 1. Launch the Software Package Editor. The Software Package Editor Selector dialog is displayed. 2. Select Native Package Technology and click OK. The Native Package Technology dialog is displayed. 3. Select Microsoft Product Installer (MSI) and click OK. The wizard starts and displays the Welcome panel. This panel lists the panels included in the wizard. 4. As you move the mouse over any of the listed items, a short explanation appears. Chapter 6. Embedding Native Objects into a Software Package 113

134 Using the Install MSI Product Importer 5. Click Next to advance to the MSI file panel. 6. Enter the path of the MSI file for the product you want to install or click the browse button and navigate to select the file. 7. Click Next to advance to the Application Information panel. 8. Type the path for the Destination folder for the installation, if you know it. Otherwise, do one of the following: v Select a folder or path from the drop-down list. v Click the browse button and navigate to select the folder. The value you enter here is assigned to the INSTALLDIR property. It is the folder on the target system where the product is to be installed. Note: Depending on the MSI package, you cannot edit the content of the Destination Folder. For example, this occurs with Microsoft Office 2000, and Microsoft Project IBM Tivoli Configuration Manager: User s Guide for Software Distribution

135 Using the Install MSI Product Importer 9. Click Next to advance to the Target and Source panel. On this panel, you identify the location of the product images to be used in the MSI installation. 10. If the product images are in a directory that is accessible from the target systems, specify that location in the Target Image Path text box and select the Redirected Installation check box. For redirected installations, the MSI file that you use to install the product on the target must be defined in the directory you indicated in the Target Image Path text box. The directory structure where the MSI file is located must contain only the images necessary to successfully install the product. 11. If the product images are in a directory that is not accessible from the target systems, you must do the following: a. Specify the current location of the product images in the Source Image Path text box. At distribution time, the images are retrieved from this directory and distributed to the target systems as part of the software package. b. In the Target Image Path text box, specify the location of the target system where the product images are to be stored when they are extracted from the software package. This is the directory from which the MSI installation process retrieves the product images during installation. c. To save the images in the path specified in the Target Image Path when installation is complete, select the Keep Images check box. For bundled installations, the MSI file that you use to install the product on the target must be defined in the directory you indicated in the Source Image Path text box. The directory structure where the MSI file is located must contain only the images necessary to successfully install the product. 12. Select the Available to All Users check box, if the installed product is to be available to all users of the target systems. If this check box is cleared, the product is available only to the user who is logged on at installation time. 13. Click Next to advance to the Application Features panel. This panel shows an expandable tree, which lists any application features that can be installed with the MSI product. The wizard obtains these details from Chapter 6. Embedding Native Objects into a Software Package 115

136 Using the Install MSI Product Importer the MSI file that you specified. 14. To change the action to be taken for a feature, do the following: a. In the expanded tree, select the feature you want to change and right-click to display a context menu of available actions. b. Select the action you require. The icon associated with the selected action appears beside the feature in the tree. 15. Click Finish to confirm all your selections and create the software package object. Using the PDF Importer A Microsoft Systems Management Server (SMS) package definition file (PDF) is a text file that contains configuration information that is structured much like a standard initialization file (.INI file) and is used to configure or install an application. It contains predefined workstation, sharing, and inventory property settings. Using the PDF Importer Tool, Software Distribution takes a PDF as input and maps the data contained in the file to specific software package properties. The result is a software package displayed in the Software Package Editor window consisting of a generic container containing a sequence of execute programs, and in some cases, also an add directory action. For example, the distribution of this software package can be used to configure and install an application. See Using the PDF Importer to follow how the PDF Importer is used to configure the installation options of the Norton AntiVirus product. The image directory of the PDF is the directory structure that contains all the files required to support the installation or removal options in the PDF. The importer tool uses the directory structure in creating the software package. The following are required sections in a PDF: [PDF] Identifies the file as a package definition file. Software Distribution supports versions 1.0 and 2.0 of the PDF format and verifies the version of the file in this section. [Package Definition] Defines the overall software package properties. This section contains information such as the name and version of the product, comment 116 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

137 Using the PDF Importer settings, a list of setup variations supported by the package, and the access permissions of the packages created with the PDF. [Setup_Variations] Define the setup variations specified in the Package Definition section. Setup variations specify package commands and supported platforms. For example, Deinstall Setup, Manual Setup, Complete Setup. The following scenario illustrates how to import definitions from a PDF file to produce a software package. The PDF file used in this example is part of the Norton AntiVirus Corporate Edition, Version 7.5, a SYMANTEC 1 product. 1. To launch the PDF Importer Tool, select Native Packaging Technology from the Software Package Editor Selector dialog, and then PDF from the Native Packaging Technology dialog. See Determining the Type of Package You Will Create on page 23 for more information about launching the tool. 2. In the PDF Name text box, enter the path to the NAVCE.PDF file. 3. Perform one of the following actions depending on where the files required for the installation are located: v If the files required for the installation of the AntiVirus application are located in a local path on the source host, enter the directory where the installation executable will be launched on the target system in the Target image path text box. The files required for the installation will be bundled into the software package. v If the installation executable is located in a remote network path, select the Redirected installation check box. If the file images are located on a remote disk, you can mount the remote disk or create an execute program action that mounts the remote disk using the following command: net use remote_disk \\path_name 1. Use of the Norton AntiVirus product requires a license from Symantec Corporation. For more information about the Norton AntiVirus product, refer to the SYMANTEC Web site: Norton AntiVirus and SYMANTEC are trademarks of Symantec Corporation. Chapter 6. Embedding Native Objects into a Software Package 117

138 Using the PDF Importer then specify in the Target image path, the remote disk you mounted or that you specified in the execute program action. For this scenario, do not select this check box. 4. In the Source image path text box, enter the directory structure that contains all the files required to support the installation of the Norton AntiVirus application. The directory tree specified is bundled in the software package as an add file system object. 5. Click Next to display the Package Definition dialog. The importer tool extracts the information contained in this dialog from the Package Definition section of the NAVCE.PDF file. 6. Click Next to display the setup options defined in the NAVCE.PDF file. 118 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

139 Using the PDF Importer A setup dialog is displayed for each setup variation contained in the PDF. Therefore, in the case of the NAVCE.PDF file, a setup dialog is displayed for the Complete, Deinstall, and Manual setup options. Use these panels to customize package commands and arguments. Make any necessary changes so that the information in these panels reflects the target system environment. Click Next to display the successive setup panels. 7. After the last setup panel, the Default setup variation panel is displayed. This panel displays the list of setup variations supported by the NAVCE.PDF file. Select one of the options as the default setup to be used when this software package is installed. The selected default setup variation becomes the value of the $(setup_variations) variable that is created at the end of the import process. 8. Click Finish to complete the importation process. A software package is displayed in the Software Package Editor window. The software package consists of a generic container that contains an add directory action and a series of execute programs. The add directory action contains the directory structure, as specified in the image path that contains all the files required to support the installation. Chapter 6. Embedding Native Objects into a Software Package 119

140 Using the PDF Importer For each setup variation contained in the PDF, a corresponding execute program is generated. However, when you distribute this software package, only the execute program for the default setup variation is executed. A condition which satisfies the value of the default setup variation is set on this execute program action.you can change the default setup variation even after the import process is complete by changing the value of the $(setup_variations) variable in the Variable list editor or using the command line. Note: An error occurs when installing the software package created using the PDF Importer for Norton AntiVirus Corporate Edition, Version 7.5 using the Version 2.0 PDF. To successfully install the package, you must specify the inhibit parsing option for the Complete setup variation. Inhibit parsing prevents the standard parsing of the values defined in the setup arguments. To do this, modify the properties of the Execute Program action. The inhibit parsing option is found on the Execute Program Properties - Advanced dialog. See Editing Software Package Properties on page 74 for more information about modifying properties. Refer to the Reference Manual for Software Distribution for information about the inhibit parsing option. Using Dialogs This section describes how to use the Software Package Editor dialogs to create a software package that contains a native object. You can also use these dialogs to edit objects created using the wizard, to change the default values set in the native object. Using dialogs you can create or edit native object for the following operating systems: v AIX. See Using Dialogs to Embed or Edit an AIX Package on page 121. v Solaris operating environment. See Using Dialogs to Embed or Edit a Solaris Package on page 124. v Linux. See Using Dialogs to Embed or Edit a Linux Package on page 127. v HP-UX. See Using Dialogs to Embed or Edit an HP-UX Package on page 130 v Windows. See one of the following sections: 120 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

141 Embedding Native Objects: Using Dialogs Using Dialogs to Embed or Edit an MSI Package on page 135. The Execute CID Program Action on page 142. The InstallShield Program Action on page 142. The Microsoft Setup Program Action on page 142. To launch the dialogs to create a software package that embeds a native object, perform the following steps: 1. Launch the Software Package Editor. The Software package Editor Selector dialog is displayed. 2. Select General Package and click OK. The Software Package Editor window is displayed. 3. In the Software Package Editor window, select the Program tab and then the appropriate icon. Using Dialogs to Embed or Edit an AIX Package To embed or edit an AIX package in a software package on a system in which no AIX packages exist, or to install an AIX update, you can use a provided set of dialog boxes, as given in the following procedure. To perform these tasks, complete the following steps: 1. In the Software Package Editor window, select the Program tab. 2. Click the AIX icon. The Install AIX Package notebook is displayed. The General page is selected by default. 3. If the images are stored into a file, specify the file name of the AIX package in the AIX Package file text box, and the directory containing this file in the Target Device Path. 4. If the product images are in a directory that is accessible from the target systems, specify that location in the Target Device Path text box and select the Redirected Installation check box. 5. If the product images are in a directory that is not accessible from the target systems, do the following: a. Type the current location of the product images in the Source Device Path text box. At distribution time, the images are retrieved from this directory and distributed to the target systems as part of the software package. b. In the Target Device Path text box, type the location on the target system where the product images can be stored when they are extracted from the software package. This is the directory from which the AIX installation process retrieves the product images during installation. c. To save the images in the Target Device Path location select the Keep Images check box when installation is complete. 6. In the Compression group box, select Deflated to compress the directories and files, or Stored to store the directories and files without compressing them. Chapter 6. Embedding Native Objects into a Software Package 121

142 Embedding Native Objects: AIX Package 7. Select the Advanced Options tab to specify AIX package installation options. 8. In the Path for Backup text box, specify an alternate save directory location for files that are updated and replaced. 9. In the Block Size text box, enter the block size of the installation media. The default is 512 bytes. 10. Select the Expand File System check box to expand any file systems where there is insufficient space to perform the installation. 11. Select the Install Corequisites check box to install the corequisites associated with the filesets specified. 12. Select the Override Files check box so that during the install or update, existing files are replaced and cannot be recovered. 122 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

143 Embedding Native Objects: AIX Package 13. Select the Is Update check box if the package being installed is an update. 14. Select the CDRom Volume check box if a CD-ROM is used as the installation device and you want to suppress multiple volume processing. 15. In the Install group box, select one or a combination of the following options to specify which part of the software product is to be installed: Root Path Specifies to install the / (root) part. Share Path Specifies to install the /usr/share part. User Path Specifies to install the /usr part. Note: Select these check boxes only if you are installing the object in a diskless target system. 16. Select the Log Options tab. 17. Disable logging by selecting the Disabled check box or define the logging options as follows: a. Specify the directory where the AIX log is to be stored. You can enter the path in the Log Path text box or click the browse (...) button to navigate to the directory. b. If you want to report the AIX log entries in the Software Distribution log, select Report Log to the server. 18. Select the Filesets tab to define filesets required for the AIX installation package. 19. To add a fileset, enter the name of the fileset in the text box and click Add. The Filesets dialog is displayed. Use this dialog to define information about the fileset as follows: a. Enter the level of the fileset in the Level text box. b. Enter a description in the Description text box. c. Click OK to close the dialog and save the information to the Filesets page. Chapter 6. Embedding Native Objects into a Software Package 123

144 Embedding Native Objects: AIX Package 20. To remove a fileset, select the fileset in the Filesets group box and click Remove. 21. When you have completed the settings in the Install AIX Package notebook, click OK to create the AIX package installation program object. You can attach conditions to AIX native installation objects, in the same way as you can for other types of software package objects. For an example of how to specify conditions, see Making a Native Installation Conditional on page 142. You can also create an AIX package installation program object using a wizard. See Using a Wizard on page 112 for more information. Using Dialogs to Embed or Edit a Solaris Package To embed a Solaris object in a software package, or to edit the parameters of existing software package objects, you use the Software Package Editor to define the install_solaris_package or install_solaris_patch stanzas, as directed in the following procedure. Note: You can also use these dialogs to edit the parameters of existing software package objects that define Solaris packages, including objects created using the Install Solaris Product wizard. To perform these tasks, complete the following steps: 1. In the Software Package Editor window, select the Program tab. 124 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

145 Embedding Native Objects: Solaris Package 2. Click the Install Solaris Package icon. The Install Solaris Package dialog opens. Note: Because the Install Solaris product and Install Solaris Patch dialog boxes are very similar (the patch dialog boxes do not include a panel for package instances) one set of instructions is given that covers both. 3. In the Caption text box, enter a text string describing the Solaris package installation. 4. In the PKG file text box, specify the Solaris file where the product installation information is defined. If you do not specify the PKG file the content of the Target image path is used to perform the operation. 5. If the product images are in a directory that is accessible from the target systems, specify that location in the Target Image Path text box and select the Redirected Installation check box. 6. If the product images are in a directory that is not accessible from the target systems, you must do the following: a. Type the current location of the product images in the Source Image Path text box. At distribution time, the images are distributed to the target systems as part of the software package. b. In the Target Image Path text box, type the location on the target system where the product images are stored, when they are extracted from the software package. This is the directory from which the Solaris installation process retrieves the product images during installation. c. To save the images in the path specified in the Target Image Path when installation is complete, select the Keep Images check box. 7. In the Compression group box, select Deflated to compress the directories and files, or Stored to store the directories and files without compressing them. Chapter 6. Embedding Native Objects into a Software Package 125

146 Embedding Native Objects: Solaris Package 8. Select the Advanced Options tab. 9. In the Spool directory text box, type the name of the directory where the package is to be stored instead of installing it. This parameter is used when you perform an install transactional operation. 10. In the Admin file text box, specify the fully qualified path name for the installation administration file to be used in place of the default installation administration file. 11. Select Use root path for client, to use the root file system of the client. 12. In the Root path for client text box, type the full path name of the directory to be used as the root path location. All files, including package system information files, are relocated to a directory tree starting in the specified root path. The root path may be specified when installing to a client from a server (for example, /export/root/client). 13. Select Interactive, to perform an installation with user intervention. 14. Select Report output to server, to report to the server the standard output and the standard error of the operation you performed. 15. In the Response file text box, type the fully qualified path name of the file to be used to perform the installation. This file supplies the interaction responses that are requested by the package in interactive mode. 16. Select Remove even if shared, to remove the package even if a file of the package is shared with another application. 17. In the Alternate FS file text box, specify an alternative FS file to map the file systems of the client. For example, you can use it in situations where the $root_path/etc/vfstab file is non-existent or unreliable. 126 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

147 Embedding Native Objects: Solaris Package 18. Select the Package Instances tab. 19. In the text box, specify the name of the package instance and click Add. 20. Define the properties of the package instance in Package Instance Properties dialog that appears. You are then returned to the Package instances page, which then shows the name of the instance. 21. To delete a package instance, select it and click Remove. You can define conditions in the same way you can for other types of software package objects. For an example of how to specify conditions, see Making a Native Installation Conditional on page 142. Using Dialogs to Embed or Edit a Linux Package To embed a RPM package file in a software package, you can use a provided set of dialog boxes, as directed in the following procedure. To perform this task, complete the following steps: 1. In the Software Package Editor window, select the Program tab. Chapter 6. Embedding Native Objects into a Software Package 127

148 Embedding Native Objects: RPM Package 2. Click the Install RPM Package icon. The Install RPM Package notebook is displayed. The RPMFiles page is selected by default. 3. In the Caption text box, type a descriptive text string. 4. To add an RPM file to the package, in the lower text box type the name of the RPM file of the product you want to install, or click the browse button (...) to navigate the file system and select it. Click Add. The RPM File Information dialog is displayed. 5. In the RPM Package File text box type the file name of the RPM package, or use the browse (...) button to navigate the file system, and type the name of the directory containing this file in the Target Device Path text box. If the images to be installed are stored in a directory, type the pathname in the Target Device Path text box. 6. Type the name of the RPM package in the RPM Package Name text box. 7. If the product images are in a directory that is accessible from the target systems, specify that location in the Target Device Path text box and select the Redirected Installation check box. 8. If the product images are in a directory that is not accessible from the target systems, you must do the following: a. Type the current location of the product images in the Source Device Path text box. At distribution time, the images are retrieved from this directory and distributed to the target systems as part of the software package. b. In the Target Device Path text box, type the location on the target system where the product images can be stored, when they are extracted from the software package. This is the directory from which the RPM installation process retrieves the product images during installation. c. To save the images in the Target Device Path location when installation is complete, select the Keep Images check box. 128 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

149 Embedding Native Objects: RPM Package 9. In the Compression group box, select Deflated to compress the directories and files, or Stored to store the directories and files without compressing them. 10. When you have completed the RPM File Information dialog, click OK to save the information and return to the RPMFiles page. 11. To remove an RPM file, select the file in the RPMFiles group box and click Remove. 12. Select the General tab. 13. In the Common Options text box, type any RPM options common to the install, verify and remove operations. 14. In the Install group box, select the options for the install operation. v Install, to install an RPM package. v Update, to upgrade an RPM package, modifying the existing installation. v Freshen, to reinstall a package from scratch. 15. Select the Force Installation check box to perform the installation, ignoring any package or file conflicts. 16. Select the No dependencies check box to ignore any dependency-related problems and to complete the package installation. 17. In the Advanced Options text box, type RPM options for the install operation. 18. In the Verify group box, type RPM options for the verify operation. 19. In the Remove group box, select the No dependencies check box to ignore any dependency-related problems and to complete the package installation. 20. In the Advanced Options text box, type the RPM options for the remove operation. 21. When you have completed the settings in the Install RPM Package notebook, click OK to create the RPM package installation program object. Chapter 6. Embedding Native Objects into a Software Package 129

150 Embedding Native Objects: RPM Package You can attach conditions to RPM native installation objects, in the same way as you can for other types of software package objects. For an example of how to specify conditions, see Making a Native Installation Conditional on page 142. You can also create an RPM package installation program object using a wizard. See Using a Wizard on page 112 for more information. Using Dialogs to Embed or Edit an HP-UX Package To embed a HP-UX package object in a software package, you can use a provided set of dialog boxes, as directed in the following procedure. To perform this task, complete the following steps: 1. In the Software Package Editor window, select the Program tab. 2. Click the HP-UX icon. The Install HP-UX Package notebook is displayed. The General page is selected by default. 3. In the Caption text box, type a descriptive text string. 4. In the HP-UX source depot text box, type the absolute path where the HP-UX source depot is located. If the images to be installed are stored in a file, specify the file name of the HP-UX software depot. Click the browse button (...) to navigate the file system and select it. 5. In the Target Device path text box, type the directory where the product images are stored and from which the installation will be launched. This location must be accessible from all the target systems. It can be a local directory on each target system or a directory on a network drive that is accessible from all the target systems. Click the browse (...) button to navigate the file system and select it. 6. If the product images are in a directory that is accessible from the target systems, specify that location in the Target Device path text box and select the Redirected installation check box. 7. If the product images are in a directory that is not accessible from the target systems, you must do the following: 130 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

151 Embedding Native Objects: HP-UX Package a. Type the current location of the product images in the HP-UX source depot text box. At distribution time, the images are retrieved from this directory and distributed to the target systems as part of the software package. b. In the Target Device path text box, type the location on the target system where the product images can be stored, when they are extracted from the software package. This is the directory from which the HP-UX process retrieves the product images during the specified change management operation. c. To save the images in the Target Device Path location when installation is complete, select the Keep images check box. Note: In this case, all the images in the HP-UX source depot are added in the software package. 8. In the Compression group box, select Deflated to compress the directories and files, or Stored to store the directories and files without compressing them. 9. Select the Advanced tab to specify the advanced options. The Advanced page is displayed. 10. In the Response files catalog text box, type the name of the response file catalog that contains all the response files you can use to perform the required change management operations without user intervention. The response file supplies the interaction responses that are requested by the package in interactive mode. 11. In the Input session file text box, type the name of the input session file that contains the options and operands you used during the previous package. 12. In the Output session file text box, type the name of the output session file where you want to save the options and operands you are defining for the current package. 13. Select the Is a patch to indicate that the you are defining a patch. In this case the installation of the package can be performed in undoable mode so that you can accept or undo the patch at a later time. Chapter 6. Embedding Native Objects into a Software Package 131

152 Embedding Native Objects: HP-UX Package 14. Select the Options tab to specify the options. The Options page is displayed. 15. To define option you can specify an options file, define options individually, or both. To define options perform the following steps: a. In the Options file text box, enter the name of the option file that contains all the options you want to use. You can use variables to express the option file by double right-clicking the mouse button in the text boxes. You can use the browse button (...) to navigate to the file system and select it. b. Define each option you want to use as follows: 1) In the upper text box, type the name of the option or click the arrow to display a list of options. 2) Select an option from the list and then click Add to add it to the list in the lower box. 3) To delete an option, select it and click Remove. For detailed information on the meaning of each option refer to the HP-UX documentation. 132 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

153 Embedding Native Objects: HP-UX Package 16. Select the Log Options tab. The Log Options page is displayed. 17. Disable logging by selecting the Disabled check box or define the logging options as follows: a. Specify the directory where the HP-UX log is to be stored. You can enter the path in the Log Path text box or click the browse (...) button to navigate to the file system and select it. b. If you want to report the HP-UX log entries in the Software Distribution log, select Report Log to the server. 18. Select the Software Selections tab to specify the software selections. The Software Selections page is displayed. 19. To define a software selection you can specify a software file, or a set of software selections, or both. You can specify software selections at product Chapter 6. Embedding Native Objects into a Software Package 133

154 Embedding Native Objects: HP-UX Package level or at bundle level. If you specify a product or a bundle you can also identify a subset of software selections that will be added to the software package. Note: If you do not specify any software selections, all the software selections contained in the HP-UX source depot are included in the HP-UX package. To define software selections perform the following steps: a. In the Software file text box, enter the name of the software file that contains all the software selections you want to use. You can use variables to express the software file by double right-clicking the mouse button in the text boxes. You can use the browse button (...) to navigate to the file system and select it. b. To define additional software selections, perform the following steps: 1) Select Software Selections from the list. 2) Enter the name of the bundle or product in the upper text box and click Add. The Software Selection Properties dialog is displayed. If necessary, enter a revision level and a description of the software selection. 3) Click OK to save the information and close the Software Selection Properties dialog. The bundle or product is added to the list. If you want to define a software selection in a bundle or product. Select the bundle or the product in the list and repeat Steps 2 and Select the GUI Options tab. The GUI Options page is displayed. 21. Leave the GUI Interaction check box unselected if you do not want to define any GUI option or select the GUI Interaction check box and define the following GUI options: v Background v Foreground v Display v Name v XRM 134 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

155 Embedding Native Objects: HP-UX Package If you select this check box the SD Install Software Selection window is displayed when the required change management operation for the HP-UX package is performed. The SD Install Software Selection window will use the XToolkit options you defined in this page. Refer to the XToolkit documentation for a detailed explanation of the GUI options. 22. When you have completed the settings in the Install HP-UX Package notebook, click OK to create the HP-UX package installation program object. You can attach conditions to HP-UX native installation objects, in the same way as you can for other types of software package objects. For an example of how to specify conditions, see Making a Native Installation Conditional on page 142. You can also create an HP-UX package installation program object using a wizard. See Using a Wizard on page 112 for more information. Using Dialogs to Embed or Edit an MSI Package If you do not have the MSI file on the system where you are defining and building your software distribution package file, you can use a set of dialogs that guide your through inputting the details you need to define the install_msi_product or install_msi_patch stanzas. The Install MSI Product and Install MSI Patch dialogs are available from the Program tab of the Software Package Editor. This section describes how to create a software package that contains an MSI Package. The procedure is similar for MSI Patches. Note: You can also use these dialogs to edit the parameters of existing software package objects that define MSI packages, including objects created using the Install MSI Product wizard. To define an MSI package using the dialogs, complete the following steps: 1. On the toolbar of the Software Package Editor window, select the Program tab to display the program action icons. 2. Click the Install MSI Product icon. The Install MSI Product dialog opens. Note: Because the product and patch dialog boxes are very similar (the patch dialog boxes do not include a panel for installable features or a configuration option), one set of instructions is given that covers both. Chapter 6. Embedding Native Objects into a Software Package 135

156 Embedding Native Objects: MSI Packages 3. In the Install or Configure page, select Install Product to install a new product or new product version, or Configure Product to make changes to an already installed product. 136 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

157 Embedding Native Objects: MSI Packages 4. Depending on your selection, the information required on the General page differs. Install Product a. Select the General tab to display the general page related to the Install product option. b. In the Caption text box, type a text string describing the MSI product installation. c. In the MSI file text box, specify the MSI file where the product installation information is defined. d. If the product images are in a directory that is accessible from the target systems, specify that location in the Target Image Path text box and select the Redirected Installation check box. e. If the product images are in a directory that is not accessible from the target systems, you must do the following: v Specify the current location of the product images in the Source Image Path text box. At distribution time, the images are retrieved from this directory and distributed to the target systems as part of the software package. v In the Target Image Path text box, specify the location on the target system where the product images can be stored, when they are extracted from the software package. This is the directory from which the MSI installation process retrieves the product images during installation. v To save the images in the path specified in the Target Image Path when installation is complete, select the Keep Images check box. f. Select Available to All Users to make the product available to all users on the target systems. If you clear this check box, the product is available only to the users who are logged on to the target systems at installation time. g. In the Compression group box, select Deflated to depress the directory and files, or Stored to store the directory and files without compressing them. Chapter 6. Embedding Native Objects into a Software Package 137

158 Embedding Native Objects: MSI Packages Configure product a. Select the General tab to display the general page related to the Configure product option. b. On the General page, type the details of the product you want to configure and the path where it is installed on the target systems. 5. Select the Reinstall Mode tab and select the types of components to be reinstalled if the software package runs with the Repair installation option specified. Table 10 on page 139 describes the mapping between reinstall mode values in Software Distribution and the corresponding MSI command line. 138 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

159 Embedding Native Objects: MSI Packages Table 10. Mapping of Software Distribution reinstall mode values to the MSI command line Software Distribution reinstall mode values Reinstall mode values in MSI command line Description File Missing p Reinstall only if file is missing. File older version o Reinstall if file is missing or if an older version is installed. File equal version e Reinstall if file is missing or an equal or older version is installed. File exact d Reinstall if file is missing or a different version is installed. File verify c Reinstall if file is missing or the stored checksum does not match the calculated value. File replace a Force all files to be reinstalled. User data u Rewrite all required user specific registry entries. Machine data m Rewrite all required machine specific registry entries. Shortcut s Overwrite all existing shortcuts. Package v Run from source and re-cache the local package. 6. Select the Log Mode tab. Disable logging by selecting the Disabled check box or define the logging options as follows: a. Specify the directory where the MSI log is to be stored. You can enter the path in the Log Path text box or click the browse button to navigate to the directory. b. Select the Log Modes by selecting or clearing check boxes. Chapter 6. Embedding Native Objects into a Software Package 139

160 Embedding Native Objects: MSI Packages Note: The log modes shown on the screen are standard SDK log modes. For more details, see the Microsoft Platform SDK documentation. c. If you want to report the MSI log entries in the Software Distribution log, select Report Log. 7. Click the Properties tab to assign values to any Windows Installer properties that are required for the installation. 8. To add a property, do the following: a. Select an appropriate Windows Installer property from the drop-down list and click Add. The property appears in the lower text box. b. Click in the text box and assign a value to the property. For example, TARGETDIR=C:\properties. 9. To remove a property, select the property in the text box and click Remove. 140 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

161 Embedding Native Objects: MSI Packages 10. If the product has additional features that can be installed, click the Features tab. 11. For each feature you want to add, enter the feature name in the upper text box and click Add. The feature is added to the Features tree. Right-click the feature to display a pop-up menu. From the pop-up menu, select the action to be performed on the feature. The default action is to install the feature on the local hard disk. 12. To delete a feature, select it and click Remove. 13. To change the default setting for the user interface level during installation, select the UI level tab. The default setting is none, that is, a silent installation. Chapter 6. Embedding Native Objects into a Software Package 141

162 Embedding Native Objects: MSI Packages Note: Changing the GUI level has no effect unless the installation is completed in disconnected mode. All other installations are silent. 14. When you have completed the settings, click OK to create the software package object. The Execute CID Program Action The IBM configuration, installation, and distribution (CID) architecture provides for the remote, unattended installation and configuration of OS/2 applications that use the OS/2 Software Installer. The OS/2 Software Installer response file (.rsp file) is used as the input. See Adding an Execute CID Program Action on page 56 for a detailed explanation how to use it. The InstallShield Program Action The InstallShield program action enables you to create a program object that runs installations of applications that use the InstallShield installation program. You can use this program action to install an application whose installable files are located on a network drive. Software Distribution uses the application s native installation (InstallShield) to perform a redirected installation. See The InstallShield Program Action on page 76 for a detailed explanation of how to use it. The Microsoft Setup Program Action The Microsoft Setup program action enables you to create a program object that runs installations of Windows applications that use the Microsoft Setup installer. See The Microsoft Setup Program Action on page 78 for a detailed explanation of how to use it. Making a Native Installation Conditional Like other types of software package objects, embedded native packages can be made conditional. You can attach one or more conditions to an object so that, at distribution time, the object is executed only if the conditions are met. 142 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

163 Embedding Native Objects: MSI Packages You define conditions using the Condition Editor, which you can access by selecting the native appropriate installation dialogs from the Program tab of the Software Package Editor window. If you are creating the object using the dialogs, you can define any conditions during creation. If you are creating an object using the wizard, you must add conditions after creation, by opening the object for editing. You can open an object for editing by double-clicking it. This section describes how to define conditions for an MSI package object. The same procedure applies to all the native package objects. To define conditions for an MSI package object, complete the following steps: 1. With the object open in the Install MSI Product or Install MSI Patch dialog, click the Condition button. The Condition Editor window opens. 2. Define an expression by selecting a variable from the list and an operator from the panel and then entering a value. For example, select the variable os_name, the operator == and enter the value Windows_ NT, to construct the expression $(os_name)==windows_ NT. or For example, select the variable os_name, the operator LIKE and enter the value Win* within single quotes, to construct the expression os_name LIKE 'Win*'. Chapter 6. Embedding Native Objects into a Software Package 143

164 Embedding Native Objects: MSI Packages 3. Click OK to return to the Install MSI Product or Install MSI Patch dialog, then click OK again to confirm the change to the object. Defining an Inventory Signature for a Native Package In the same way as for other types of software package objects, you can also define an Inventory signature for a native package. To perform this task follow the procedure described below: 1. With the software package selected in the Software Package Editor main window, select the System action tab. The Set Inventory signature dialog is displayed. 2. Select the Inventory signature icon to display the Set inventory signature dialog. 3. In the File Name text box, type the name of the product. 4. In the File Size text box, type the size of the file in bytes. 5. Select the Add if not existing check box to add the inventory signature to the appropriate table in the configuration repository, if it does not already exist. Optionally enter a description and version number of the product in the Description and Version text boxes. Note: No check is performed on the target endpoint machine after the installation of the package to verify that the signature file actually exists. 144 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

165 Chapter 7. How Does AutoPack Work? This chapter introduces the concepts of AutoPack technology. AutoPack technology is based upon automated detection of both file and system changes that take place during the installation of an application, and packaging those changes within a single software package for distribution to target systems, thus minimizing a system administrator s effort in preparing software for network distribution. You can use AutoPack by selecting AutoPack Technology from the Software Package Editor Selector dialog or by using the autopack command from the command line. See Determining the Type of Package You Will Create on page 23 for more information about using AutoPack from the Software Package Editor. For more information about the autopack command, refer to the Reference Manual for Software Distribution. AutoPack automatically generates a software package by comparing two successive snapshots of a preparation machine. A preparation machine is any Windows, OS/2, or UNIX, refer to the Release Notes for details about supported platforms, on which the Software Distribution Java Endpoint Package Editor component is installed. Perform the AutoPack process on a preparation machine with few or no other applications installed. Because AutoPack relies on differencing technology that detects file and system configurations, using a simple system will avoid file contention. If other applications are installed on the preparation machine before you create the software package, AutoPack might include unwanted data and system files, or exclude vital system files from the software package. It also helps avoid problems associated with shared objects among different applications. You must create a software package on the same operating system as the target machine. Doing this avoids file contention that can result between different operating systems. For example, if you are installing Netscape Navigator on Windows 2000 and Windows XP systems, create a software package on each operating system. Note: Because AutoPack technology automatically detects both file and system changes that take place during the installation of an application, applications that are hardware dependent can create problems. For example, some graphics applications are dependent on monitor type. During the installation of these types of applications, hardware settings are memorized that will cause incompatibility with targets that have different settings than those of the preparation machine. Before you create a software package using AutoPack, it is important to understand how AutoPack works so that you can customize it to satisfy workstations running different operating systems. Copyright IBM Corp. 2002,

166 AutoPack Components AutoPack Components AutoPack enables you to create software packages for distribution to target machines without having to write configuration programs or perform additional installation tasks. It automatically determines the files to be distributed to the target machine and also handles changes to system components such as registry changes, desktop icons, and programs listed on the Start menu. Consider some of the changes that take place on system components when an application is installed on a Windows 2000 system: v A set of files is copied to a target directory. v Entries are added to the Windows Registry. v.ini files are created and modified. v Statements are added to the system files (config.sys, autoexec.bat). v Folders and shortcuts are added to the Windows desktop. v Windows services. AutoPack takes a snapshot of the state of these components before the installation of an application and another after the installation is complete, and then uses differencing technology to identify the changes that have taken place in the state of these components. The differencing phase is the process by which the first and second snapshots are examined and compared. For each difference found, the related action is generated and added to the software package. For example, assume that the c:\winnt\system32\myapp.dll file has been added to the system. The addition of this file is detected during the differencing phase and an action is generated to add this file to the software package. System components vary depending on the operating system. The following table illustrates various components monitored by AutoPack, their corresponding managed objects, and the platforms that support each component. Table 11. Components monitored by AutoPack and supported platforms Component Managed Objects Supported Platforms File system Text files Files, directories, symbolic links (for UNIX platforms) Lines, tokens, and commands Windows profiles (.ini) Sections, items Windows Windows registry Keys, values Windows Windows shell Folders, shortcuts Windows OS/2 profiles Items OS/2 4.0, 4.5 OS/2 desktop OS/2 system files (OS2.ini and OS2SYS.ini) Generic objects, folders, programs, shadows Items All All OS/2 4.0, 4.5 OS/2 4.x and later Windows services Services Windows 2000, Windows XP, Windows IBM Tivoli Configuration Manager: User s Guide for Software Distribution

167 AutoPack Configuration File AutoPack Configuration File This section describes the structure of the AutoPack configuration file autopack.ini for Windows systems, and provides a typical autopack.ini file for UNIX systems. AutoPack uses the configuration file to establish which objects of a given component should be monitored and which objects should be ignored during the differencing phase. AutoPack stores the configuration file in the working directory. The end of this chapter includes the default autopack.ini configuration files for Windows 2000, Windows XP, Windows 2003, OS/2, and UNIX systems. The autopack.ini file has the same structure as a Windows.ini file. It contains a general section and an include and exclude section for each system component. See the table on page 146 for a list of system components and the objects they manage. The include sections list the objects in the related component that must be monitored during the snapshot, while the exclude sections list a subset of the objects in the include section that must be ignored during the differencing phase. For example, you can specify an entire directory structure in the include section, but can exclude specific files contained in this directory by specifying them in the exclude section. If a difference is found in an object listed in the exclude list, the action related to this object will not be included in the software package. Note: It is important that the include sections of the autopack.ini file do not change between the First Snapshot and the Second Snapshot. The autopack.ini file is composed of the following sections: v The General Section. The General section contains the path for the working directory. The default working directory is the autopack directory located under the product directory, for example, c:\swdis\autopack. You can change this default, but the autopack.ini file must be located in the working directory. The following represents the syntax of the general section: [General] WorkingDir = pathname For UNIX systems, the working directory is product_dir/autopack, where product_dir is specified in the swdis.ini file found in the path /etc/tivoli on UNIX systems. See Base Configuration Information on the Endpoint on page 294 for more information about the swdis.ini file. v FileSystem Sections. Use the FileSystem sections to manage the monitoring of file system objects. In the include section, specify the drives that you want to scan. For Windows and OS/2 platforms, the $(system_drive) is always monitored even if you do not add it to the include section. In the exclude section, specify the directories or files that should be ignored during the differencing phase. You can use wildcards in this section. For example, to list all files in the temp directory in the FileSystem Exclude section, use c:\temp\*.* in the list. Refer to the Reference Manual for Software Distribution for more information about specifying file and directory names with wildcards. The following is the syntax for the include and exclude sections for this component: [FileSystem Include] drive_1 drive_2... drive_n [FileSystem Exclude] Chapter 7. How Does AutoPack Work? 147

168 AutoPack Configuration File pathname_1 pathname_2... pathname_n For UNIX systems, you monitor the root (/) or the home drive ($(home)). If you have mounted directories, do not dismount them, they are automatically excluded from the snapshot. Notes: 1. Under the FileSystem Exclude section, exclude the directory containing the Tivoli code. 2. The root is monitored by default. Exclude monitoring the root if the files being installed do not affect the root Monitoring the root can affect performance, especially on very large systems. See the Autopack.ini Default for UNIX Systems on page 155 for a sample UNIX autopack configuration file. v TextFiles Sections. Use these sections to manage the monitoring of text file objects. List the text files to be monitored in the include section, and text files to be ignored during the differencing phase in the exclude section. You can use wildcards in both of these sections. [TextFiles Include] <pathname_1> <pathname_2>... <pathname_n> [TextFiles Exclude] <pathname_1> <pathname_2>... <pathname_n> When AutoPack monitors a file as a text file object, it detects changes that have taken place inside the file, then generates an action in the software package to apply only those changes to the target machine. This differs from monitoring files as file system objects because, when AutoPack monitors file system objects, the entire file is replaced on the target system. To illustrate this, consider monitoring changes to the config.sys file. Monitoring this file as a text file object enables you to replicate only changes to the file, such as adding new lines or deleting lines from the file. Monitoring the file as a file system object results in the entire config.sys file being added to the package and distributed to the target machine. v WinProfiles Sections. Use these sections to manage the monitoring of Windows profiles such as.ini files. In the include section, specify the files you want to monitor. In the exclude section, specify files that must be ignored during the differencing phase. Wildcards can be used in both sections. [WinProfiles Include] pathname_1 pathname_2... pathname_n [WinProfiles Exclude] 148 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

169 AutoPack Configuration File pathname_1 pathname_2... pathname_n Monitor.ini files as WinProfile objects if you want to detect only the changes that take place inside an.ini file. Monitor them as file system objects if you want the entire file packed into the software package for distribution to the target machine. v WinRegistry Sections. Use these sections to manage the monitoring of Windows Registry paths. Specify registry paths to monitor in the include sections and specify registry paths to be ignored during the differencing phase. Wildcards are not permitted in registry paths. [WinRegistry Include] regpath_1 regpath_2... regpath_n [WinRegistry Exclude] regpath_1 regpath_2... regpath_n v OS2Profiles Sections. Use these sections to monitor OS/2 profiles or.ini files except for the OS2.ini and OS2SYS.ini files. These files are treated as OS2SystemFiles objects. Unlike Windows profiles, OS/2 profiles are binary files. Specify profile files you want to monitor in the include section, and specify profile files that must be ignored during the differencing phase in the exclude section. Wildcards can be used in both of these sections. [OS2Profiles Include] pathname_1 pathname_2... pathname_n [OS2Profiles Exclude] pathname_1 pathname_2... pathname_n Monitor.ini files as OS2Profile objects if you want to detect only the changes that take place inside an.ini file. Monitor them as file system objects if you want the entire file packed into the software package for distribution to the target machine. v OS2SystemFiles Sections. The include section of this component contains the OS2.ini and OS2SYS.ini files. Do not modify this section. However, you can modify the exclude section to specify sections of.ini files that must be ignored during the differencing phase. For example, these files contain information about objects on the desktop that are unrelated to the target machine. Exclude those sections containing information about desktop objects by adding them to the exclude section. The following is the syntax for the exclude section: [OS2SystemFiles Include] c:\os2\os2.ini c:\os2\os2sys.ini Chapter 7. How Does AutoPack Work? 149

170 AutoPack Configuration File [OS2SystemFiles Exclude] file:section file:section... file:section v OS2Desktop Sections. The include section of this component contains a list of desktop folders to be monitored. Each folder can be specified by using either the full path name or by using its object ID. Do not modify the exclude section. Wildcards are not permitted in these sections. The following syntax illustrates how desktop folders are specified: [OS2Desktop Include] pathname_1 OR object-id_1 pathname_2 OR object-id_2... pathname_n OR object-id_n Customizing the Configuration File AutoPack creates the configuration file the first time it runs. Each section contains defaults based on the workstation configuration. These defaults are set to satisfy the most widely detected operating systems on workstations. For example, because most installation procedures modify the same registry keys, the WinRegistry Include section is set to monitor the following registry paths: HKEY_LOCAL_MACHINE\SOFTWARE HKEY_CURRENT_USER HKEY_USERS\.Default HKEY_LOCAL_MACHINE\System\CurrentControlSet You can add an object to its related exclude section to ignore any changes in that object and avoid including this change in the software package, or you can add an object to its related include section to monitor any changes in that object and include those changes in the software package. The WinRegistry Exclude section contains registry keys that do not need to be monitored. These are keys that have no part in the installation of software and should not be included in the software package. For example, the following registry path is excluded: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib This registry path is used for statistical information regarding the machine and changes constantly independent of the installation of an application. The WinProfiles Exclude section contains files that do not need to be monitored. For example, the winit.ini file is listed in this section by default. This file contains information regarding files that should be deleted after restarting the system and have nothing to do with the installation of an application. The file system drive to be monitored is configured for Windows systems by default. You may need to edit the autopack.ini file several times if the default settings are not applicable to your system components. For UNIX systems, you may need to personalize the FileSystem Include section. To minimize monitoring time, you can specify a subset of file systems rather than indicating the root to avoid monitoring every file system on the target system. 150 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

171 AutoPack Configuration File Notes for Certain User Scenarios There are certain user scenarios which require customizing the autopack.ini file to achieve a successful installation of the software package generated using AutoPack. The following points describe known scenarios which require some user intervention: 1. When the differencing phase is launched from the Software Package Editor, the process hangs if the software package being created contains a large number of objects. To improve performance, you need to tune the -mx100m value in the speditor.bat file. Raise the value gradually by small increments until you find the optimal value for your environment. For example, replace mx100m with mx150m and then continue to increase this value until the machine performance improves. 2. For distributions that update Windows system files, which could be locked in read or write, it is advisable to perform the installation in undoable-intransactional mode. In such a case, a backup copy of the locked files is made during the commit phase. 3. When you create a software package using AutoPack that installs the Norton AntiVirus product on a Windows 2000 endpoint, the distribution fails if the following registry key is included in the software package: HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\ServiceCurrent For a successful distribution, add the registry key to the WinRegistry Exclude section. 4. When you create a software package using AutoPack that installs the Norton AntiVirus product, you must wait for LiveUpdate and disk scan to complete successfully and reboot the system before taking the second snapshot. This procedure prevents problems due to locked files. 5. The OverrideRegistryPermissions option must be set to y (yes) if you are running any of the following user scenarios: v Create a software package using AutoPack for the DB2 client software and install the software package on a Windows 2000 endpoint. v Create a software package using AutoPack for the Exceed 6.1 software and install the software package on a Windows 2000 endpoint. v Create a software package using AutoPack for Microsoft Office 2000 software and install the software package on a Windows 2000 endpoint. Alternatively, add the following entry in the WinRegistry Exclude section of the autopack.ini file: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\ ServiceCurrent 6. Create a software package using AutoPack for Microsoft Office 2000 software. If you perform an undoable installation of the software package on a Windows 2000 endpoint, you must increase the amount of virtual memory to at least 400 MB. 7. When you create a software package using AutoPack that installs Microsoft Office XP software on a Windows XP endpoint, set the following keys in the autopack.ini file: v In the General section: OverrideRegistryPermission=y v In the WinRegistry Exclude section: HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\ServiceCurrent Chapter 7. How Does AutoPack Work? 151

172 AutoPack Configuration File Dealing with Shared Objects The preparation machine should have only a minimum set of applications installed: the operating system and AutoPack. Besides preventing file contention, this helps avoid problems associated with shared objects. Many Windows applications share objects such as files and registry entries. To avoid reinstalling objects that have already been installed by an application on a workstation, Microsoft suggest using a reference counter stored in the following registry path: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\ CurrentVersion\SharedDLLS Not all applications use this registry path to store their reference counters. Apple QuickTime, for example, stores shared files under the following registry path: HKEY_LOCAL_MACHINE\SOFTWARE\Apple\QuickTime32\CurrentVersion \SharedFiles Other applications do not use reference counters. Consider the case of a file and registry entry common to both an application already installed on the preparation machine, and an application to be installed between the first and second snapshot. As already mentioned, shared objects will not be reinstalled. Therefore, during the differencing phase, AutoPack includes the shared file and registry entry as part of the software package. The file and registry entry were present before the installation and no changes occurred to these files after the installation. No commands are generated to add this file and registry entry. AutoPack can minimize the problems associated with shared objects by monitoring reference counters. Autopack.ini Default for Windows 2003 [General] OverrideRegistryPermissions=n ReplaceIfNewer=n RemoveIfModified=n ReplaceIfExisting=y ComputeCRC=n VerifyCRC=n WorkingDir=C:\swdis\autopack [FileSystem Include] C:\ [TextFiles Include] c:\autoexec.bat c:\config.sys [TextFiles Exclude] [WinRegistry Include] HKEY_LOCAL_MACHINE\SOFTWARE HKEY_CURRENT_USER HKEY_USERS\.Default HKEY_LOCAL_MACHINE\System\CurrentControlSet [WinRegistry Exclude] HKEY_LOCAL_MACHINE\SAM HKEY_LOCAL_MACHINE\System\Clone HKEY_LOCAL_MACHINE\SOFTWARE\Program Groups HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\SharedDLLs HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib HKEY_LOCAL_MACHINE\System\CurrentControlSet\Enum HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services 152 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

173 AutoPack Configuration File HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Reliability HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\PendingFileRenameOperations [WinProfiles Include] C:\WINDOWS\*.ini [WinProfiles Exclude] C:\WINDOWS\progman.ini C:\WINDOWS\wininit.ini C:\WINDOWS\swdis.ini [FileSystem Exclude] C:\Documents and Settings\Administrator\Local Settings\Temp\*.* C:\swdis\*.* C:\WINDOWS\swdis.* C:\WINDOWS\*.grp c:\boot.ini *\win386.swp *\pagefile.sys C:\WINDOWS\*.ini c:\autoexec.bat c:\config.sys??\recycler\*.*??\recycled\*.* C:\WINDOWS\system32\config\*.* *.lnk C:\WINDOWS\APPLOG\*.* C:\WINDOWS\SchedLgU.Txt C:\WINDOWS\DEBUG\*.* C:\*\ntuser.dat.log C:\*\ntuser.dat C:\WINDOWS\prefetch\*.* *\hiberfil.sys C:\*\UsrClass.dat C:\*\UsrClass.dat.LOG Autopack.ini Default for Windows XP [General] WorkingDir=C:\swdis\autopack [FileSystem Include] C:\ [TextFiles Include] c:\autoexec.bat c:\config.sys [TextFiles Exclude] [WinProfiles Include] C:\WINDOWS\*.ini [WinProfiles Exclude] C:\WINDOWS\progman.ini C:\WINDOWS\wininit.ini C:\WINDOWS\swdis.ini [FileSystem Exclude] C:\DOCUME~1\ADMINI~1\LOCALS~1\Temp\*.* C:\swdis\*.* C:\WINDOWS\swdis.* C:\WINDOWS\*.grp c:\boot.ini *\win386.swp *\pagefile.sys C:\WINDOWS\*.ini c:\autoexec.bat c:\config.sys??\recycler\*.*??\recycled\*.* C:\WINDOWS\System32\config\*.* *.lnk C:\WINDOWS\APPLOG\*.* Chapter 7. How Does AutoPack Work? 153

174 AutoPack Configuration File C:\WINDOWS\SchedLgU.Txt C:\WINDOWS\DEBUG\*.* C:\*\ntuser.dat.log C:\*\ntuser.dat C:\WINDOWS\prefetch\*.* *\hiberfil.sys C:\*\UsrClass.dat C:\*\UsrClass.dat.LOG C:\Tivoli\*.* [WinRegistry Include] HKEY_LOCAL_MACHINE\SOFTWARE HKEY_CURRENT_USER HKEY_USERS\.Default HKEY_LOCAL_MACHINE\System\CurrentControlSet [WinRegistry Exclude] HKEY_LOCAL_MACHINE\SAM HKEY_LOCAL_MACHINE\System\Clone HKEY_LOCAL_MACHINE\SOFTWARE\Program Groups HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\SharedDLLs HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib HKEY_LOCAL_MACHINE\System\CurrentControlSet\Enum HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Reliability HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\ Session Manager\PendingFileRenameOperations Autopack.ini Default for Windows 2000 [General] WorkingDir=C:\Tivoli\swdis\1\autopack [TextFiles Include] c:\autoexec.bat c:\config.sys [TextFiles Exclude] [FileSystem Exclude] C:\DOCUME~1\ADMINI~1\LOCALS~1\Temp\*.* C:\Tivoli\swdis\1\*.* C:\WINNT\swdis.* C:\WINNT\*.grp c:\boot.ini *\win386.swp *\pagefile.sys C:\WINNT\*.ini c:\autoexec.bat c:\config.sys??\recycler\*.*??\recycled\*.* C:\WINNT\System32\config\*.* *.lnk C:\WINNT\APPLOG\*.* C:\WINNT\SchedLgU.Txt C:\WINNT\DEBUG\*.* C:\*\ntuser.dat.log C:\*\ntuser.dat C:\WINNT\prefetch\*.* [FileSystem Include] C:\ [WinRegistry Include] HKEY_LOCAL_MACHINE\SOFTWARE HKEY_CURRENT_USER HKEY_USERS\.Default HKEY_LOCAL_MACHINE\System\CurrentControlSet [WinRegistry Exclude] HKEY_LOCAL_MACHINE\SAM HKEY_LOCAL_MACHINE\System\Clone HKEY_LOCAL_MACHINE\SOFTWARE\Program Groups 154 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

175 AutoPack Configuration File HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\SharedDLLs HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib HKEY_LOCAL_MACHINE\System\CurrentControlSet\Enum HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Reliability HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\PendingFileRenameOperations [WinProfiles Include] C:\WINNT\*.ini [WinProfiles Exclude] C:\WINNT\progman.ini C:\WINNT\wininit.ini C:\WINNT\swdis.ini Autopack.ini Default for UNIX Systems [General] CompressionMethod=deflated ReplaceIfNewer=n RemoveIfModified=n ReplaceIfExisting=y ComputeCRC=n VerifyCRC=n WorkingDir=/endpoint/swdis/1/autopack [TextFiles Include] [TextFiles Exclude] [FileSystem Exclude] /mnt/* /tmp/* /endpoint/swdis/1/* /dev/* /etc/tivoli/swdis.* */.sh_history [FileSystem Include] / Autopack.ini Default on OS/2 Systems [General] ReplaceIfNewer=n RemoveIfModified=n ReplaceIfExisting=y ComputeCRC=n VerifyCRC=n WorkingDir=C:\TIVOLI\swdis\1\autopack [FileSystem Include] C:\ [TextFiles Include] C:\config.sys C:\autoexec.bat C:\startup.cmd C:\os2init.cmd [TextFiles Exclude] [OS2Profiles Include] [OS2Profiles Exclude] [FileSystem Exclude] C:\TCPIP\TMP\*.* C:\TIVOLI\swdis\1\*.* C:\OS2\swdis.* C:\OS2\*.ini C:\OS2\os2.!!! C:\OS2\os2sys.!!! *\SWAPPER.DAT C:\config.* C:\autoexec.* C:\startup.* Chapter 7. How Does AutoPack Work? 155

176 AutoPack Configuration File C:\os2init.* C:\OS2\SYSTEM\RAS*.*?:\EA DATA. SF?:\WP ROOT. SF C:\\dmisl\*.* C:\\mptn\*.* 156 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

177 Chapter 8. Generating a Software Package Using AutoPack AutoPack automatically generates a software package by reproducing the results of an installation on a preparation machine. For information about how AutoPack technology works, see Chapter 7, How Does AutoPack Work?, on page 145. In this chapter, the AutoPack guided process is used to create a software package that replicates the installation of Adobe Reader 6.0 by performing the following tasks: v Scanning drives on the preparation machine where software will be installed to create a first snapshot, or preinstallation snapshot, of the drive and system configurations. (It is important that the preparation machine have few or no other applications installed. The machine must also be of the same operating system type as the target PC.) v Bundling the file and system changes that result from installing software on the preparation machine for distribution to target machines. v Taking a second snapshot, or post-installation snapshot, of the preparation machine drive and identifying the installed files and system changes. v Creating a software package based on the difference between the first and second snapshots. AutoPack technology is integrated into the Software Package Editor. You can choose to launch either the Guided Process, which guides you through the AutoPack process step-by-step from start to finish, or you can launch each step separately if you need to customize the preparation machine between steps. Guided Process To launch the Guided Process you can either select AutoPack Technology from the Software Package Editor Selector dialog, or select General Package from the Selector dialog, and then AutoPack->Guided Process from the Software Package Editor menu bar. Step-by-step To launch each step sequentially, select General Package from the Selector dialog, then AutoPack from the menu bar of the Software Package Editor, and then select the options in the following order: 1. First Snapshot 2. Second Snapshot 3. Differencing Refer to this chapter and the online help for more detailed information about these dialogs. Notes: 1. This procedure can be executed locally on a disconnected machine using the command line interface. Refer to the autopack command in the Reference Manual for Software Distribution. 2. You cannot use AutoPack to create software packages that perform operating system upgrades and installations. Copyright IBM Corp. 2002,

178 Running AutoPack Running AutoPack Use a Windows 2000 workstation as the preparation machine to create the Adobe Reader software package for Windows 2000 targets. Run AutoPack on the same operating system as the target system. 1. Verify that the preparation machine has few or no applications installed. To check the applications installed on a Windows 2000 system, select Add/Remove Programs from the Windows Control Panel. You might also want to refer to the Windows Start->Programs menu, because not all application installations add an entry to the Windows Add/Remove Programs group. 2. To launch the AutoPack guided process, select AutoPack Technology from the Software Package Editor Selector dialog as explained in Determining the Type of Package You Will Create on page 23. The AutoPack Guided process provides an easy-to-use wizard that guides you step-by-step through the creation of a software package. An introductory dialog is displayed. 3. Click Next to proceed with the first snapshot. Creating the First Snapshot The first snapshot is a preliminary snapshot of the preparation machine drive and system configuration before the installation of Adobe Reader. AutoPack scans the specified drive and stores the current configuration information and directory structure in the working directory. 158 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

179 Creating the First Snapshot 1. Begin the process of creating the first snapshot by completing the General Options dialog. This dialog corresponds to the General section of the autopack.ini file, as this is where the working directory is specified. See AutoPack Configuration File on page 147 for more information about the autopack.ini file. In the Working directory text box, specify the directory name where you want to temporarily store the results of the snapshots. This directory contains the output files of the first and second snapshots. The default is <product_directory>\autopack. The <product_directory> default value is located in the <system_root>\swdis.ini file if you are working in a Windows or OS/2 environment, or in the /etc/tivoli/swdis.ini file if you are working in a UNIX environment. See Checking Configuration Files on page 294 for more information about the swdis.ini file.you can change the default by modifying the autopack.ini file. 2. In the Drives to monitor scrolling list, specify the drives that you want to monitor during the first and second snapshots. You can specify more than one drive. The default is your system drive. Note: Using AutoPack on a Linux system, you might be required to modify the default path to monitor from /root (the HOME directory of root user) to /. Normally, /root is not an installation directory where the root user installs software. 3. Leave the Customize system monitoring check box selected to specify objects to monitor or exclude during the differencing phase, such as text files, registry entries, or.ini files. If AutoPack detects any differences in the objects that you specify to monitor, the related action is included in the software package. AutoPack ignores any differences found in the objects you specify to exclude during the differencing phase. Click Next to display the Text Files to Include dialog. If you do not select this check box, AutoPack proceeds to the Software Installation Options dialog found in step 10 on page 163. Chapter 8. Generating a Software Package Using AutoPack 159

180 Creating the First Snapshot In the Text Files to Include dialog, indicate the files that you want to monitor during the differencing phase. This dialog corresponds to the Text Files section of the autopack.ini file explained on page 148. The Text Files section also explains the difference between monitoring files as text file objects as opposed to file system objects. The Text Files to Include dialog lists some files that AutoPack monitors by default. These files are usually operating system files. It is recommended that you do not remove the files listed here. You can, however, add text files to be monitored by clicking Add files or delete other files from the list by selecting Remove. Note: The default files to include and exclude are different for each supported platform. Windows, OS/2, and UNIX list different default files to include and exclude. 4. Click Next to display the Text Files to Exclude dialog. In this dialog, indicate the files that must be ignored during the differencing phase. You can, for example, exclude a subset of the objects specified in the 160 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

181 Creating the First Snapshot corresponding include dialog. If any differences are found in these objects during the differencing phase, their related actions are excluded from the software package. 5. Click Next to display the Registry Entries to Include dialog. In this dialog, you can specify registry paths that you want to monitor during the differencing phase. Click Add to add new entries to the list or click Remove to remove selected entries from the list. This dialog corresponds to the WinRegistry section of the autopack.ini file explained on page Click Next to display the Registry Entries to Exclude dialog. Specify registry paths to ignore during the differencing phase. In this dialog, add entries that contain information that is not used for the installation of the application. For example, the following entry is already in the exclude dialog by default because it contains performance information of the target system that is not applicable to the installation of the application: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ Windows NT\CurrentVersion\Perflib Chapter 8. Generating a Software Package Using AutoPack 161

182 Creating the First Snapshot 7. Click Add to add new entries to the exclude list, or click Remove to remove selected entries from the list. 8. Click Next to display the Win Profiles to Include dialog. The listed.ini file is a default setting monitored by AutoPack. This dialog corresponds to the WinProfiles section of the autopack.ini file explained on page 148. Add files that you want to monitor during the differencing phase by clicking Add files. Remove a selected file from the list by clicking Remove. Click Next to display the Win Profiles to Exclude dialog. Specify.ini files to ignore during the differencing phase. Click Add files to add new files to the default list, or click Remove to remove selected files from the list. 162 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

183 Creating the First Snapshot 9. Click Next to display the System Files to Exclude dialog. This dialog contains a list of files and directories that are excluded by default. Add any files or directories that you want to ignore during the differencing phase. If differences are found in these files or directories during the differencing phase, they are excluded from the software package. This dialog corresponds to the FileSystem section of the autopack.ini file explained on page 147. Note: You must include the following directories in the System Files to Exclude list: v The directory where you installed the endpoint. The default is C:\Program Files\LCF. v The directory where you installed the server. The default is C:\Tivoli. 10. Click Next. The Software Installation Options dialog is displayed. In this dialog, you can choose from two installation options: v Manual installation Chapter 8. Generating a Software Package Using AutoPack 163

184 Creating the First Snapshot Manual Installation Option v Automatic installation The following sections describe these installation options. You can install the Tivoli desktop software manually by selecting Manual Installation from the Software Installation Options dialog. The manual installation option interrupts the AutoPack Guided Process to allow you to install the software. You choose when to resume with the second snapshot by relaunching the AutoPack Guided Process. 1. Select Next on the Software Installation Options dialog to display the Software Package Properties dialog. 2. Replace the default software package name, MyPackage, with AcroReader. 3. Leave the default value 1.0 in the Version text box. 4. Select the appropriate check boxes: Verify CRC When this option is selected, when checking the identity of the source and target files, Software Distribution compares their cyclic redundancy check (CRC) values. Use this option together with Replace if existing to verify if an existing file must be replaced. Compute CRC When this option is selected, after the installation of a file, Software Distribution compares the CRC of the file installed on the target machine with the corresponding file in the package to check whether the file was corrupted during distribution or installation. Replace if existing This option specifies to replace an object that already exists on the target. It is selected by default. Remove if modified This option specifies to remove the object even if the target object has been modified. 164 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

185 Manual Installation Option Override Registry Permissions If this option is selected, access permissions for adding or removing protected registry keys and values are temporarily overridden, then restored after the operation is completed. 5. Click Next to display a dialog listing the steps to be performed. Because you selected manual installation, the steps to be performed are the first snapshot and the manual installation. The remaining steps are executed after you have fully installed Adobe Reader and have relaunched the AutoPack guided process. 6. Select Finish to launch the execution of the first snapshot. Note: Some installations recommend that you close active applications before proceeding with the installation. Select the Close the Software Package Editor check box to close the Software Package Editor before beginning the manual installation. Doing this maximizes use of resources. Upon completion of the installation procedure, you can resume with the second snapshot by launching the Software Package Editor and selecting AutoPack->Guided Process. AutoPack reminds you that a previous AutoPack procedure has not been completed and asks if you would like to resume the procedure. 7. When the first operation is complete, AutoPack exits from the AutoPack Guided Process and prompts you to begin the manual installation. 8. Install Adobe Reader 6.0 as you normally would. Regardless of how you run the executable, be sure to close all applications. 9. When the installation is complete, you can resume the second snapshot. Resuming the Second Snapshot After you have installed the software, resume the second snapshot and the creation of the software package. 1. Launch the Software Package Editor and select AutoPack Technology from the Software Package Editor Selector dialog. Chapter 8. Generating a Software Package Using AutoPack 165

186 Resuming the Second Snapshot An introductory dialog is displayed. 2. Click Next and AutoPack displays a message that asks if you would like to resume with a previously initiated AutoPack process, or if you want to ignore the previous installation and start a new AutoPack process. 166 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

187 Resuming the Second Snapshot 3. Click Next. AutoPack displays the software package properties specified before the first snapshot was performed. You can edit this information if necessary. 4. Click Next. AutoPack displays the remaining operations to be performed. 5. Click Finish to begin creating the second snapshot. Chapter 8. Generating a Software Package Using AutoPack 167

188 Resuming the Second Snapshot 6. At the completion of the second snapshot, the AcroReader software package and its contents are displayed in the Software Package Editor window. You can use the Software Package Editor tools to customize the package properties. See Editing Software Package Properties on page 74 for details on modifying software package properties. See Saving the Software Package on page 79 for details on saving the package in different formats. Before building the software package, check the AutoPack result in the Software Package Editor and remove any unwanted objects. After you have built the software package, you can test it by using the disconnected command line interface (CLI) commands. Refer to the Reference Manual for Software Distribution for more information about disconnected CLI commands. The Automatic Installation Option Using the AutoPack Guided Process, you can select either Automatic Installation or Manual Installation to install the application. When you choose the automatic installation option, the installation executable specified is launched during the guided process, and AutoPack automatically resumes with the second snapshot after the installation is complete. Using the automatic installation option, you can install only a single application; that is, you can specify only one executable. Note: Using the AutoPack Guided Process, the automatic installation option does not function properly with certain applications, such as Tivoli applications and WinZip software. AutoPack is unable to detect when the installation is complete. The first snapshot is created correctly and the setup executable of the application is launched automatically. However, AutoPack erroneously starts the second snapshot before the installation is complete, which creates an incorrect differencing result. In this case, use the manual installation option to install the software. 168 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

189 The Automatic Installation Option 1. In the Program text box of the Software Installation Options dialog, enter the drive and path to the application s installation setup program. 2. Click Next to display the Software Package Properties dialog. The rest of the procedure is similar to the manual installation option. Complete the Software Package Properties dialog. See page 164 for more information about this dialog. Chapter 8. Generating a Software Package Using AutoPack 169

190 The Automatic Installation Option 3. Click Next. A list of operations to be executed is displayed. Note: Some installations recommend that you close active applications before proceeding with the installation. Select the Close the Software Package Editor check box to close the Software Package Editor before beginning the automatic installation. Doing this maximizes use of resources. Upon completion of the installation procedure, you can resume with the second snapshot by launching the Software Package Editor and selecting AutoPack->Guided Process. AutoPack reminds you that a previous AutoPack procedure has not been completed and asks if you would like to resume the procedure. 4. Click Finish and AutoPack begins to execute each operation, adding a check mark to the left of each operation upon its completion. When the automatic installation is run, the application s setup program is executed and the software is installed. Upon completion of the automatic installation process, AutoPack automatically resumes with the second snapshot. 170 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

191 The Automatic Installation Option At the completion of the final operation, the Software Package Editor window displays the software package generated by AutoPack. You can use the Software Package Editor to customize it. See Editing Software Package Properties on page 74 for information about modifying the properties of the software package. See Saving the Software Package on page 79 for information about saving the software package in different software package formats. Chapter 8. Generating a Software Package Using AutoPack 171

192 The Automatic Installation Option 172 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

193 Part 2. Planning and Distributing Software Packages Chapter 9. Preparing a Software Package for Distribution Creating a Software Distribution Profile Setting the Profile Subscribers Importing a Software Package into the Tivoli Environment Creating a New Software Package and Importing it into a Software Package Profile Importing an Existing Software Package into a Software Package Profile Deleting a Software Package Profile Software Package Properties Calculating the Size of a Software Package Converting a Software Package Not-built to Built Built to Not-built Exporting a Software Package Change Management Operations Software Package States Executing Change Management Operations Installing a Software Package Removing a Software Package Undoing a Software Package Accepting a Software Package Committing a Software Package Verifying a Software Package Loading and Unloading Software Packages 195 Customizing the GUI Settings Installing the Appsample^1.0 Software Package 196 Advanced Options Change Management Operation Modes Overwriting Default Variables Defining Distribution Settings Notifying Users of a Distribution Distributing Software Packages to Mobile Targets Installing the Device Object Software Package 210 Distributing Nested Software Packages Things To Consider Nested Package Distribution Scenario Checking the Outcome of a Distribution Checkpoint Restart Service for Network Failure or Power Interruptions Example Scheduling a Distribution Chapter 10. Using Data Moving Configuring the Data Moving Service Data Moving Scenarios Sending Data to Multiple Destinations Data Retrieval from Multiple Origins Deleting a File on Multiple Systems Moving Files from Endpoint to Endpoint Defining the Advanced Options Using Pre- and Post-Processing Scripts Examples The Data Moving Service in an OS/400 Environment Chapter 11. Configuring a Network Topology 235 Introducing NoonTide Network Architecture Creating a Repeater Hierarchy Configuring Repeater Sites Setting Repeater Parameters Step 1: List the Current Settings of the Repeaters Parameters Step 2: Determine the Disk Space Requirements of the Applications to be Distributed Step 3: Check that the Electron and Pescado Sites Have the Required Disk Space and Memory Step 4: Set Electron s Repeater Parameters 248 Step 5: Set Pescado s Repeater Parameters 248 Step 6: Verify that the Repeater Parameters are Set Correctly Step 7: Restart the Repeater How Software Distribution Works Software Distribution Methods Software Distribution Scenarios Scenario 1: Distributing from a Tivoli Management Region Server through a Gateway. 254 Scenario 2: Distributing from a Source Host/Tivoli Management Region Server to a Repeater Distributing the SP^1.0 Software Package to GW1 and GW Distributing from a File Server Scenario 3: Distributing from a Source Host through Repeater Depots Scenario 4: Distributing from a Tivoli Management Region Server to a Mobile Endpoint Installing Images from a CD-ROM Scenario 5: Performing Data Moving Operations 260 Chapter 12. Integrating the Tivoli Enterprise Console Enabling the Tivoli Enterprise Console Steps to Enable the Integration The tecad_sd.conf File Creating the Software Distribution Console Software Distribution Classes Chapter 13. Integrating Inventory with Software Distribution Configuration Repository Query Facility Describing Software Distribution Tables How the Integration Works Copyright IBM Corp. 2002,

194 Enabling and Disabling the Historical Database and Change Management Status Exchanging Information between Software Distribution and Inventory Defining an Inventory Signature Creating the INVENTORY_QUERIES Running an INVENTORY_QUERY Desktop Command Line Modifying SWDISTDATA_QUERY Desktop Command Line Chapter 14. Upgrading Windows 2000 Professional to Windows XP Environment Configuration Creating a Response File Copying the Files That You Need to Perform the Migration to the Tivoli Server Copying the Windows XP Files to the Image Server 285 Customizing the Inst_wXP.spd Software Package Definition File Creating the Software Package on the Tivoli Server 286 Subscribing the Endpoints to the Upgrades Profile Manager Distributing the Software Package to the Tivoli Endpoints Using the Check_OS^1.0.spd to Verify the Upgrade 287 Chapter 15. Troubleshooting Troubleshooting Process Hints and Tips Improving Performance Setting the Number of Endpoints to Be Handled 293 Setting the Report Timeout for the Server Setting the Number of Threads Checking Configuration Files Base Configuration Information on the Distribution Server and Source Host Base Configuration Information on the Endpoint 294 Software Distribution Logs Software Package Log Example Software Distribution Server Log 298 Data Moving Logs Example Log Log Object List Notices and Mail Tivoli Enterprise Console Configuration Repository Examining the SPD File Troubleshooting the Software Package Editor GUI 305 Checking Repeaters, Gateways, and Endpoints Setting Timeout Values for a Distribution Repeater Timeout User Program Timeout Verifying Setup for Endpoints Checking lost-n-found Checking the Default Directory on a Target System IBM Tivoli Configuration Manager: User s Guide for Software Distribution

195 This part describes how to plan and perform Software Distribution operations, perform operating system upgrades, and use the integration of Inventory and the Tivoli Enterprise Console with Software Distribution. Locating Related Information Information related to these tasks is available from the following sources: v Introducing IBM Tivoli Configuration Manager. This provides an overview of Software Distribution. v Reference Manual for Software Distribution This includes information about how to perform these same tasks from the command line. v Planning and Installation Guide. This includes information about how you install Software Distribution. v Messages and Codes. This provides details of all messages generated by the IBM Tivoli Configuration Manager components and services. v User s Guide for Inventory Provides detailed information about managing hardware and software using Inventory. v IBM Tivoli Enterprise Console: User s Guide and IBM Tivoli Enterprise Console: Adapters Guide Provide detailed information about integrating network, systems, database, and application management with Tivoli Enterprise Console Part 2. Planning and Distributing Software Packages 175

196 176 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

197 Chapter 9. Preparing a Software Package for Distribution This chapter describes how you prepare software packages for distribution in the Tivoli environment. From the Tivoli desktop, you can define software packages, associate them with target machines, and distribute them to those machines, in parallel, in the same or different Tivoli management regions. You use the Tivoli desktop to import software packages into the Tivoli environment, in which you can perform Software Distribution operations. The desktop supports all the operations that you can perform from the command line interface (CLI). For information about commands, refer to the Reference Manual for Software Distribution. To perform Software Distribution tasks, you must have appropriate authorization. For more information about authorization, see Appendix D, Authorization Roles, on page 349. This chapter provides instructions for: v Creating profiles within a profile manager, and importing software packages into that profile, and for setting profile subscribers (the profile managers and endpoints) for the profile manager in which the profiles reside. See Creating a Software Distribution Profile on page 177. v Preparing the software package for distribution within the Tivoli environment. See Importing a Software Package into the Tivoli Environment on page 182. v Defining the properties of a software package using either the Software Package Editor or the command line. See Software Package Properties on page 186. v Calculating the size of newly created software packages and for recalculating them if they have changed since their creation. See Calculating the Size of a Software Package on page 188. v Converting the software package file format from software package to software package block, and vice versa. See Converting a Software Package on page 189. v Exporting a software package object into text file (.spd) format to produce the software package definition file. This definition file can be modified and imported into a software package or software package block. See Exporting a Software Package on page 190. v Using change management operations on software package objects. See Change Management Operations on page 191. Creating a Software Distribution Profile You create a Software Distribution profile within a profile manager that has been defined in a policy region. You then import software packages into Software Distribution profiles. The following scenario creates a Software Distribution profile from the Tivoli desktop and imports the Appsample software package. In this scenario, the distribution environment comprises the following: v An administrator: Root_msecchi-region v A policy region: msecchi-region v A managed node: msecchi Copyright IBM Corp. 2002,

198 Creating a Software Distribution Profile v A profile manager that contains several software distribution profiles: PM1 To determine the administrator s name that was defined for the root user ID when Tivoli Management Framework was installed on the server, double-click on the Administrators icon. Refer to Tivoli Management Framework: User s Guide for more information about administrators. 1. Double-click the msecchi-region icon to display the contents of the policy region. 2. In the Policy Region: msecchi-region dialog, select Create -> ProfileManager to create a profile manager in which the Appsample software package profile 178 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

199 Creating a Software Distribution Profile will reside. The Create Profile Manager dialog is displayed. 3. In the Name/Icon Label text box, type PM2. 4. Select the Dataless Endpoint Mode check box to enable the profile manager to distribute software package profiles to endpoints. Note: If you do not select the Dataless Endpoint Mode check box, the system is in database mode. This enables distribution of software package profiles to any profile manager that has endpoints as subscribers. For more information about dataless and database modes, refer to the Tivoli Management Framework: Planning for Deployment Guide. 5. Click Create & Close to return to the Policy Region: msecchi-region dialog. This now shows the PM2 profile manager. 6. To create a profile in the PM2 profile manager, double-click the PM2 icon to open the Profile Manager dialog. 7. Select Create -> Profile to display the Create Profile dialog. In this dialog you create a software package profile for the Appsample software package. 8. In the Name/Icon Label text box, type the Appsample^1.0 profile name. Chapter 9. Preparing a Software Package for Distribution 179

200 Creating a Software Distribution Profile Note: The string that represents the software package name and version must be formed so that the name is separated from the version by one of the following characters: v Caret (^) v Dot (.) Refer to the Reference Manual for Software Distribution for more information about software package name and version syntax. 9. Select SoftwarePackage resource type from the Type scrolling list. Note: If the resource type is not available in the scrolling list, you must add it as a managed resource of your policy region by moving it from the Available Resources to the Current Resources in the policy region. Each policy region maintains a list of managed resource types that are valid or defined for that specific policy region. 10. Click Create & Close to create the new profile and return to the Profile Manager dialog. An icon representing the newly created software package profile, Appsample^1.0, is displayed in the PM2 profile manager. The format of the software package profile at this point is empty. 180 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

201 Creating a Software Distribution Profile Setting the Profile Subscribers Before you can perform an operation on the profile, you must set the subscribers for the profile manager in which the profile resides. Subscribers can include other profile managers, endpoints, or resource groups. Resource groups can contain users or pervasive devices. Profiles distributed to users are distributed to the endpoint associated with the user. When performing an install change management operation you can select subscribers from those already available in that particular profile manager. However, when you select Profile Manager -> Distribute from the Profile Manager dialog menu, you distribute to all subscribers identified in that profile manager, and you cannot selectively choose them for each type of package in the profile manager. In the following scenario you add two endpoints as the subscribers to the PM2 profile manager. 1. From the Profile Manager dialog, select the Appsample^1.0 profile. 2. Select Profile Manager -> Subscribers to display the Subscribers dialog: 3. To move a subscriber to the Current Subscribers list, select one or more subscribers from the Available to become Subscribers list, then click the left arrow button. By default, all subscribers in the profile manager are displayed in the Available to become Subscribers list. To remove a subscriber, select one or more subscribers from the Current Subscribers list and click the right arrow button to move them to the Available to become Subscribers list. 4. Move the PM1 (Profile Manager) subscriber to the Current Subscribers list, then click Set Subscriptions & Close. The PM1 subscriber is added to the PM2 Profile Manager dialog. Chapter 9. Preparing a Software Package for Distribution 181

202 Creating a Software Distribution Profile Importing a Software Package into the Tivoli Environment Before you can use a software package profile to distribute a software package to a target system, you must import the software package into the Tivoli environment where it is cataloged as a software package object in the Tivoli object database. The software package profile is only a definition of the information that each profile item includes. The profile items must be populated with the database objects to be distributed. You can import an existing software package located on either an endpoint or managed node into the software package profile, or you can create a new software package within the software package profile. Creating a New Software Package and Importing it into a Software Package Profile To create a new software package and import it into a software package profile, ensure that the Software Distribution Software Package Editor component is installed and perform the following steps: 1. Create a software package profile as defined in Creating a Software Distribution Profile on page IBM Tivoli Configuration Manager: User s Guide for Software Distribution

203 Importing a Software Package into the Tivoli Environment 2. Right-click the software package profile icon from the Profile Manager dialog, then select Properties from the pop-up menu. The Software Package Properties dialog is displayed. 3. Click Launch Software Package Editor to display the Create Software Package dialog. Type the source host name. 4. Click Set & Close to close the dialog and launch the Software Package Editor. The Software Package Editor main window is displayed. 5. Create the software package using the Software Package Editor as explained in Chapter 3, Creating Packages Using the Software Package Editor, on page Save the software package and return to the software package profile in the Profile Manager dialog. Check that the software package has been imported into the software package profile. Importing an Existing Software Package into a Software Package Profile Existing software packages can be imported in a built format (.spb) or in a not-built format (.sp). Before it is built, a software package contains only a description of the objects contained in the package, that is, a sequential list of actions to be executed on the target system and not the actual resources themselves, such as files and programs. The resources reside on the source host. A software package in the built format already contains all the objects and resources required by the actions in a zipped file format. In this scenario, the Appsample^1.0 profile is populated with the Appsample software package, which is in the not-built format. Chapter 9. Preparing a Software Package for Distribution 183

204 Importing a Software Package into the Tivoli Environment 1. Right-click the Appsample^1.0 profile from the Profile Manager dialog, then select Import from the pop-up menu. 184 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

205 Importing a Software Package into the Tivoli Environment The Import dialog imports a software package file into a software package profile. 2. In the Location of Input File group box, specify the machine type from the drop-down list. The options are Managed Node and Endpoint. If you select Endpoint, type the name of the endpoint in the Endpoint Name text box and then click the ellipsis (...) button. 3. Select Managed Node from the Machine Type drop-down list, then type msecchi in the Managed Node Name text box. 4. Click the ellipsis (...) button to display the Select Input File dialog. The dialog displays the file system hierarchy for the msecchi managed node. The file you select in this browser dialog is the file that is imported into the Appsample^1.0 software package profile. 5. Trace the path to the Appsample.sp file in the Directories and Files boxes. Click Set File & Close to return to the Import dialog. 6. You can import the software package either in the built format or in the not-built format. To import the Appsample software package in the not-built format, perform the following steps: a. Deselect the Build check box in the Location of Source Host group box. b. In the Source Host Name text box, type the name of the source host. The package is built at distribution time and the resources referenced in the software package are collected from the specified source host. Ensure that, when a package is being built at distribution time or imported to the built format, the Software Distribution component is installed on the source host. If not an error occurs. OR To import the Appsample software package in the built format, perform the following steps: a. Select the Build check box. Chapter 9. Preparing a Software Package for Distribution 185

206 Importing a Software Package into the Tivoli Environment b. Type the SPB path in the SPB Path text box. If the input file is a software package or software package definition file, it is imported into a software package block. If the input file is a software package block, it is copied from the managed node or endpoint specified in the Location of Input File group box to the specified software package block path on the source host. Note: Always select the Build check box when importing a software package block. Selecting the Build check box enables the Overwrite check box. Select Overwrite to overwrite the software package block should it already exist on the source host. In this scenario, deselect the Build check box. 7. In the Source Host Name text box, type the source host from which the files in the software package block are to be obtained, if it is not already defined in the input file. Note: The source host can be any of the available managed nodes on which the Software Distribution component is installed. 8. Click Import & Close. The software package profile icon in the Profile Manager dialog is now in the not-built format. Deleting a Software Package Profile When you delete a software package profile, it is removed from the Tivoli database and its icon is removed from the profile manager. Deleting a profile does not delete the source files or directories or the distributed files or directories on the subscribers. Note: If you delete a software package for which you have scheduled a distribution, you must delete the job from the scheduler. Deleting a profile does not automatically delete the job. See Scheduling a Distribution on page 217 for more information about distributing a software packaged at a schedule time. Refer to the Tivoli Management Framework: Planning for Deployment Guide for more information about using the Tivoli Management Framework Scheduler. Software Package Properties To remove previously distributed software packages from target systems, you perform a Remove change management operation. See Removing a Software Package on page 193 for more information about removing a software package. Software package properties can be defined in the following ways: v Using the Software Package Editor. v Using the wsetspop, wsetspgs, and wsetspat commands from the command line (excluding the Package Type and Versioning Type properties). v Exporting a software package to the software package definition file format, modifying the properties, and re-importing the file back to the software package format. To view the properties of the Appsample software package profile from the Tivoli desktop, perform the following steps: 186 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

207 Software Package Properties 1. Right-click the Appsample^1.0 software package profile icon in the Profile Manager dialog, then select Properties. The Software Package Properties dialog is displayed from which you can view the properties defined for the software package. 2. Click Launch Software Package Editor to display the Software Package Editor. From the editor, you can do the following: v View the contents of a software package v Create a software package from scratch v Edit software packages that are in the built format Note: To modify the contents of a software package, each endpoint For information about editing software packages that are in the built format and the options that are available when the Software Package Editor is launched from the Software Package Properties dialog, see Launching the Software Package Editor on Managed Nodes on page To view information on software packages nested in the Appsample^1.0 software package, click Nested Software Packages. See Distributing Nested Software Packages on page 212 for more information about distributing software packages that contain nested packages. Chapter 9. Preparing a Software Package for Distribution 187

208 Software Package Properties 4. Click Advanced to display the Advanced Properties dialog. The properties displayed in the Software Package Properties and Advanced Properties dialogs are explained in Setting Properties on the Package on page 61. Calculating the Size of a Software Package Calculate the size of a software package at the source host to determine the total size of the files it contains. Use this option to recalculate the size if you have made changes to the package since its creation. To calculate the size of the Appsample software package in the built format, perform the following steps: 1. Right-click the software package profile from the Profile Manager dialog, and select Calculate Size from the pop-up menu. The Calculate Software Package Size dialog is displayed. 188 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

209 Calculating the Size of a Software Package The Calculate Software Package Size dialog displays the name of the software package and its profile manager. If the size of the software package had already been calculated, it displays the last recorded calculation. 2. Click Calculate Size to recalculate the size of the currently selected software package (in bytes). Note that if a package contains only actions, that is, the package is in the not-built format, its size is calculated as zero. When calculating the size of nested software packages, the size is calculated as the sum of the size of the primary package plus the size of the nested packages. The size can be calculated successfully only if the primary package and nested packages have been imported into the Tivoli environment and cataloged as software package objects in the Tivoli object database. Converting a Software Package The convert operation is used to transform the software package file format from software package to software package block, or from software package block to software package. A software package contains only a description of the objects contained in the package. That is, it contains a sequential list of actions to be executed on the target machine and not the actual objects or resources themselves, such as files or programs, which are located on the source host. A software package block is in a zipped file format and bundles the actions with the resources. You can use this operation to convert only software package objects that already exist in the object database. In other words, the software package objects must have been imported into the Tivoli environment. Note: The size of a software package block cannot exceed 2 GB. You can exceed this limit by nesting software packages. Each segment or package cannot exceed 2 GB. Not-built to Built To convert the Appsample software package (not-built) to a software package block (built), perform the following steps: 1. Right-click the Appsample^1.0 software package in the Profile Manager dialog, then select Convert from the pop-up menu. The Convert Software Package dialog is displayed. 2. In the SPB Path text box, type the path and file name for the software package block on the source host. The source host is the managed node defined when the package is imported. All the resources must be located on the selected source host, otherwise, the operation fails. Chapter 9. Preparing a Software Package for Distribution 189

210 Converting a Software Package 3. Select the Overwrite check box to overwrite the software package block if it already exists on the source host. This option is valid only if the target format is a software package block. 4. Click Convert & Close to convert the software package into a software package block on the source host. Built to Not-built To unbuild or convert the Appsample software package block (built) to a software package (non-built) and save it to a specified directory, perform the following steps: 1. Right-click the software package block and select Convert. The software package block is stored on the source host defined at the time of import and the Convert Software Package dialog is displayed. Exporting a Software Package 2. Select the Unbuild check box if you want to save the contents of the software package to a staging directory. 3. If you selected the Unbuild check box, click Unbuild Directory and navigate to the directory where you want to store the contents of the software package when it is unbuilt. 4. Click Convert & Close. The software package is converted to a non-built format. If you selected the Unbuild check box, the contents are saved to the Unbuild Directory and the source paths in the software package are updated so that they point to the Unbuild Directory. Otherwise, the software package block is converted to a software package and the source paths remain unchanged. Note: If relative source paths are specified in the software package, the unbuild operation might fail or behave unpredictably. The Export dialog enables you to export a software package object into text file format. This text file is the software package definition file. It consists of a sequence of stanzas, each of which describes an action to be executed. Using a text editor, you can view the.spd file, modify it, and use the Import function to import the revised.spd file into a software package or software package block. Refer to the Reference Manual for Software Distribution for more information about the.spd file format. To export a software package object to the.spd format and then reimport it, perform the following steps. 190 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

211 Exporting a Software Package 1. Right-click the Appsample^1.0 software package profile, then select Export from the pop-up menu. The Export dialog is displayed. 2. Specify the name of the managed node to which the file should be exported in the Managed Node Name text box. 3. In the Path text box, specify the full pathname of the file on the managed node to which the software package is to be exported. To export to a remote managed node, you must specify its fully qualified path. 4. Select the Overwrite check box to overwrite an existing.spd file. 5. Click Export & Close to export the software package to the.spd file format. 6. Open and edit the software package definition file using a text editor. You can view software package definition files in the IBM Tivoli Configuration Manager: Reference Manual for Software Distribution. 7. Follow the instructions in Importing a Software Package into the Tivoli Environment on page 182 to import the.spd file to either a built or not-built software package. Change Management Operations This section describes the following change management operations that you can perform on software package objects. These options fully automate the distributing and installing of software, and are as follows: v Install v Remove v Undo v Accept v Commit v Verify v Load v Unload For more information about the operations and dialogs described in this section, refer to the corresponding Software Distribution server command, which can be run from the command line of the server, in the Reference Manual for Software Distribution. Software Package States The software package state that results after an operation may vary based on the history of the package, that is, depending on what operations, such as install, have been previously performed on it. The state is represented by a five-character string. Chapter 9. Preparing a Software Package for Distribution 191

212 Change Management Operations Each character of the string represents a category of information about the package, which can be assigned one of a number of values. For example, a software package with the IC state is a package that has been installed and committed. Refer to the Reference Manual for Software Distribution for a table summarizing possible software package states. Depending on the state of a software package due to a previous operation, not all operations can be performed on it. The operational state of a software package can be determined in the following ways: v Run the CM_STATUS_QUERY. v Open the Software Distribution log file located in the path specified in the software package properties log path. v If you have the disconnected command line installed on the endpoint, run the wdlssp command. The state of a software package is determined by the following: v The nature of the last operation performed (install or remove). v The state of the last operation performed (prepared or committed). v The state of the backup package (undoable state). v Whether a reboot is required to complete the operation. v An additional flag that indicates an error condition or that the status is in the process of being changed. Executing Change Management Operations Each of the change management operations is performed in three steps: Check Test that the operation can be performed to reduce the risk of failure during the execution phase. Execute Perform the operation only if the check is successful. Cleanup Resources acquired during the execute phase are deleted. Change management operations can be performed from the Profile Manager dialog in either of these two ways: v Drag-and-drop the Appsample^1.0 software package icon onto the required subscriber icon, to use the default change management operation and associated attributes you set up in the software package (see Setting Advanced Server Options on page 66). v Right-click the Appsample^1.0 software package icon to display a pop-up menu from which you can select the required change management operation and customize the associated attributes, as described below. 192 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

213 Change Management Operations From this menu, you can view software package properties, calculate the size of the software package, convert the software package into a software package block, export software packages, and perform change management operations on software packages. The change management operations available depend on the format of the software package. Installing a Software Package The install operation performs the actions contained in the software package. The actions executed by the install operation depend on the nature of the action. For example, while the install operation of the add file action copies a file to the target file system, the install operation of the remove registry key action removes a registry key from the target system Windows registry. To perform an install operation from the command line, see the winstsp command in the Reference Manual for Software Distribution. Removing a Software Package The remove operation uninstalls the software package; that is, it performs the opposite action of the install operation. The remove operation does not return the system to its state prior to the last executed operation (see Undoing a Software Package on page 194). The actions performed by the remove operation depend on the nature of the action contained in the software package. Add object-related actions are reversed. For example, while the remove operation on the add file Chapter 9. Preparing a Software Package for Distribution 193

214 Change Management Operations action removes a file from the file system, the remove operation of the add registry key action removes a registry key from the Windows registry. However, the remove operation on a remove object-action does nothing. The behavior of remove operations on program and system actions is defined in the program and system action properties. To perform an remove operation from the command line, see the wremovsp command in the Reference Manual for Software Distribution. Undoing a Software Package The undo operation returns the system to its state prior to the execution of the previous operation. This operation is used for objects for which the previous operation was submitted in undoable or in transactional mode to roll back the system to its original state. Files added by the installation that did not exist prior to the distribution are removed. If the files existed prior to the distribution and were removed, they are added back. If they existed prior to the distribution and were replaced, the backup copy is restored. Additions, deletions, or changes made to configuration or system information (registry changes,.ini file entries, folders, shortcuts, and so on) are reset to their original state. However, this operation is valid only for the last attempted installation, not for prior installations. In the event of fatal errors during the installation process, this operation is triggered automatically. To perform an install operation from the command line, see the wundosp command in the Reference Manual for Software Distribution. Accepting a Software Package The accept operation discards the resources needed to undo the previous operation (backup copy). The accept operation, which frees up system resources, should be performed only when you are certain that you will not need to undo the previous operation. After running an accept operation, the previous operation is no longer undoable. To perform an accept operation from the command line, see the waccptsp command in the Reference Manual for Software Distribution. Committing a Software Package An install or remove operation submitted in transactional mode is performed in two phases: the preparation phase and the commit phase. During the preparation phase, each action in the package prepares the conditions for the successful execution of the requested operation, which reduces the risk of failure during the commit phase. The commit operation causes all the updates established in the preparation phase to take effect. To perform a commit operation from the command line, see the wcmmtsp command in the Reference Manual for Software Distribution. Verifying a Software Package The verify operation verifies the consistency of an installed software package and the objects on the target system. A verify operation checks that the changes that occurred during the last operation are intact. If the consistency check fails, the software package is placed in an error state. The actions performed by the verify operation depend on the nature of the action. For example, while the verify operation of the add file action verifies that the copied file still exists, the verify operation of the add registry key action verifies that the registry key is still in the Windows registry. 194 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

215 Change Management Operations To perform a verify operation from the command line, see the wversp command in the Reference Manual for Software Distribution. Loading and Unloading Software Packages Entire distributions can be stored in a directory on a repeater depot and a distribution that has been interrupted because of unavailable nodes or network failures can be resumed from the repeater depot rather than from the initial distribution source. The software package can subsequently be unloaded from the depot. These operations are valid for only built software packages. To perform a load or unload operation from the command line, see the wldsp and wuldsp commands in the Reference Manual for Software Distribution. See Scenario 3: Distributing from a Source Host through Repeater Depots on page 257 for more information about repeater depots and operations you can perform. Customizing the GUI Settings You can customize some of the default distribution settings for a specified policy region, or for all policy regions, to conform with your own company distribution policies. The wswdmgr command enables you to customize the default values for the following options: Table 12. Customizing default values for distribution options Dialogs Options Refer to... Change Management Operations (install, remove, accept, commit, undo, verify, load, and unload) Distribution Settings User Notification Settings Mobile Settings label, priority, operation, disposable, from depot, from fileserver, from cd, notification interval, send timeout, execute timeout, deadline, roaming EP, wake on lan EP, enable multicast, retry unicast, enable user notification, user notification note, allow defer, allow reject, default action, default timeout enable disconnected, distribution note, optional, mandatory, hidden, mandatory date, escalate message, escalate date Installing the Appsample^1.0 Software Package on page 196 Defining Distribution Settings on page 205 Notifying Users of a Distribution on page 206 Distributing Software Packages to Mobile Targets on page 208 These options are fully explained in the following sections and correspond to the l option defined in the Reference Manual for Software Distribution. Refer to the Reference Manual for Software Distribution for more information about the command syntax and arguments of the wswdmgr command. Chapter 9. Preparing a Software Package for Distribution 195

216 Change Management Operations Installing the Appsample^1.0 Software Package 1. Select Install from the Appsample^1.0 software package pop-up menu to display the Install Software Package dialog. 2. In the Label text box, specify the name of the software package, for example, Appsample^1.0. The default is the software package name, but you can specify any text in this text box. 3. Specify the order in which distributions are handled by repeaters in the Priority Level group box. The default value is Medium. The priority level selected in this group box is the priority also used by the notification manager which informs listeners of distribution results. See point 252 in How Software Distribution Works on page 250 for more information about the notification manager. 196 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

217 Change Management Operations 4. In the Changes group box, click one of the following: All Source Repair Installs all the files in the software package. This option corresponds to the m a attribute used in the command line version of the operation. This option is visible only for not-built packages. Installs only those source host files that have been modified since the last successful distribution to the target system. Installs the following: v The source objects that since the time of the last successful installation have been corrupted, modified, or are not present on the target. This makes the target objects consistent with the source objects. v The objects and actions on the target that have been changed or corrupted since the time of the last successful installation. The software package is re-built containing only the objects needed to perform the repair and, therefore, is smaller than the original software package, and is installed on the target. The repair option applies only to software packages in the following operational states: v Target machines on which the software package has already been installed and committed (IC) v Target machines on which the software package has been installed and committed, but the software package is in error (IC---E) Note: The repair option also supports software package blocks, but not when the From Depot check box is selected. See step 8 on page 199 for information about the From Depot option. Refer to the Reference Manual for Software Distribution for more information about software package operational states. This option corresponds to the m r attribute used in the command line version of the operation. 5. To upgrade an installed package using byte-level differencing, select the Delta Install check box and type the name and version of the built package to be upgraded in the Base Package text box. Software Distribution uses the files contained in the delta package to reconstruct each version file starting from the base file already installed on the target and applying to it the corresponding delta file contained in the delta package. If any of the installed files to be reconstructed are not found on the target, or have been modified, or are read-only, or are locked, the delta installation fails. To apply the delta installation the base and the version packages must have the same nested structure. Byte-level differencing uses dependency checking to verify if the base package has been installed on the target. The base package must be in the IC or ICU state. If you clear the Dependency check box, no checks are done on the base package. For a detailed explanation of how byte-level differencing works, refer to the Reference Manual for Software Distribution. The delta install option corresponds to the d option used in the command line version of the operation. If you perform a delta installation, you cannot install the software package in source or repair mode. 6. The Checks group box allows you to select a type of verification to be performed. The configuration repository is accessed for information about the Chapter 9. Preparing a Software Package for Distribution 197

218 Change Management Operations status of change management operations on all targets, as well as the availability of the targets. The change management operation is performed depending on the information returned by the check option selected. No Checks The selected change management operation will be performed on all the selected targets provided that no errors of any kind are found by the verification process; if any error is found, the verification process stops before starting the operation. This is the default, and is the equivalent of not specifying any check attributes in the command line version of the operation. Checks Force Verifies whether the operation can be performed without submitting it. The process generates a list of targets on which the operation fails. This option corresponds to the i option used in the command line version of the operation. This option is available only if the target is already registered in the Inventory database as a consequence of a scan or a change management operation performed on the target. Forces the operation regardless of the state of the software package on the target system. If the package is versionable, the version checks are made on the target even when this option is selected. If the version checks fail, the operation fails. Refer to the Reference Manual for Software Distribution for more information about software package version checking. This option corresponds to the f option used in the command line version of the operation. Ignore Verifies whether the operation can be performed and proceeds with the operation only on target systems that pass the verification. For example, if you are performing an install operation and the software package is already installed on a target system, the operation does not proceed on that target system. If you do not select this option, the operation does not proceed on any of the specified targets unless all targets pass the verification. This option corresponds to the I option used in the command line version of the operation. This option is available only if the target is already registered in the Inventory database as a consequence of a scan or a change management operation performed on the target. Preview Returns to the log file on the server a list of actions that would be carried out if you performed the operation. The operation is not actually carried out. This attribute can be used in conjunction with the repair or source options. When you specify the source and preview options together, do not specify subscribers for the operation, as this would result in an error message. A check is performed on the target and the list of files to be repaired or a list of source files that have been modified is returned to the log file. This option corresponds to the i option used in the command line version of the operation. 7. Clear the Disposable check box to keep the data associated with a distribution (depot segment) at the repeater after all target systems have received the distribution. If the distribution needs to be repeated in the future, it can be initiated from the depot rather than from the source host. Select the Disposable check box to remove the data associated with a distribution from the repeater once the distribution has finished (either all endpoints have completed or the distribution has exceeded its life span). Repeater depots that have been configured to accept permanent distributions will remove the 198 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

219 Change Management Operations distribution if the Disposable option is selected. If a repeater depot is configured to accept temporary distributions, and disposable is not specified, the distribution is not removed. For more information about configuring repeater depots to accept permanent distributions, see Setting Repeater Parameters on page 242. This option, when selected, corresponds to l disposable=y used in the command line version of the operation. Note: If the object of the distribution is a software package in the not-built format and not a software package block, this option is disabled and the data is deleted after the software package is distributed and not stored on the depot. 8. Select the From Depot check box to specify that the software package to be installed resides on the repeater depot rather than on the source host. See Creating a Repeater Hierarchy on page 238 for more information about depots. This option does not apply to software packages in the not-built format. This option, when selected, corresponds to l from_depot=y used in the command line version of the operation. Notes: 1. If you select this check box, you cannot select either the From Fileserver or the From CD check box. 2. If you specify From Depot together with Roaming EP, the software package must be loaded on all depots to which the endpoint can roam to avoid an install failure. 9. Select the From Fileserver check box to specify that the images to be installed are to be retrieved from a file server rather than from the source host. File servers must be configured if this option is used. See Scenario 2: Distributing from a Source Host/Tivoli Management Region Server to a Repeater on page 255 that describes the required steps to perform a dataless distribution of a software package that retrieves the images referenced in the software package from a file server. Note: When you send a distribution with the From Fileserver option selected, consider increasing the distribution send_timeout value. After this timeout value is exceeded, you can no longer pause or cancel the distribution. This option applies to software package blocks (built format). This option, when selected, corresponds to l from_fileserver=y used in the command line version of the operation. 10. Select the From CD check box to specify that the images referenced in the software package are to be retrieved from the CD-ROM on the target system rather than from the source host. This option does not apply to software packages in the not-built format. This option, when selected, corresponds to l from_cd=y used in the command line version of the operation. See Scenario 4: Distributing from a Tivoli Management Region Server to a Mobile Endpoint Installing Images from a CD-ROM on page 259 for the required steps to perform a dataless distribution that accesses the installable images from the endpoint CD-ROM. 11. To move a subscriber to the Install Software Package On list, select one or more subscribers from the Available Subscribers list, then click the left arrow. By default, all subscribers in the profile manager are displayed in the Available Subscribers list. Chapter 9. Preparing a Software Package for Distribution 199

220 Change Management Operations To remove a subscriber, select one or more subscribers from the Install Software Package On list and click the right arrow to move them to the Available Subscribers list. If the Available Subscribers list contains a profile manager, a plus sign (+) appears in front of its name. You can double-click a profile manager name to expand it and display the Tivoli endpoints it contains and the other profile managers that subscribe to it. You can then select any of the subscribers and add them to the Install Software Package On list. If you select a profile manager name in the Available Subscribers list, you must deselect it before double-clicking it. The name of an expanded profile manager has a dash ( ) in front of it in the Available Subscribers list. To compress an expanded profile manager entry, double-click the profile manager name. Click Expand All or Compress All to expand or compress all profile managers in the Available Subscribers list. 12. If you have Tivoli Inventory installed, you can select subscribers by scanning the available Tivoli endpoints for certain criteria defined by a query in a query library. Click Query to display the Execute a Query dialog. In this dialog, you can use the Tivoli configuration repository to define a list of distribution targets for a profile manager that contains a software package. It lists the available query libraries that were created using the Tivoli Management Framework. Select a query library from the Query Libraries scrolling list, then click Execute to run the query on the Tivoli configuration repository and return the names of the endpoints that meet the criteria. This list automatically populates the Install Software Package On list. Refer to the Tivoli Management Framework: Planning for Deployment Guide for more information about creating and using queries. Click Close to return to the Install Software Package dialog. 13. Select the Dependency check box to apply any software and hardware dependencies defined for the software package. The Dependency check box, when selected, corresponds to the R y option used in the command line version of the operation. 14. Click Schedule to schedule distributions at a future time. See Scheduling a Distribution on page 217 for more information. You can also scheduler Software Distribution change management operations using the Activity Planner. See Activity Planner on page 317 for information about a scheduling facility that enables you to manage a group of operations as a single operation from a single machine in the network. 200 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

221 Change Management Operations 15. To replace all values in this dialog with the default values for this operation click Reset. 16. From the Advanced Options pull-down menu, select the options you require. Advanced Options enable you to set the following information for your distribution: operation modes, default variables, distribution settings, and mobile settings. See Advanced Options for detailed explanation. 17. When you have finished setting options from the Advanced Options menu, install the software package to the selected subscribers by clicking Install & Close. The dialog is not dismissed until the operation has been submitted. You can view the status of the distribution using the Distribution Status Console or from the command line using the wmdist command. Refer to the Tivoli Management Framework User s Guide for more detailed information. Advanced Options The dialog for each of the change management operations contains an Advanced Options pull-down menu. The options in this menu depend on the selected operation. You can set the following options for the install operation: v Operation Modes: See Change Management Operation Modes on page 202 Provides options such as the capability of returning the system to its initial state if the operation fails, backing up the software package, automatically performing a reboot, options in case of locked resources or insufficient disk space. v Default Variables: See Overwriting Default Variables on page 204 Enable you to temporarily overwrite the value of default variables already defined in the software package. v Distribution Settings: See Defining Distribution Settings on page 205 Enable you to exploit Wake on LAN technology, optimize network bandwidth by multicasting distributions, rerouting queued distributions from one gateway to another, depending on which gateway the mobile endpoint last connected, set distribution deadline times. v User Notification Settings: See Notifying Users of a Distribution on page 206 Enable you to send users a note informing them of a distribution, determine whether users can defer accepting a software package, and determine whether users can decide to reject a software package. v Mobile Settings: See Distributing Software Packages to Mobile Targets on page 208 Allow mobile users to defer accepting a software package distribution, reject a distribution, alert mobile users with a message about a pending software distribution. Chapter 9. Preparing a Software Package for Distribution 201

222 Change Management Operations Change Management Operation Modes Selecting Operation Modes from the Advanced Options pull-down menu enables you to specify additional options to be used when executing an install operation. The options available in this dialog depend on the selections you make. For example, selecting Yes in the Transactional Options group box enables the Auto-Commit check box in the Automatic Operations group box, which was previously grayed out. Selecting the Auto-Commit check box enables the Reboot Options that were previously grayed out. Reboot options are not valid on UNIX systems. The install operation supports the following execution options: v Transactional Options No Yes Not-transactional: This option does not provide the capability of returning the system to its initial state if the operation fails unless you have also selected the Yes option in the Undoable Options group box. If disk space is consumed before the distribution has completed, the distribution fails and some files are left on the target system. Use this option only if you are sure the operation will complete successfully. This option corresponds to t n of the command line version of this operation. Transactional: The execution of the operation is split into two phases: the preparation phase and the commit phase. During the preparation phase, each action in the package prepares the conditions for the successful execution of the requested operation, which reduces the risk of failure during the commit phase. If the preparation phase completes normally, in the case of an install, the files are installed in the staging area. At this point the commit phase begins, where the updates take effect, that is, files are moved from the staging area to the production area. If the preparation phase fails, the system is returned to its original state. For example, this option is useful if there are locked files or if there is not enough disk space. It avoids interrupting a distribution in mid-stream and leaving partial distributions (files) on the target system. This option corresponds to t y of the command line version of this operation. 202 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

223 Change Management Operations v v Only if necessary Preferably not-transactional: Requests the system to not execute the operation in transactional mode if it detects that it cannot proceed because of temporary errors that could disappear during the commit phase. For example, it is useful to perform an operation with this two-phase (preparation and commit phase) approach when resources are locked or not available in the preparation phase but then become available in the commit phase. This option corresponds to t o of the command line version of this operation. Note: The Only if necessary option is not supported on OS/400 endpoints. Undoable Options No Yes Not-undoable: A backup package is not created and therefore the undo of an operation is not possible. This option corresponds to u n of the command line version of this operation. Undoable: Requests the ability to return the system to its previous state because a backup package is created. This option corresponds to u y of the command line version of this operation. Note: This option is recommended for software packages that install system files, because the operation can then be rolled back (undone) without damaging the system. If possible Preferably-undoable: Attempts to create a backup package, but continues with the normal installation if the process to acquire backup space fails. This option corresponds to u o of the command line version of this operation. Transactional Undoable-in-transactional: transactional, which requests that an action be undoable in transactional mode, that is, the operation is undoable, but the backup package is built during the commit phase. This mode, which is a combination of transactional and undoable mode, requires that space for both a staging area and a backup area be reserved. The operation is performed in two phases: the preparation phase and the commit phase, as in transactional mode. Performing a commit operation creates a backup package, to be used in the undo phase, and causes all the updates performed in the preparation phase to take effect. This option corresponds to u u of the command line version of this operation. Reboot Options No Yes Not-in-a-reboot: Auto-commit without a reboot. Executes the commit operation without a machine reboot. This option increases the possibility of errors due to possible locked resources. This option corresponds to c n of the command line version of this operation. In-a-reboot: Auto-commit with a user reboot. Executes the commit phase the next time the machine is rebooted by the user. This option corresponds to c y of the command line version of this operation. If necessary Executes the commit phase with a machine reboot only if necessary. For example, if locked files are found, an auto reboot will be performed. This option corresponds to c o of the command line version of this operation. Chapter 9. Preparing a Software Package for Distribution 203

224 Change Management Operations v Automatic Auto-reboot: Executes the commit phase with a reboot when only the operating system is running and all other applications are closed. This option prepares the system to complete the operation when the Software Distribution agent automatically runs the reboot operation. This option corresponds to c r of the command line version of this operation. Automatic Operations Auto-Commit Requests the system to automatically commit a pending operation. This option corresponds to c of the command line version of this operation. Auto-Accept Requests the system to automatically accept an undoable operation. This option corresponds to a of the command line version of this operation. Click Set to save the options you selected, or click Set & Close to save the options and return to the Install Software Package dialog. Overwriting Default Variables Using this dialog, you can temporarily overwrite the value of default variables formerly defined either in the Software Package Editor or in a Software Package Definition (SPD) file for a specific distribution. See Chapter 3, Creating Packages Using the Software Package Editor, on page 29 for more information about setting variables from the Software Package Editor. When you subsequently remove a software package, you can define or override only those variables that were not resolved when the package was installed. Refer to the Reference Manual for Software Distribution for a list and description of Software Distribution built-in variables. You open this dialog by selecting Default Variables from the Advanced Options pull-down menu in the Install Software Package dialog. 204 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

225 Change Management Operations 1. To change the value of a variable, type the name of the default variable for which you want to change the value in the Variable Name text box. In the Variable Value text box, type the new value to be assigned to the variable. 2. Using the Default Variables List group box, you can also add or remove variables to be used during the execution of an operation. 3. Click Set to save the variables you specified, or click Set & Close to save the variables and return to the Install Software Package dialog. Defining Distribution Settings Use this dialog to define distribution settings including server-level and client-level timeout parameters that enable you to specify a time interval after which either the server or client interrupts a distribution. Setting timeout parameters can avoid suspended distributions. You open this dialog by selecting Distribution Settings from the Advanced Options pull-down menu in the Install Software Package dialog. 1. Select the Wake on Lan EP check box if the distribution is to automatically trigger a restart on targets that are not available at distribution time. The target machine must have the Wake on LAN network adapter to exploit this technology. 2. Select the Roaming EP check box if the distribution is to be transferred from the gateway, where it is queued, to the gateway to which it last connected, where an endpoint, which is a target to the distribution, has connected. If you clear this check box, the distribution remains queued at the original gateway until the mobile endpoint connects to it again or the distribution times out. Chapter 9. Preparing a Software Package for Distribution 205

226 Change Management Operations Note: If you specify From Depot together with Roaming EP, the software package must be loaded on all depots to which the endpoint can roam to avoid an install failure. 3. Select the Enable Multicast check box to enable data broadcasting to multiple repeaters. Multicast sends only one distribution from the source to a group of targets simultaneously. Use this option where there is limited network bandwidth. Optionally select the Retry Unicast check box to retransmit the distribution independently to each endpoint that failed to receive the original multicast distribution. Refer to the Tivoli Management Framework: Planning for Deployment Guide for information about preloading a depot using multicast and sending a distribution to endpoints using multicast. 4. Specify the Deadline by typing the date and time on which the distribution expires. The distribution fails for any targets that have not received the distribution before the specified date and time. 5. Specify a Notification Interval. The default is 1800 seconds (30 minutes). This controls the interval with which each repeater bundles up the completed results and returns them to the application and distribution manager. The value specified here overrides the value previously set using the wmdist -s command. See Setting Repeater Parameters on page 242 for more information. 6. Specify a Send Timeout period. The default is 300 seconds (five minutes). Send Timeout refers to the length of time a repeater will wait for a target to receive a block of data. This timeout is used to detect network or endpoint failures. The value specified here overrides the value previously set using the wmdist -s command. 7. Specify the Execution Timeout. The default is 300 seconds (five minutes). The Execute Timeout refers to the length of time a repeater will wait for Software Distribution to return the result of a distribution after all the data has been sent. This timeout is used to detect network, endpoint, or script failures, for example, a script that is running in an infinite loop. The value specified here overrides the value previously set using the wmdist -s command. 8. Click Set to save the settings you specified, or click Set & Close to save the settings and return to the Install Software Package dialog. Notifying Users of a Distribution Use this dialog to inform users of software package distributions initiating on their systems. The Software Distribution Notification dialog is displayed on the user s system informing the user of a distribution and enables the user to make decisions about the distribution. The Endpoint Notification dialog is displayed only on Windows platform endpoints. Using the user notification settings you can do the following: v Send users a note informing them of the distribution. v Determine whether users can defer accepting a software package. v Determine whether users can decide to reject a software package. You open this dialog by selecting User Notification Settings from the Advanced Options pull-down menu in the Install Software Package dialog. These settings are 206 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

227 Change Management Operations available for all change management operations, except load and unload. 1. Select the Enable User Notification check box to notify the user of a distribution starting on the user s machine. 2. In the User Notification Note text box, type text to be sent with the distribution, or click Add note from SPO to import the text of the description defined in the software package. See Description on page 72. Alternatively, click Add note from file to navigate to a file where a pre-defined message is stored. This message is displayed on the Software Distribution Endpoint Notification dialog. 3. Select the Allowed Actions. Determine the actions the user is permitted to perform on the endpoint. Allow Defer Select this check box to allow the user to defer the distribution. A user can defer the software distribution and, at the end of the defer timeout period, subsequently reject it or defer it again. Allow Reject Select this check box to allow the user to reject the distribution. 4. Select the Default Action. In the case that the user is not logged on the machine or is not physically present, set the default action to be performed on the endpoint. Accept Select this radio button to set the default action in the notification dialog to accept. Reject Select this radio button to set the default action in the notification dialog to reject. 5. In the Default Timeout text box, type the interval of time the notification dialog is displayed. The default is 60 seconds. When the timeout period Chapter 9. Preparing a Software Package for Distribution 207

228 Change Management Operations elapses, the default action is launched if the user is logged on. If the user is not logged on, the default action is launched immediately without a timeout period. 6. Click Set to save the settings you specified, or click Set & Close to save the settings and return to the Install Software Package dialog. When the software package is submitted for distribution, the Software Distribution Endpoint Notification dialog pops up on the screen of the endpoint user. The settings specified in the User Notification Settings dialog determines what options (if any), the user has in this dialog. For example, if the Allow Defer and Allow Reject check boxes on the User Notification Settings dialog were not selected, the user would not have the option of rejecting or deferring and would be forced to accept the distribution. The user can click Show Details to display the Distribution Details dialog to view information about the software package name, the change management operation to be performed, the operation mode and the distribution ID. Note: This dialog does not display on mobile endpoints. Distributing Software Packages to Mobile Targets Using this dialog, you can define rules for distributing software packages to mobile targets. Using the mobile settings you can do the following: v Determine whether mobile users can defer accepting a software package and for how long. v Determine whether to reject a software package. v Specify a date by which the distribution must complete or fail. v Define a sequence of messages to be sent on specified dates to alert the mobile users of a pending software package distribution. 208 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

229 Change Management Operations You open this dialog by selecting Mobile Settings from the Advanced Options pull-down menu in the Install Software Package dialog. 1. Select the Enable Disconnected Operation check box to allow installation of the package in disconnected mode. Selecting this option enables the mobile endpoint to download the software packages to the local depot and execute the software distribution operation later. If you do not select this option, you must install software packages when you download them. 2. In the Distribution Note text box, type text to be sent with the distribution, or use one of the following options to import predefined text: v Click Add note from file to navigate to a file where a pre-defined message is stored. v Click Add note from SPO to use the software package description in the distribution note. 3. Select a Distribution Mode. Optional If you select this mode, the mobile user has the option to defer or reject the installation indefinitely. Chapter 9. Preparing a Software Package for Distribution 209

230 Change Management Operations Mandatory If you select this mode, you must specify a mandatory date by which the installation must be performed. The mobile user can defer installation up to this date. Hidden If you select this mode, the mobile user is not given the option of deferring the installation. The installation is performed as soon as the user connects to a gateway. 4. If you selected Mandatory mode, you must specify a date and time by which the installation must be performed. You can also choose to clear the Force check box. The force option has the following effect: Selected The mandatory installation is automatically started as soon as the mobile user connects and if the mandatory date is reached. This is the default. Cleared The mobile user has the choice of not starting the mandatory installation. However, the user will not be able to perform any other operations until the mandatory installation has been performed. 5. Unless you selected the Hidden distribution mode, you can specify an escalate date and time, when a message is to be sent to mobile users alerting them that there is a pending installation to be performed. If you specify a date, you must also provide a corresponding message. You can type the message in the text box, or click Add from file to navigate to a file where a predefined message is stored. You can define up to ten escalate dates and messages. 6. Click Set to save the settings you specified, or click Set & Close to save the settings and return to the Install Software Package dialog. Refer to the Tivoli Management Framework: User s Guide for information about mobile computing. Installing the Device Object Software Package To install (the only action supported for devices) the device object software package, you follow the instructions for installing a software package (as described in Installing a Software Package on page 193). However, not all the options apply to device object software packages. 210 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

231 Change Management Operations The Install Software Package dialog shows the options that do not apply to device objects grayed out. In addition, you can complete the Default Variables and the Distribution Settings dialogs that you access from the Advanced Options pull-down menu in the Install Software Package dialog. The other options on this menu do not apply to device objects. Chapter 9. Preparing a Software Package for Distribution 211

232 Distributing Nested Software Packages Distributing Nested Software Packages The distribution behavior of a software package containing nested software packages varies depending on the following factors: v The type of change management operation submitted on the primary package v The change management status of the primary and nested software packages v The installation options set in the primary and nested software packages When Software Distribution change management operations are performed on a primary package, the operation is also performed on the nested software packages. The following is the behavior of a primary software package containing nested software packages for each change management operation: Install The install operation installs the primary software package and its nested software packages in the order specified during the package creation. Even if the Stop on failure option is not selected in the primary package, if the installation of a nested software package fails, the installation of the primary package fails also. Recovery actions may be performed, depending on the installation options specified in the software package. For example, if the install operation was submitted in undoable mode, the target system is returned to its state prior to the installation failure. Remove Submitting a remove operation on a primary software package that contains nested software packages removes the packages in the reverse order in which they were originally installed. Undo The undo operation is performed on the primary package and nested software packages in the reverse order in which they were originally installed. The undo operation is successful if the operation on the primary package completes successfully, and the operation on each of the nested software packages completes successfully. The undo operation fails if the primary software package or one of its nested software packages were not originally installed in transactional mode. Accept The accept operation is performed on the primary software package and its nested software packages in the order specified at creation time. If one or more software packages are in error, they are ignored during the accept operation. The accept operation completes successfully only if the primary software package and its nested software packages are in a not-undoable state. Commit The commit operation is performed on the primary software package and its nested software packages in the order specified at creation time. The commit operation completes successfully when the primary package and its nested packages are installed in a committed state. Verify The verify operation is performed on the primary software package and on its nested software packages in the order specified at creation time. For more information about change management operations, see Change Management Operations on page 191. See Nested Packages on page 73 for more information about specifying the order of execution of the primary package and nested software packages. 212 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

233 Distributing Nested Software Packages Things To Consider Before implementing nested software packages, consider the following: v Nested software packages are built independently from the primary software package. v Nested software packages are imported into the Tivoli environment individually. If one or more nested software packages is not in the object database and an operation has been submitted on the primary package, the operation is unsuccessful and an error message for each missing package is displayed. v The source host for all packages must be the same. v Nested software packages can reside in different policy regions, but the user performing an operation on a primary package containing nested software packages must have the proper authorization role. v The repair operation is performed only on the primary software package. No changes are performed during this operation. v No checks are performed on the nested software packages when the primary package is imported into the object database. All checks are performed when a change management operation is submitted on the primary package. For this reason, no checks are performed when a software package is removed from the object database or renamed. v Submitting operations in a disconnected target mode does not have any effect on nested software packages. Use only server commands. v Utilizing the MDist 2 functionality, each software package is considered a segment. When distributing or loading a primary package containing two nested software packages, the distribution uses three distinct segments: one for the primary package, one for the first nested software package, and one for the second nested software package. Chapter 9. Preparing a Software Package for Distribution 213

234 Distributing Nested Software Packages Nested Package Distribution Scenario Consider the software package structure illustrated by the following figure: Software Packages B, C and D are nested in Software Package A. The order of execution of the software packages is the order specified during the creation of the primary software package. In this scenario, the primary software package has been specified to be executed first and the nested packages follow. The following is the order of execution of the software packages: 1. Software Package A 2. Software Package B 3. Software Package C 4. Software Package D Assume that the following settings are specified in Software Package A (primary software package): v Default change management operation: install v Default change management operation mode: undoable v Stop on failure option is not selected (stop_on_failure = no) 214 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

235 Distributing Nested Software Packages The default change management operation and operation mode set in the primary package override the defaults specified in the nested software packages. When an install operation is submitted on the primary package, the following steps are performed: 1. Software package status information is retrieved from the configuration repository for Software Packages A, B, C and D. Result: successful validation. 2. Install operation executed on Software Package A. Result: installed successfully. 3. Install operation executed on Software Package B. Result: installed successfully. 4. Install operation executed on Software Package C. Result: failure. 5. An undo operation is executed on Software Package A. The log reports that the rollback has been performed successfully. 6. An undo operation is executed on Software Package B. The log reports that the rollback has been performed successfully. 7. An undo operation is executed on Software Package C. The log reports that a rollback has been performed successfully. 8. Software Package D is not executed. No log is generated. Although the Stop on failure option was not selected (stop_on_failure = no) in the primary package, the install operation is interrupted and recovery operations are performed. The related reports containing the results of the operation are sent in accordance with the log information options specified in each of the software packages. However, the log for the primary software package also contains the results of the operations for the nested software packages. Because the nested software packages were returned to their original state, a report is not transmitted back to the server. When an installation completes successfully, and the Historical Database and Change Management Status features are enabled, the configuration repository is updated with the information related to the primary software package and the nested software packages. Checking the Outcome of a Distribution You can check the outcome of a distribution in the following ways: v Check the MDist2 status using the wmdist command or checking the MDist2 Distribution Status console v See the Software Distribution message or message ID reported in the Message table of the MDist 2 database. v Software Distribution log. See Software Distribution Logs on page 296 v Check the CM_STATUS in the configuration repository. See Chapter 13, Integrating Inventory with Software Distribution, on page 271. v Through integration with the Tivoli Enterprise Console, check Enterprise Console events for information about failed and successful target exit codes, and messages related to failed distributions. See Chapter 12, Integrating the Tivoli Enterprise Console, on page 263. v Check results logged into the Software Distribution 4 notice group. v Check for an to the specified user. Chapter 9. Preparing a Software Package for Distribution 215

236 Distributing Nested Software Packages Checkpoint Restart Service for Network Failure or Power Interruptions If the distribution of a software package is interrupted by a network failure, machine reboot, or power failure, the gateway recognizes the failure and Software Distribution and MDist 2 recover the problem by retrying the distribution when the timeout period specified expires. The distribution is automatically resumed when the cause of failure has been corrected. For network failures, the distribution resumes from the last completed block. The amount of data that must be retransmitted depends on the MDist 2 buffer size. The default is 16 KB. For power failures, the distribution resumes from the last successful checkpoint. When a power failure occurs, a handshake occurs between repeaters and between repeaters and endpoints that allow a data stream to be resumed at the point of interruption. This handshake occurs for each connection, so that if there is a failure within the hierarchy during the distribution of a large package, the distribution need not be restarted from the beginning. For transmissions between repeaters and endpoints, the buffer size used to set checkpoints is set dynamically. Normally, the size of the buffer is set to a tenth of the size of the package. If there is a failure, the transmission restarts from the last checkpoint save. The buffer has a minimum size of 1 MB and a maximum size of 2 GB. Therefore, the number of checkpoints differs from ten, only in the case of packages smaller than 10 MB or larger than 20 GB. If you set a fixed size for the buffer, you can define a buffer size by assigning a value to the checkpoint_buffer_size attribute in the swdis.ini file. This attribute controls checkpoint buffers in the following way: v If the attribute is not specified, dynamic buffer evaluation is used. v If the attribute is set to equal 0, checkpointing is disabled. v If the attribute is set to equal a value between 1 MB and 2 GB, the buffer size is set to that value. A checkpoint save is made when a file is transmitted that raises the number of bytes transmitted since the last checkpoint save to a value greater than or equal to the buffer size. If the transmission comprises just one file, no checkpoint save is made, even if the file size is greater than or equal to the buffer size, because files cannot be broken. Example A package has a size of 3800 KB. Therefore, the buffer size is set to the minimum for dynamic buffer, 1 MB. The package contains four files. The file sizes and checkpoint save positions are shown in the table that follows: File Size Checkpoint Save File KB After transmission File KB File KB After transmission File KB 216 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

237 Distributing Nested Software Packages In this example, the first checkpoint save is made when 1200 KB has been sent and the second when a further 1100 KB has been sent. The buffer size is always reached or exceeded before the checkpoint save is made, and the save is never made during the transmission of a file. If this package contained only one file of 3800 KB, there would be no checkpoint saves made even though the size of the file is more than three times the buffer size. Scheduling a Distribution To schedule the distribution of a software package, you can use either the Tivoli Management Framework service or the IBM Tivoli Configuration Manager Activity Planner service. With the Tivoli Management Framework service, the distribution itself is the task to be performed and the execution of the task is defined as a job. The scheduler enables you to do the following: v Schedule jobs to occur at specific times and within a specified time frame. v Schedule jobs to repeat a specified number of times at specified time intervals. v Schedule jobs to repeat indefinitely. v Restrict scheduled jobs to run only during the day, at night, during the week, or on weekends. Refer to the Tivoli Management Framework: Planning for Deployment Guide for more information about the scheduler service. The Activity Planner is a much more robust, powerful scheduling service. With Activity Planner you can do the following: v Schedule a plan containing any number of activities, each activity having its own execution schedule. v Define several types of different activities in the same plan, not just Software Distribution operations. Activities include: Software Distribution operations, task library tasks, inventory scans, and pristine manager installations. v Condition execution of activities on other activities in the same plan. v Monitor and control plans and individual activities. v Pause and resume plans and individual activities. Refer to the User s Guide for Deployment Services for information about the Activity Planner service. To schedule a change management operation using the Tivoli Management Framework scheduler service, complete the following steps: 1. From the change management operation dialog, click Schedule to schedule the operation at a future time. 2. Click Schedule to schedule distributions at a future time. See Activity Planner on page 317 for information about a scheduling facility that enables you to manage a group of operations as a single operation from a single machine in the network. Software Distribution displays the Add Scheduled Job dialog. Chapter 9. Preparing a Software Package for Distribution 217

238 Distributing Nested Software Packages The Add Scheduled Job dialog can be used to schedule jobs for the following operations: v Install v Remove v Accept v Commit v Undo v Load v Unload Software Distribution automatically retries an unavailable target for the length of its distribution lifetime, without waiting until the distribution to all other targets is complete. 218 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

239 Distributing Nested Software Packages Note: When performing a distribution of a software package profile using either the Distribute option from the Profile Manager menu or the drag-and-drop method, the retry options do not function. You can also set retry options by selecting Set Retry/Cancel/Restriction Options from the Add Scheduled Job dialog. The Set Retry/Cancel/Restriction Options dialog is displayed. When the time set in the Retry Options group box arrives, any targets that experienced a failed distribution prior to this time are retried. Any ongoing distributions, or distributions that have been cancelled are not resubmitted. Conversely, if a repeat is scheduled in the Repeat The Job group box, the distribution is repeated for all targets, including those that were previously unavailable and are currently being retried by the MDist 2 service. The result is two instances of the same distribution to the same target at the same time. To avoid this situation, set the lifetime of the distribution shorter than the repeat interval. See Timeout Settings in Overwriting Default Variables on page 204 for more information about setting the lifetime of a distribution. If Checks, Ignore, or Force is selected in the Checks group box from the change management operation dialogs that support the scheduling function, the check requested is performed when the scheduled time arrives and the job is executed. If retry or repeat, or both, are selected for a job, the checks are performed before the execution of the selection. Checks are not performed immediately for scheduled distributions because the state of the software package for a target could change before the scheduled time arrives. Refer to the Tivoli Management Framework: Planning for Deployment Guide for more information about creating tasks and jobs and using drag-and-drop to schedule a job. Chapter 9. Preparing a Software Package for Distribution 219

240 Distributing Nested Software Packages Click Close to close the Add Scheduled Job dialog and return to the Install Software Package dialog. 220 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

241 Chapter 10. Using Data Moving In any distributed systems environment, the issue arises of how to maintain consistency of data across the system. Data updates have to be distributed from a central point, and information collected locally must be retrieved for central consolidation and storage. The Data Moving Service integrates data movement capabilities into the software package distribution process. It provides the following benefits: v Support for sending, retrieving, and deleting files. Any type of file can be sent, retrieved or deleted using the data moving command. v Ability to send files from a source endpoint to a number of target endpoints. v Ability to send, retrieve, or delete multiple files by using wildcards or matching indicators, in addition to Software Distribution standard variables. For more information on Software Distribution variables, refer to the Reference Manual for Software Distribution. v Ability to apply the specified operation to all subdirectories and files in the path. v Lenient distributions. v Ability to define pre- and post-transfer tasks. v Ability to define software dependencies for data transfers. The data transfer can be made dependent on the state, on the destination system, of a specified version of a software package. v Code page translation capabilities. v Use of Tivoli s multiplexed distribution (Mdist2) service, which provides queuing, priority, checkpoint restart, distribution monitoring, and bandwidth control. v Support of data moving operations in an OS/400 environment. v Integration with the Activity Planner. Note: The Data Moving Service is supported on endpoints and users, but is not supported on devices. Configuring the Data Moving Service All data moving operations use the same software package object, DataMovingRequests.1. This object contains certain standard information to be used by all data moving operations, including logging options. If this object is not available, no data moving operation can be performed from the CLI or the Activity Planner. This object is normally created automatically, in the DataMovingProfile profile manager within the default policy region, when you install Software Distribution. However, you can create the object later by running data moving command, wspmvdata, using one of the mutually exclusive options: v -A This creates the DataMovingRequests.1 object in a profile manager that belongs to a region having SoftwarePackage as managed resource. v -p profile manager Copyright IBM Corp. 2002,

242 Configuring the Data Moving Service This creates a DataMovingRequests.1 object in the specified profile manager. Note: Before specifying a profile manager name, make sure that the profile manager belongs to a region having SoftwarePackage as managed resource. For more information about defining these options, see the section on wspmvdata in Using Commands in the Reference Manual for Software Distribution As with other software package objects, operations using the DataMovingRequests.1 object can only be performed by users who have been assigned at least the senior role in the policy region where the software package object resides. You may wish to allow some users to perform data moving operations but not change management operations, for example installing and removing software packages. You can achieve this by setting up a policy region that only contains the DataMovingRequests.1 object and assigning all the users a senior role in that region. If you decide to do this, you must remove the software package from the policy region where it has been automatically installed, and recreate it in a profile manager in the data moving policy region, using the -p argument. Notes: Data Moving Scenarios 1. Information about operations using the DataMovingRequests.1 object is not stored in the Tivoli configuration repository. 2. The properties for the DataMovingRequests.1 object that appears in the profile manager have limited functionality compared with the properties for other objects. They only provide access to the Package Properties dialog. They do not allow you to open the software package file in the Software Package Editor, to open the Nested packages dialog, or to use drag and drop to perform data moving operations on targets. Although you can physically drag and drop the DataMovingRequests.1 object, no operation is performed. The Data Moving Service supports the following scenarios: v You want to send a file held in a central location to multiple destinations. v You want to retrieve a specific file from a series of locations and consolidate the retrieved files in a single, central location. v You want to delete a specific file from a series of locations. v You want to move a set of files from one endpoint to a number of endpoints. Sending Data to Multiple Destinations A retailing company with several branches distributes its price list to all branches. Updates to the price list are made at the central office. An updated price list must then be distributed in a way that ensures that all branches are kept in line with the central pricing information. To complete the data movements required for this scenario, you define a data moving task with the following characteristics: v A single data origin, which is a software distribution source host functioning as a gateway or a repeater at the head office. v A destination list of endpoints that includes all the branches where pricing information is held. 222 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

243 Data Moving Scenarios v A post-transfer task on the endpoints that updates the branch price lists with the new information. v A post-transfer task on the source host to collect results from the endpoints. To perform this operation from the GUI, perform the following steps: 1. Open the DataMovingProfile in your policy region. 2. Right-click on the DataMovingRequests.1 object to display a pop-up menu. 3. Select the Send menu item. The Data Moving Service Send Operation dialog is displayed. 4. Fill in the dialog as described in the above image. Chapter 10. Using Data Moving 223

244 Data Moving Scenarios 5. Click on Send & Close to perform the send operation. For more information about the settings in this dialog, refer to the Reference Manual for Software Distribution and the online help available from this dialog. The following example shows a command to complete such a transfer from the Command Line Interface. wspmvdata \ -r tpost:/tmp/importpl.sh -r spost:/tmp/results.pl \ -P sp:/prices -P tp:/data/sales plist Using this command, the file plist, which is located in the directory /prices on the centoff source host system is copied to pi003-ept and pi006-ept systems, in the /data/sales destination directory. Following the transfer, the script importpl.sh, which is located in the /tmp directory on the endpoints, runs on the pi006-ept, pi003-ept endpoint systems and the script results.pl, which is located in the /tmp directory on the source host runs on the centoff source host. For more information on the contents of the results.pl script, see Examples on page 231. Note: If the target directory is not preceded by a backslash, the selected file is created in the default directory: /<default dir>/data/sales/plist, where, the default dir for Tivoli managed nodes is the current working directory of the source host process implementation ($DBDIR). The default dir for endpoints is the <prod_dir> directory, which can be set in the swdis.ini file. For more information on paths and directories, see the Reference Manual for Software Distribution. In the retailing company, it is often necessary to send files that have very similar names, except for some specific tokens within the name, for example sales.data.*.all. By using wildcards, you can select all files that match the specified file name. The following example shows a command to send all files present in the c:/tmp source directory on the source system centoff with prefix plist and suffix source.txt to targets pi003-ept and pi006-ept. The -R option applies the operation to all subdirectories in the specified path. wspmvdata -R -P sp:c:/tmp -P tp:/tmp plist.*source.txt Data Retrieval from Multiple Origins Each day, sales transactions for the retail company are collected by the branches where the sales are made. At the end of the day, the sales transactions must be transferred to the central office where the sales ledger and central stock registers can be updated. To complete the data movements required for this scenario, you define a data moving task with the following characteristics: v A pre-transfer task to run on all the branch endpoint systems to extract the sales transactions to a file. v An origin list that includes all the branch endpoint systems from which sales transactions are to be retrieved. v A single destination source host system functioning as a gateway or a repeater that is the central office. v A post-transfer task that updates the central office sales ledger and stock register with the sales transactions. 224 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

245 Data Moving Scenarios To perform this operation from the GUI, perform the following steps: 1. Open the DataMovingProfile in your policy region. 2. Right-click on the DataMovingRequests.1 object to display a pop-up menu. 3. Select the Retrieve menu item. The Data Moving Service Retrieve Operation dialog is displayed. 4. Fill in the dialog as described in the above image. 5. Click on Retrieve & Close to perform the retrieve operation. For more information about the settings in this dialog, refer to the Reference Manual for Software Distribution and the online help available from this dialog. The following example shows a command to complete such a transfer from the Command Line Interface. Chapter 10. Using Data Moving 225

246 Data Moving Scenarios wspmvdata -s -r tpost:/tmp/import_file.sh - r spre:/tmp/export_file.sh -P sp:/sales -P tp:/data/sales trans This command runs a pre-processing script called export_file.sh on the pi003-ept, pi006-ept endpoints to extract data. The extracted data is saved in a file called trans. The trans file is stored in the /sales directory on each endpoint. Afterwards, the trans files are retrieved from the endpoints and stored on the source host system, in a subdirectory within the /data/sales destination directory. The naming convention for the subdirectory is as follows: endpointname_distributionid_timestamp Note: The destination directory (/data/sales) on the system is not created with this command, so it must be created beforehand. After the transfer, the script import_file.sh runs on the source host system. Alternatively, each day a different file is created on all the branch endpoint systems that records the transactions that have taken place during the day. This way, by the end of the week, you will have a set of files that are named the same, except for the date that is inserted in the file name, for example sales.data transactions, sales.data transactions and so on. By using matching indicators, $(MAX) to select the highest value or $(MIN) to select the lowest value, you can move the most recent or oldest file. The following example shows a command to select and move the file on the source directory c:/tmp with prefix transactions and suffix data.txt and with the highest value, i.e. the most recent date, within the set. wspmvdata -P sp:c:/tmp -P tp:/tmp transactions.$(max)data.txt Another form of matching indicator processing is based on the substitution of part of the file name with the endpoint name. For example, the file name might be sales.data.store52.transactions, where store52 is the endpoint name for a specific store. The same naming convention will be applied to all similar files on all endpoints, but each of them would have a different store number. In order to perform a retrieve operation on all such files, it is necessary to specify a list of targets and request the sales.data.$(ep_label).transactions files. This function is only supported for retrieve and delete operations, as the $(ep_label) variable is resolved at the target. The following example shows a command for retrieving all files in the directory /tmp on the pi003-ept and pi006-ept endpoints with prefix transactions and suffix data.txt replacing the $(ep_label) variable with the actual name of the endpoint. wspmvdata -P sp:c:/tmp -P tp:/tmp transactions.$(ep_label)data.txt In this case, the sales.data.pi003-ept.transactions file is retrieved from the pi003-ept endpoint, the sales.data.pi006-ept.transactions file is retrieved from the pi006-ept endpoint, and so on. Note: The use of both the wildcard (*) and one of the matching indicators, $(MIN), $(MAX), $(ep_label), is not supported within the same file name. This happens because the wildcard applies the operation to multiple files, while the matching indicators can identify only a single file. You can use only the asterisk or one of the matching indicators for the file name. 226 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

247 Data Moving Scenarios Deleting a File on Multiple Systems There is a software upgrade, which results in changes to data structures, and a file that is being used at all branches is no longer required by branches that are using the new software. To complete the data movements required for this scenario, you define a data moving task with the following characteristics: v A destination list that includes all the branch systems where the file is present. v The name and location of the file on the branch systems. v The delete argument. v A software dependency to ensure that only branches with the new software are affected. Chapter 10. Using Data Moving 227

248 Data Moving Scenarios To perform this operation from the GUI, perform the following steps: 1. Open the DataMovingProfile in your policy region. 2. Right-click on the DataMovingRequests.1 object to display a pop-up menu. 3. Select the Delete menu item. The Data Moving Service Delete Operation dialog is displayed. 4. To set the software dependency, click on Advanced Options menu and select the Software Dependencies menu item. The Software Dependencies dialog is displayed. For more information on software dependencies, see Defining the Advanced Options on page Enter the software package name and its state. 6. Click OK to save the changes and return to the Data Moving Service Delete Operation dialog. 7. Fill in the dialog as described in the above image. 8. Click on Delete & Close to perform the delete operation. 228 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

249 Data Moving Scenarios For more information about the settings in these dialogs, refer to the Reference Manual for Software Distribution and the online help available from this dialog. The following example shows a command to complete such a transfer from the Command Line Interface. wspmvdata -d /temp/oldfile Using this command, the file oldfile stored in the directory /temp is deleted from the pi003-ept, pi006-ept systems, on the condition that the software SW_Package version 2 is in installed and committed state. Note: Empty directories are removed, while directories containing data are not deleted and a warning message is inserted in the log file. No origin system is required for the delete operation. Moving Files from Endpoint to Endpoint In a distributed environment with a server and several endpoints connected to a gateway, it is possible to retrieve a file from a source endpoint and send it to one or more endpoints through a source host functioning as a gateway or a repeater. This function is only supported for send operations. To perform this operation from the GUI, perform the following steps: 1. Display the Data Moving Service Send Operation dialog as described in Sending Data to Multiple Destinations on page In the Data Origin Type pull-down menu, select the EndPoint menu item. The Managed Node Name text field changes to Endpoint Name and the (...) button is disabled. 3. Fill in the fields as required. 4. Click on Send & Close to perform the send operation. The following example shows a command to move file status 1.txt from source endpoint b1 to target endpoints b2 and b3. The -R option applies the operation to all subdirectories in the specified path. wspmvdata -R -P sp:c:/tmp -P tp:/tmp status1.txt Defining the Advanced Options For all Data Moving operations, you can define the advanced options also available for the Change Management operations. For more information, see Executing Change Management Operations on page 192. Selecting Software Dependencies from the Advanced Options pull-down menu allows you to specify a software dependency for the Data Moving Service operation. 1. To specify a software dependency, enter the software package name the Data Moving operation will be dependent on in the Package Name text box or click the (...) button to browse for the software package. 2. To define the state for the software package, click on either the Installed (I) or Not Installed (R) radio button. It is also possible that the software package has not been installed. 3. Using the Software Dependencies List box, you can also add or remove software dependencies. Chapter 10. Using Data Moving 229

250 Data Moving Scenarios 4. Click Set to save the software dependencies you specified, or click Set & Close to save the software dependencies and return to the Data Moving Service Operation dialog. Using Pre- and Post-Processing Scripts When you define a data moving operation, you can specify up to four scripts to be invoked during the data moving process. These scripts define pre- and post-processing tasks on the origin and destination systems between which you want to move data. The following are typical examples of tasks you can define using the script facility: v Extracting data from a central repository on the origin system and storing it in a file that is to be moved to the destination systems. v Updating a local repository on the destination systems with data from the file that has been received. The sequence in which the scripts run in a send operation from a source host to multiple endpoints is as follows: 1. The pre-processing script runs on the origin system, which is the source host system that was specified in the command. 2. A pre-processing script runs on each destination system. The destination systems for a send operation are endpoints. 3. A post-processing script runs on each endpoint. 4. The post-processing script runs on the source host. The sequence in which the scripts run in a retrieve operation is as follows: 1. A pre-processing script runs on the destination system, which is the source host. 2. A pre-processing script runs on each origin system. The origin systems for a retrieve operation are endpoints. 3. A post-processing script runs on each endpoint that was an origin for the retrieval. 4. The post-processing script runs on the source host. For delete operations, there is no origin system. Pre- and post-processing scripts run on the endpoints from which the file is to be deleted before and after file deletion. The sequence in which the scripts run in a send operation from endpoint to endpoint is as follows: 1. The pre-processing script runs on the origin system, which is the endpoint that was specified in the command. 2. A post-processing script runs on the origin system, which is the endpoint that was specified in the command. 3. A pre-processing script runs on each destination system. The destination systems for a send operation are endpoints. 4. A post-processing script runs on each destination system. The destination systems for a send operation are endpoints. When you write a script to be used with the wspmvdata command, you must include the following arguments: 230 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

251 Using Scripts $1 Operation Type This identifies the type of data-moving operation. Possible values are send, retrieve, and delete. $2 Location Type This indicates whether the script will run on a Tivoli managed node (source host) or on an endpoint. Possible values are EP_SCRIPT for endpoints, and SH_SCRIPT for source hosts. $3 Timing Type This indicates whether the script will run before or after the data moving operation. Possible values are PRE_SCRIPT and POST_SCRIPT. $4 Data File This is the fully qualified name of the file that was moved or deleted. $5 Endpoint Label This is the unique endpoint identifier on which the operation was performed. This parameter is only available for the post-processing script on the source host. $6 Endpoint Result This indicates the result of the operation on the endpoint. Possible results are 0 (success) and 1 (failure). This parameter is only available for the post-processing script on the source host. Note: The new Endpoint Result parameter allows you to condition the execution of the post-processing script on the source host to the result of the operation on the endpoint, so that, for example, the script is not run if the operation on the endpoint has not been successful. The values assigned to these arguments depend on the arguments you specified for the wspmvdata command. Note: If you are writing a post-processing script for use on Windows platforms, you must include code to deal with any errors caused by the file being locked. This situation can occur when an identical file, in name and content, already exists on the target system and is locked at the distribution time. In such a case, the data moving operation does not fail with file locked, because it does not attempt to replace the file, since there are no changes. As the operation has not failed, the post-processing script will run and must be able to deal with a locked file. Examples The following command includes the script merge.sh as a post-processing script on the target system. wspmvdata -r tpost:/usr/sd42/scripts/merge.sh /usr/sd42/source/data.txt The target system for this command is a source host and the source list includes two endpoints. The purpose of the merge.sh script is to create a single file on the source host system by merging the files that have been retrieved from the endpoints. Chapter 10. Using Data Moving 231

252 Using Scripts #!/bin/sh #=================================================== CM_OPERATION=$1 LOCATION=$2 PRE_POST=$3 DATA_FILE=$4 print "CM Operation:" $CM_OPERATION > /usr/sd42/scripts/merge.out; print "Location:" $LOCATION >> /usr/sd42/scripts/merge.out; print "Pre-post:" $PRE_POST >> /usr/sd42/scripts/merge.out; print "File Name" $DATA_FILE >>/usr/sd42/scripts/merge.out; print "===========================================" >>/usr/sd42/scripts/merge.file; print "= FILE being merged: $DATA_FILE at: `date` =" >>/usr/sd42/scripts/merge.file; print "===========================================" >>/usr/sd42/scripts/merge.file; cat $DATA_FILE >> /usr/sd42/scripts/merge.file; rc=$? print "Error level is:" $rc >> /usr/sd42/scripts/merge.out; exit $rc When the merge.sh script runs, the fixed parameters are set as follows: $1 Retrieve $2 SH_SCRIPT $3 POST_SCRIPT $4 /usr/sd42/source/<endpoint name>_<distributionid>_<timestamp> Note: A single directory is created on the source host for each endpoint. This ensures that each retrieved file is stored in a unique directory on the source host. The script writes these values and any errors to an output file and appends the contents of the data file to the file usr/sd41/scripts/merge.file. The following command includes the results.pl as a post-processing script on the target system. wspmvdata -r tpost:/tmp/importpl.sh -r spost:/tmp/results.sh -P sp:/price -P tp:/data/sales plist The target system for this command is a source host and the source list includes two endpoints. The purpose of the results.pl script is to create a report on the source host system containing the results of the operations performed on the endpoints. #!/usr/bin/perl ######################################################################## # Post script at Source Host. It writes file /usr/swd/scripts/sh_post.out with operation results# ######################################################################## ($operation,$location,$type,$file,$ep_label,$result)=@argv;open(tmp, ">>/usr/swd/scripts/sh_post.out") die ("Cannot open sh_post.out file! \n"); print TMP "CM Operation: $operation \n"; print TMP "Location: $location \n"; print TMP "Pre-post: $type \n"; print TMP "File Name: $file \n"; print TMP "The operation at endpoint:$ep_label, has returned:$result\n"; close(tmp); The following output is written to the file created by the script: CM Operation: send Location: SH_SCRIPT Pre-post: POST_SCRIPT File Name: /usr/sd42/source/file.txt 232 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

253 Using Scripts The operation at endpoint:pi003-ep, has returned:0 CM Operation: send Location: SH_SCRIPT Pre-post: POST_SCRIPT File Name: /usr/sd42/source/file.txt The operation at endpoint:pi006-ep, has returned:0 The Data Moving Service in an OS/400 Environment The Software Distribution Data Moving Service is available to send, retrieve, and delete files in an OS/400 environment. A full description of the Data Moving Service is given in Chapter 10, Using Data Moving, on page 221. The purpose of this section is to provide some examples of data moving commands used in the OS/400 environment. These demonstrate the different conventions for specifying file locations that are used in the OS/400 environment. See The OS/400 Native and Integrated File Systems on page 92. Note: Notice the use of the codepage translation option ( c) in the examples that follow. Using this argument results in the file that is sent being translated to EBCDIC codepage before it is written to the OS/400 destination location or to ASCII if it retrieved from an OS/400 location. The following example moves the file data.dat from a Windows or UNIX source host to the OS/400 IFS and runs a post-processing program on the target system. The command specified here is identical to the command that would be used to take the same actions in a UNIX file system. wspmvdata -c -P sp:/usr/sd/source -P tp:/usr/sd/target -r tpost:/usr/sd/scripts/post.sh data.dat At installation time, this command copies the file data.dat from the source host to the location on the target system identified by the IFS path /usr/sd/target. After the file has been installed, the post-processing program located at /usr/sd/scripts/post.sh runs on the target machine. In the following example, the file data.dat is sent from a Windows or UNIX source host to an OS/400 physical file. A post-processing program runs on the target system. wspmvdata -c -P sp:c:/usr/sd/source -P tp:/qsys.lib/mylib.lib/data.file -r tpost:/qsys.lib/mylib.lib/post.pgm data.dat At installation time, this command collects the file data.dat from the source host and adds it to the library MYLIB.LIB as member of the physical file DATA.FILE. After file has been installed, the post-processing program located at /QSYS.LIB/MYLIB.LIB/POST.PGM runs on the target machine. In the following example, the file data.dat is sent from a Windows or UNIX source host to an OS/400 library. wspmvdata -c -P sp:c:/usr/sd/source -P tp:/qsys.lib/mylib.lib -r data.dat At installation time, this command collects the file data.dat from the source host and adds it to the library MYLIB.LIB as a physical file (DATA.FILE). The file will Chapter 10. Using Data Moving 233

254 The Data Moving Service in an OS/400 Environment contain one member with the same name (DATA.MBR). The file is created by default as an OS/400 source physical file (PF-SRC). In the following example, mymember.mbr, which is a member of the physical file todelete.file, is deleted. wspmvdata -d -P tp:/qsys.lib/mylib.lib/ todelete.file mymember.mbr Notes: 1. You cannot use the Data Moving Service to delete OS/400 physical files. Only file members can be deleted. 2. In an OS/400 environment, the wildcard character (*) is supported only if it is used by itself. For example, you can specify to retrieve all files in a directory using just the (*) wildcard character, but you cannot specify to retrieve files that match the following pattern: data.*.sh. 3. The data moving send operation from endpoint to endpoint is not supported if the file to be sent originates from an OS/400 native file system. 234 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

255 Chapter 11. Configuring a Network Topology Using Software Distribution you can create and distribute software packages. However, some planning at this point will lead to a more efficient and manageable distribution environment. In particular, you should consider the following questions: v What types of software do you want to distribute and how much disk space does each require? v Will certain types of network connections slow down a distribution (such as slow WAN connections)? v How can you configure the network and repeaters to efficiently distribute multiple software packages? v Are other Tivoli applications available to ease distribution efforts? This chapter addresses these questions by presenting an example scenario involving NoonTide Enterprises. NoonTide Enterprises is a fictitious company with some of the network complexities that face today s businesses. This scenario describes the step-by-step procedure for configuring a distribution environment. It includes the following steps: v Assessing the network topology and available departmental resources. v Determining the hierarchy of repeaters that best suits the actual network topology exploiting the multiplexed distribution service for improved performance. v Creating the necessary repeaters, their range of managed node clients, and setting repeater parameters. v Tuning and configuring repeaters as depots to store distribution data in order to reduce network traffic for frequently distributed data sets. You can also configure the distribution manager by creating a RIM database and a RIM object in order to monitor and control distributions. You can also monitor and control distributions using the Distribution Status Console. Refer to the Tivoli Management Framework: User s Guide for more information about the Distribution Status Console. The distribution manager stores status information about a distribution in the database tables. There is one distribution manager for each Tivoli management region that keeps track of all the distributions started in it. If the distribution spans multiple Tivoli management regions, all status information is stored in the distribution manager in the initiating Tivoli management region and no status information is stored in the interconnected Tivoli management regions. You can use the Inventory database to check the status of software packages installed on endpoints and software packages loaded on depots. Additional tuning is required for the roaming endpoints feature. Refer to the Tivoli Management Framework: Planning for Deployment Guide for more information about the roaming endpoint feature. For the purpose of this scenario, we assume that you are the senior system administrator at NoonTide. The senior authorization role is required to perform the procedures described in this scenario. Copyright IBM Corp. 2002,

256 Introducing NoonTide Introducing NoonTide NoonTide Enterprises develops, markets, and sells electronic products to an international market. Their principal departments include Engineering, Support, Marketing, Administration, and Sales. NoonTide has installed and uses Tivoli Management Framework and several Tivoli applications to manage a distributed network that is divided into seven subnets, four in the corporate office and three in regional offices. Each department is represented by a policy region, which is created to model the management and organizational structure of a network computing environment, as well as to enforce common policies between related departments. In NoonTide s Tivoli management region environment, each policy region houses each department s resources such as subregions, managed nodes, endpoints, and profile managers. The following policy regions exist on the administrator s desktop. For example, the Engineering policy region represents the Engineering department. The Engineering policy region contains a UNIX managed node gateway, called big, that serves endpoints. The Engineering policy region also contains the Product, Research, and Test subpolicy regions that group and control access to resources for these three components of the Engineering department. 236 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

257 Introducing NoonTide Network Architecture NoonTide also organizes its environment according to administration tasks. The System Monitors and Software Distribution policy regions contain Tivoli Distributed Monitoring and Software Distribution subregions, jobs, and tasks. The pescado-region policy region is the default policy region that is created when the Tivoli management region server (Tivoli server) is installed. The name of the default policy region is taken from the name of the machine that is hosting the Tivoli server (pescado). Understanding and planning NoonTide s network topology is essential to configuring its distribution environment. NoonTide has seven subnets four in the corporate office and three in regional offices. Subnets are connected either by Ethernet connections, which have bandwidths of 100 Mbps (megabits per second), or by T1 lines, which have bandwidths of 1 Mbps. Each subnet contains a UNIX or a Windows managed node gateway that connects to the Tivoli server. Endpoint gateways are installed on managed nodes in subnets that have endpoint clients. To distribute a software package profile to a managed node or gateway, you must install the endpoint service on it first. A repeater can be part of a gateway (gateway repeater) or it can be created as a standalone repeater on a managed node that does not have a gateway on it (standalone repeater). Standalone repeaters can distribute only to other repeaters, while gateway repeaters can also distribute to their endpoints (targets). The repeater manager maintains information about the Tivoli network configuration, including target clients and repeater sites. See Configuring Repeater Sites on page 241 for more information about configuring repeaters. The endpoint manager controls and configures gateways and endpoints, assigns endpoints to gateways, and maintains the endpoint list. The endpoint manager is available from the Tivoli desktop. For information about the endpoint manager, endpoint gateways, and managed resources, refer to the Tivoli Management Framework: Planning for Deployment Guide. Chapter 11. Configuring a Network Topology 237

258 Network Architecture The following diagram illustrates NoonTide s network topology. Subnet 3 Subnet 4 Subnet 5 Subnet 6 Subnet 7 oak big pearl diamond lapis Tivoli management region server rainbow odin pescado dollar electron alloy Subnet 1 Subnet 2 Ethernet connection T1 connection lolo Creating a Repeater Hierarchy NoonTide Enterprises has configured its network environment to optimize use of Tivoli s Multiplexed Distribution (MDist 2) service. Every repeater (gateway or standalone) contains both an MDist repeater and an MDist 2 repeater. However, Software Distribution uses primarily MDist 2. MDist 2 enables you to perform asynchronous distributions of large amounts of data to multiple targets in an enterprise. The MDist 2 service maximizes NoonTide s data throughput by performing the following operations: Parallel distribution Enabling parallel distribution to hosts on the same subnet. Using this feature, the data flows from the source host pescado through the dollar and rainbow gateway repeaters and down to the endpoints, if both the Marketing and Administration departments need this application. This feature results in a distribution that can be faster than sending copies of the software in serial to each machine. Spreading the distribution load across networks Spreading the distribution load across a network tree limits resource contention that can arise when one server is responsible for distributing to many client machines. Sending single copies of the data across slower links Using multicast for distributions sends software packages just once to a group of targets, reducing the number of copies distributed, and freeing up network resources. With the same connection, only one software package is transmitted from the source host to only those machines configured with 238 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

259 Creating a Repeater Hierarchy multicast and ignores the classic repeater hierarchy. For example, pescado (Subnet 1) distributes to all endpoints configured with multicast in Subnet 2. The repeaters redistribute the single copies in parallel to other hosts on the far side of the slow connection. This distribution is a more effective use of the network than sending a copy of the software across the network gateway for each remote target. For example, pescado can efficiently distribute to pearl, diamond, and lapis using electron as a repeater site. Using repeater depots Enabling repeaters to temporarily or permanently store distribution data at an intermediate fan-out point called a repeater depot. A repeater depot has the built-in MDist 2 capability of permanently or temporarily storing data segments. A repeater configured as a permanent depot maintains the data in the repeater depot even after the distribution has completed. A repeater depot also enables you to store software distributions on nodes closer to the targets. For example, the diamond gateway, which has repeater depot functionality, can start a distribution to software packages from its repeater depot to the target systems associated with it, rather than from the source host. Caching distributions Caching distributions, which enables the checkpoint restart functionality. If a distribution failure occurs for one target, the fan-out point continues to distribute to the other targets. The interrupted distribution automatically resumes from where it left off using the data from the repeater depot, rather than beginning all over again from the origin of the distribution data. By default, the Tivoli server pescado serves as the repeater distribution server for all the targets in the Tivoli management region. Pescado is also the source host and therefore also a repeater. The source host machine must be a repeater. Endpoint gateways are automatically configured to act as MDist 2 repeaters for distributing information to their endpoints. The NoonTide network includes endpoint gateways at odin, big, pearl, diamond, and lapis. NoonTide has configured the rainbow and dollar gateways to serve as additional MDist 2 repeaters. The network also includes electron, a standalone repeater with the MDist 2 function. The following diagram shows NoonTide s repeater hierarchy. The arrows represent the distribution flow. The distribution flow would be different if the source host were not located on the pescado Tivoli server but on a separate managed node. In this case, the distribution flow would originate at the source host. Chapter 11. Configuring a Network Topology 239

260 Creating a Repeater Hierarchy As in the case of the NoonTide network, one repeater site is often not enough to handle heavy network traffic and large software distributions. To determine the number of additional repeaters needed in any given environment, use the following guidelines: v If the network has slow network links, designate one managed node on each side of the network link to be a repeater with a local copy of the Tivoli binaries. v If the range (the managed node clients that receive data from the repeater site) of a repeater site contains too many clients in multiple subnets, add a repeater site for each subnet. In addition to determining the number of repeaters, you will also need to determine which of the MDist 2 repeaters are to be configured as permanent depots. Any repeater can be configured to be a depot. The placement of the repeater depots depends on where you need depot storage facilities in your Tivoli environment. It is recommended that you place depots on the other side of slow network links, like WANs, to enable quicker distributions. You must also consider the disk space required for the storage of distributions, especially if entire 240 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

261 Creating a Repeater Hierarchy distributions are stored after they complete. You need to calculate the size of the distribution and select a system with the required disk space. Before you begin a distribution, you can verify the repeater route or distribution path by using the wrpt command with the q argument. Refer to the Tivoli Management Framework Reference Manual for more information about the wrpt command syntax and arguments. The remainder of this chapter describes how to determine whether additional repeaters are needed, how to configure the parameters for each repeater, and how to configure a repeater as a depot. Refer to the Tivoli Management Framework: Planning for Deployment Guide to determine repeater and repeater depot environments and settings that will work best in your environment. In addition, the Tivoli Management Framework: Planning for Deployment Guide provides information about configuring endpoint gateways on managed nodes that serve endpoints. Configuring Repeater Sites As NoonTide s senior system administrator, you must complete each of the following steps to determine whether more repeater sites are necessary and, if so, how to configure them: 1. Determine which machines are defined as repeaters by typing the wrpt command from the command line of any managed node in the Tivoli management region. For example, when you first install Tivoli Management Framework on the pescado server, wrpt gives the following output: pescado [1] wd [] After you configure NoonTide s environment, run wrpt to list the default repeater on pescado, all endpoint gateways, and each managed node that is configured with a repeater. 2. List the machines in the range of the pescado repeater. Enter the following odadmin command from the command line of any managed node in the Tivoli management region to list the clients of the pescado repeater: odadmin odlist The output of this command is as follows: Region Disp Flags Port IP address Hostname(s) ct pescado,pescado.noontide.com 2 ct odin,odin.noontide.com 3 ct rainbow,rainbow.noontide.com 4 ct dollar,dollar.noontide.com 5 ct electron,electron.noontide.com 6 ct oak,oak.noontide.com 7 ct big,big.noontide.com 8 ct pearl,pearl.noontide.com 9 ct diamond,diamond.noontide.com 10 ct lapis,lapis.noontide.com 11 ct alloy, alloy.noontide.com Chapter 11. Configuring a Network Topology 241

262 Configuring Repeater Sites This list contains the names and IP addresses of managed nodes in each subnet shown in Network Architecture on page 237. Endpoints are not listed because they do not have the full Tivoli Management Framework (oservs). Endpoints rely on managed nodes for communication with the Tivoli server. 3. Create a repeater site on all managed nodes that serve as standalone repeaters in the repeater hierarchy. Endpoint gateways are automatically configured as repeater points for their client endpoints. To create a standalone repeater, use the wrpt command as follows: wrpt n repeater_name range=value In the NoonTide environment, enter the following command to make electron a standalone repeater that serves the pearl, diamond, and lapis gateway repeaters: wrpt n electron range=8-10 Refer to the Tivoli Management Framework: User s Guide for more information about creating a standalone repeater. 4. Use the wrpt command to verify that repeater sites are configured correctly. The output for NoonTide s configuration follows: pescado [1] -wd- [] odin [2] --- [] rainbow [3]] --- [] dollar [4]] --- [] electron [5] --- [8, 9, 10] oak [6] --- [] big [7] --- [] pearl [8] --- [] diamond [9] --- [] lapis [10] --- [] alloy [11] --- [] The electron repeater lists the host numbers of the machines it serves as their range. 5. If your network supports multicast, use the wmcast command to set repeater properties for MDist 2 multicast distributions. Refer to the Tivoli Management Framework: Reference Manual for more information about the wmcast command. In NoonTide s environment, pescado distributes software package A to its endpoint clients, which are managed by the rainbow, odin, dollar, oak, big, and electron gateways. The electron repeater distributes software package A to the pearl, diamond, and lapis gateways. Finally, pearl, diamond, and lapis distribute the software package to their endpoints. Each repeater and endpoint gateway distributes software package A in parallel to its endpoint clients. Refer to the Tivoli Management Framework: Reference Manual for more information about the wrpt and odadmin commands. Setting Repeater Parameters Now that you have created standalone repeater and endpoint gateway repeater sites for NoonTide s network, you must configure each of them to efficiently handle software distributions. Use the wmdist command to configure MDist 2 repeater parameters and manage distributions for both standalone repeaters and gateway repeaters. Refer to the Tivoli Management Framework: Reference Manual for more information about the syntax and arguments of the wmdist command. 242 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

263 Setting Repeater Parameters You configure each repeater and endpoint gateway in the NoonTide network in accordance with the amount of available memory, disk space, and network bandwidth, and the number and bandwidth capacity of the repeater s targets. The following procedure configures the electron (a Windows NT machine) and pescado (a Solaris machine) repeaters by performing the following steps: 1. Step 1: List the Current Settings of the Repeaters Parameters. 2. Step 2: Determine the Disk Space Requirements of the Applications to be Distributed on page Step 3: Check that the Electron and Pescado Sites Have the Required Disk Space and Memory on page Step 4: Set Electron s Repeater Parameters on page Step 5: Set Pescado s Repeater Parameters on page Step 6: Verify that the Repeater Parameters are Set Correctly on page Step 7: Restart the Repeater on page 249. Step 1: List the Current Settings of the Repeaters Parameters Enter the following wmdist command: wmdist -s electron wmdist -s pescado The following is the default output of this command for the electron repeater. The default output for the pescado repeater is the same, except that the default repeater directory for a UNIX repeater is /var/tmp/. repeater_id: rpt_dir: $DBDIR/tmp/ permanent_storage: TRUE max_sessions_high: 5 max_sessions_medium: 10 max_sessions_low: 40 disk_max: 500 (MB) mem_max: 64 (MB) send_timeout: 300 (secs) execute_timeout: 600 (secs) notify_interval: 30 (mins) conn_retry_interval: 900 (secs) retry_ep_cutoff: 7200 (secs) net_load: 500 (KB/sec) packet_size: 16 (KB) target_netload: 0 (KB/sec) debug_level: 3 repeater_multicast: FALSE endpoint_multicast: FALSE default_multicast: FALSE slow_link: FALSE where: repeater_id rpt_dir=pathname Specifies the object ID of the repeater. Specifies the parent directory used to hold the depot directory and the states directory. The depot directory contains all the segments stored in the database and must have enough free space to hold the value of disk_max. The states directory contains the database that holds the persistent state of the repeater queue. Chapter 11. Configuring a Network Topology 243

264 Setting Repeater Parameters permanent_storage=truefalse Configures the repeater to be a depot. If set to TRUE, the depot retains segments marked for permanent storage after the distribution finishes. If set to FALSE, the segments are deleted from the depot after the repeater finishes sending the distribution to all its targets. max_sessions_high=number Specifies the maximum number of concurrent connections a repeater opens for high-priority distributions. These connections are shared among all active distributions. If the repeater runs out of high-priority connections, it tries to use a medium-priority connection. Note: If the new value is greater than the old value, changes are not effective until you restart the repeater. max_sessions_medium=number Specifies the maximum number of concurrent connections a repeater opens for medium-priority distributions. These connections are shared among all active distributions. If the repeater runs out of medium-priority connections, it tries to use a low-priority connection. max_sessions_low=number disk_max=max_size_mb mem_max=max_size_mb Note: If the new value is greater than the old value, changes are not effective until you restart the repeater. Specifies the maximum number of concurrent connections a repeater opens for low-priority distributions. This number must be one or greater. These connections are shared among all active distributions. If the repeater runs out of low-priority connections, it waits for an open connection to complete before opening additional connections. Note: If the new value is greater than the old value, changes are not effective until you restart the repeater. Specifies the amount of disk space allocated to the repeater depot. Units are in megabytes (MB). If the disk_max number equals zero, no limit is enforced. This number should not exceed the size of the disk. Every distribution flowing through a repeater is stored at least temporarily in the depot. The depot must be large enough to hold the largest distribution that you expect to distribute. Note: If the new value is greater than the old value, changes are not effective until you restart the repeater. Specifies the amount of memory (in MB) that are 244 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

265 Setting Repeater Parameters send_timeout=seconds execute_timeout=seconds notify_interval=minutes conn_retry_interval=seconds retry_ep_cutoff=seconds net_load=kb_per_second packet_size=number_kb used to buffer data being sent to targets. This improves performance by reducing the number of disk accesses to the depot. The memory is shared among all active distributions. Note: If the new value is greater than the old value, changes are not effective until you restart the repeater. Specifies the timeout (in seconds) used to detect a network or target failure while sending data. A target is allowed the number of seconds specified by the send_timeout option to receive each packet on the network. If a timeout occurs, the distribution remains in the repeater queue and a retry occurs in conn_retry_interval seconds. See Setting Timeout Values for a Distribution on page 307 for more information about how Software Distribution sets timeout values for a distribution. Specifies the amount of time (in seconds) an endpoint method has to return results after it has received all that data from a distribution data. Some applications may be running scripts after receiving data but before returning results to the repeater. Specifies the frequency (in minutes) of status reporting. When the notify_interval has elapsed or the distribution has completed on all targets, the results are flushed. The results are sent to the application using MDist 2 and updated in the MDist 2 database. Specifies the frequency (in seconds) that unavailable or interrupted targets are retried. Specifies the amount of time (in seconds) to continue retrying an unavailable or interrupted endpoint. Unavailable or interrupted repeaters are retried until the distribution deadline has been reached. Specifies the maximum amount of network bandwidth (in kilobytes per second) that the repeater is allowed to use. If slow_link is set to TRUE, the network bandwidth is measured in bytes per second. This allocation is shared among all active distributions. This option is used with target_netload. Specifies the number of kilobytes written to the network during each send request. If slow_link is set to TRUE, specifies the number of bytes written to the network during each send request. target_netload=kb_per_seconds Specifies the maximum amount of network bandwidth (in kilobytes per second) that can be sent to an individual target. If slow_link is set to TRUE, the network bandwidth is measured in Chapter 11. Configuring a Network Topology 245

266 Setting Repeater Parameters debug_level=number bytes per second. The default value of 0 disables this check. This command is used with net_load. Controls which messages are written to log files for the managed node repeater ($DBDIR/rpt2log). Logging for the gateway repeater is controlled using the wgateway debug_level command. repeater_multicast=truefalse When an application sends a multicast distribution, indicates whether the gateway uses multicast when distributing packages to other repeaters. Specify TRUE to use multicast. Specify FALSE to use unicast. The default is FALSE. Note: To set this keyword to TRUE, Java 1.3 for Tivoli and Tivoli Java Client Framework must be installed on this repeater. endpoint_multicast=truefalse When an application sends a multicast distribution, indicates whether the gateway uses multicast when distributing packages to its endpoints. Specify TRUE to use multicast. Specify FALSE to disable multicast and use unicast. A gateway can only multicast to its own endpoints. This keyword applies to gateway repeaters only. The default is FALSE. Notes: 1. The keyword can be used in combination with the C option of the wmdist command. 2. To set this keyword to TRUE, Java 1.3 for Tivoli and Tivoli Java Client Framework must be installed on this repeater. default_multicast=truefalse Specifies whether multicast is the default mode for all MDist 2 distributions. This distribution mode can be overridden by Software Distribution. Specify TRUE to enable. Specify FALSE to not enable. The default is false. slow_link=truefalse Specifies whether the distribution is over links with bandwidths less than one kilobyte. If TRUE, the net_load, packet_size, and target_netload values are measured in bytes instead of kilobytes. The default is FALSE. Some of these parameters can be overwritten for a particular distribution by specifying them in the distribution options at distribution time. For more information about repeater parameters, refer to the Tivoli Management Framework User s Guide and the Tivoli Management Framework Reference Manual. For information about distribution options, see Defining Distribution Settings on page 205. Step 2: Determine the Disk Space Requirements of the Applications to be Distributed Determine the disk space requirements of the applications to be distributed by referring to the installation guides for the applications. 246 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

267 Setting Repeater Parameters In this scenario assume that the installation media and some of the application files of the software to be distributed are distributed in the software package. The installation media requires 180 MB and the application requires about 25 MB. Thus, assume the largest software package will be 210 MB, considering the overhead of the configuration programs and the software package. Step 3: Check that the Electron and Pescado Sites Have the Required Disk Space and Memory Check that the electron and pescado sites have the required disk space in the directory represented by rpt_dir and the required memory for processing. Note: You must be logged in as Administrator to perform the steps to determine disk space and memory allocations. 1. Check for available disk space on electron (a Windows NT machine) by clicking Start->Programs->Administrative Tools->Disk Administrator. The C:\ drive has 388 MB of free disk space and the D:\ drive has 1484 MB of free disk space. 2. Check for available memory on electron by clicking Start->Programs- >Administrative Tools->Windows NT Diagnostics. 3. Select the Memory tab to display the following window: Chapter 11. Configuring a Network Topology 247

268 Setting Repeater Parameters About 148 MB (152,016) of memory are available. 4. Check for available memory on pescado (a Solaris machine), and locate a file system with free space that can be used to buffer distributions. (Commands used for finding available memory vary by operating system.) To check the amount of RAM installed on the machine, enter the prtconf grep Memory size command. Note that this command returns the total amount of memory installed, not just the free memory. The output is: Memory size: 512 Megabytes Finally, to check the disk partitions for available space, use the df k command. The output is: Filesystem /dev/vx/dsk/rootvol /dev/vx/dsk/usr /proc fd /dev/vx/dsk/rootdg/vol06 swap kbytes used avail capacity 82% 82% 0 0% 66% 11% Mounted on / / /usr /proc /var /tmp Because the /tmp file system uses a portion of swap space it is not a good choice to use as a repeater. The /var file system is the best choice for this system because it has the largest free space and it does not use swap space. Step 4: Set Electron s Repeater Parameters The send_timeout parameter is not reconfigured in this example. The slowest system on the network is a Pentium with 32 MB of RAM. The default send_timeout is 300 seconds, which is sufficient for this system s configuration. 1. Set the mem_max and disk_max parameters. For performance reasons, do not set mem_max higher than the available RAM. The memory cache reduces disk access to improve performance. If mem_max is larger than available memory, it causes the data to be swapped to disk and the performance gain will be lost. To avoid the possibility of a failed distribution, set the disk_max parameter to the majority of the hard drive space available on the repeater. For example, the electron repeater has 148 MB of available physical memory and 1.5 GB of free space on the D: partition of its hard drive. The following command sets the mem_max parameter to 100 (so as not to reserve all the available memory for the repeater cache) and the disk_max parameter to wmdist -s electron mem_max=100 disk_max= Set the rpt_dir parameter to be on a partition with at least the specified disk_max value of free space. In this case, specify the repeater main directory for the electron repeater on the D: partition, under D:\tivoli\rptdir: wmdist -s electron rpt_dir=d:\tivoli\rptdir You can use a backslash (\) in the directory path if you enter this command from electron. If you enter this command from a UNIX managed node, you must qualify the backslash with another backslash or use a forward slash (/) as follows: D:/tivoli/rptdir Step 5: Set Pescado s Repeater Parameters Set pescado s repeater parameters. 1. Pescado s physical memory is 512 MB. If pescado is used for tasks in addition to acting as a repeater, set this parameter to use a smaller portion of the resources. wmdist -s pescado mem_max= IBM Tivoli Configuration Manager: User s Guide for Software Distribution

269 Setting Repeater Parameters 2. Set the rpt_dir and disk_max parameters. The /var file system has available disk space and files should be buffered in the /var/tmp directory. Of the 297 MB available on /var, the repeater will be limited to use 230 MB to ensure that it does not use all of the file system s space. Set the parameters as follows: wmdist -s pescado rpt_dir=/var/tmp disk_max=230 Note: For network connections with different bandwidths, the repeater parameter values must be scaled proportionally. Step 6: Verify that the Repeater Parameters are Set Correctly Verify that the repeater parameters are set correctly using the wmdist s command for each repeater. The output for the electron repeater is as follows: repeater_id: rpt_dir: D:\tivoli\rptdir permanent_storage: TRUE max_sessions_high: 5 max_sessions_medium: 10 max_sessions_low: 40 disk_max: 1000 (MB) mem_max: 100 (MB) send_timeout: 300 (secs) execute_timeout: 600 (secs) notify_interval: 30 (mins) conn_retry_interval: 900 (sec) retry_ep_cutoff: 7200 (secs) net_load: 500 (KB/sec) packet_size: 16 (KB) target_netload: 0 (KB/sec) debug_level: 3 repeater_multicast: FALSE endpoint_multicast: FALSE default_multicast: FALSE slow_link: FALSE The output for the pescado repeater is: repeater_id: rpt_dir: /var/tmp/ permanent_storage: TRUE max_sessions_high: 5 max_sessions_medium: 10 max_sessions_low: 40 disk_max: 230 (MB) mem_max: 128 (MB) send_timeout: 300 (secs) execute_timeout: 600 (secs) notify_interval: 30 (mins) conn_retry_interval: 900 (sec) retry_ep_cutoff: 7200 (secs) net_load: 500 (KB/sec) packet_size: 16 (KB) target_netload: 0 (KB/sec) debug_level: 3 repeater_multicast: FALSE endpoint_multicast: FALSE default_multicast: FALSE slow_link: FALSE Step 7: Restart the Repeater To stop and restart a specific gateway and its repeater, enter the following command: wgateway gateway_name restart Chapter 11. Configuring a Network Topology 249

270 Setting Repeater Parameters Standalone repeaters restart after 20 minutes of inactivity. You can wait until the repeater restarts or enter the following command: odadmin reexec dispatcher_number How Software Distribution Works Software package distributions are enabled by several methods. The following sections contain several typical distribution scenarios that demonstrate how these methods and machine types interact depending on the number and types of endpoints. The following diagram illustrates how methods are invoked between systems in a Tivoli environment: Tivoli Server Source host 4 5 M1 w/ repeater 6 Ep1 Ep2 Ep3 Ep4 1. CM operation passes target list to cm_execute_src on source host (SH) 2. cm_execute_src initiates the MDist 2 service on SH 3. MDist 2 retrieves routing information from endpoint manager on the Tivoli server 4. While MDist 2 invokes send on source host to distribute to source's endpoints, the source's send invokes cm_operation_ep2 on Ep1 and Ep2 and starts distribution 5. MDist 2 passes routing information and distribution files to the send method on M1 6. MDist2 send method on M1 invokes cm_operation_ep2 on Ep3 and Ep4 and starts distribution 7. When all the results have been collected on the gateway or the notify_interval setting has expired, the results are bundled and passed back by the MDist2 engine to the application callback method, called the MDist2_result method. Figure 1. MDist 2 and change management operations The distribution of a software package to an endpoint occurs in steps. When a software package is distributed, the method associated with the change management operation submitted on the Tivoli management region server performs the following steps: 1. A change management (CM) operation is submitted that runs on the Tivoli management region server. Each operation corresponds to a change management operation method. If the default operation is submitted using the Tivoli desktop or the command line, the default_push method is called. Note: The distribution process for the data moving command differs in some details from the standard change management distribution method. An explanation of this process is given in Scenario 5: Performing Data Moving Operations on page IBM Tivoli Configuration Manager: User s Guide for Software Distribution

271 How Software Distribution Works The change management operation method passes information about the software package and the list of endpoints to the cm_execute_src method on the source host machine. 2. A list of endpoints is gathered for the software package operation. 3. The sp_val_operation validation policy method runs, which validates the operation in terms of endpoint subscribers and roles. 4. The software package status is validated in the database (CM_STATUS). 5. The Software Distribution method, cm_execute_src, runs on the source host and calls the distribution manager method, registerdistribution, on the Tivoli management region server. By default, the Software Distribution source host is defined as repeater. 6. The source host contacts the MDist 2 service with the list of endpoints. 7. The distribution manager calls the tst_route method in the repeater manager to retrieve the route for that distribution. 8. The distribution manager creates entries in the MDist 2 database for each of the distribution s target systems. 9. The registerdistribution method returns the distribution s route and ID number to the source host. 10. Once the distribution ID is returned, Software Distribution does the following: a. Prepares the data to be sent in software package block format (built format). If it was originally stored as a different format, the build occurs at submission time. b. Updates the SD_INST table with a temporary changing status. For example, running an install operation for the first time, the temporary status is reported as (- - - C), with C in the final position. Refer to the Reference Manual for Software Distribution for more information about software package states. 11. Software Distribution calls the MDist 2 distribute method to distribute the data stream. In general, if there are other repeaters in the route path, the send method is used. When the endpoint is reached, the MDist 2 distribute method then calls the Software Distribution cm_operation_ep2 method to run on each endpoint. Each repeater then simultaneously: a. Distributes the data stream to all endpoints in its range, calling the cm_operation_ep2 method on each endpoint. b. Calls the send method on any sub-repeater. If the sub-repeater includes an endpoint of the distribution in its repeater range, the data stream and list of endpoints is passed on to it. 12. The cm_operation_ep2 method runs on each endpoint system and is responsible for receiving and installing the software package. When the cm_operation_ep2 method finishes receiving and running the appropriate CM operation on the software package (install, remove, and so on), it returns the completion status (failed or successful operation) to the method that initially called it. 13. The frequency with which the repeater packages and returns results is determined by the setting of the notify_interval attribute, which specifies how often (in minutes) results should be returned. When all the results have been collected on the gateway or the notify_interval setting has expired, the results are bundled and passed back by the MDist 2 engine to the application callback method, called the mdist2_result method. Note: Reducing the value of the notify_interval attribute increases the frequency with which reports are returned. Reports use available MDist Chapter 11. Configuring a Network Topology 251

272 How Software Distribution Works 2 connections on the server which frequently are occupied. To improve performance, adjust the number of connections available in accordance with the notify_interval setting. 14. The mdist2_result method converts the data from MDist 2 to be processed by the notification manager. This method is also responsible for running the notification manager by calling the run_nm method which informs available listeners (internal and external) of incoming results. The priority level set in the software package at time of distribution is also the priority with which listeners report information. Available internal listeners are responsible for the following activities: v Updating change management status tables v Sending events to the Tivoli Enterprise Console v Sending output to log files v Sending notices to notice groups v Sending to users The available external listener, the Activity Plan Manager, is also updated with information about the submitted operation. The temporary changing state in the SD_INST table is updated with the final completion status of the operation. Note: To optimize performance, ensure that only those listeners to which you want to send reports are enabled, otherwise, Software Distribution wastes resources connecting to them unnecessarily. To view a list of all the cm_execute_src and send methods called by the cm_execute_src method, enter the odstat c command during the distribution. This command tracks the activities on servers, gateways, repeaters, and the source host. It lists the CM operation method as running on the server and the cm_execute_src method as running on the source host. It lists the send method as running on the repeater. If you continually enter the odstat c command, you see each method disappear from the list as each process completes, until finally the cm_execute_src method completes. During a software package distribution, Software Distribution distributes software packages with communication services provided with Tivoli Management Framework. Distributions rely on communication established by the following two Tivoli Management Framework services: v Interobject Message (IOM) service, which provides a means of distributing large blocks of data between repeaters without involving oserv communications. The oserv is the main Tivoli Management Framework service that coordinates communications between all managed resources and gateways. v Multiplexed Distribution (MDist 2), which enables asynchronous distributions of large amounts of data to multiple endpoints in an enterprise. During a software package distribution to multiple endpoints, MDist 2 uses a store-and-forward mechanism to transmit the entire distribution before the next level of connections is opened. Once the distribution is passed along, the connection is closed. MDist 2 uses the wmdist command to configure repeaters. See the Tivoli Management Framework: Reference Manual for the usage and syntax of the wmdist command. 252 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

273 How Software Distribution Works Additional information about MDist 2 is available in the Tivoli Management Framework: Planning for Deployment Guide. Software Distribution Methods During a software package distribution, CM operation methods are initiated on the Tivoli management region server. How you choose to distribute the software package actually determines which of these methods is executed. One of the following methods serves as the master method of the software package distribution and defines all submethods: default_push This method is called if the software package is distributed using either the Profile Manager --> Distribute menu option on the Tivoli desktop or by dragging and dropping the software package icon onto the required subscriber. The default operation can also be set from the command line using the following command: wsetspat -o <default_cmop> -M <default_cmop_mode> Refer to the Reference Manual for Software Distribution for more information on the wsetspat command. CM operation This method is called if the software package is distributed using the appropriate command from the command line, or from the Tivoli desktop by right-clicking the appropriate profile, then clicking a CM operation. The change management commands that correspond to the methods are shown in the following table. Table 13. Software Distribution methods and corresponding operations and commands Method Operation Command install install winstsp reverse remove wremovsp accept accept waccptsp commit commit wcommtsp undo undo wundosp verify verify wversp load load wldsp unload unload wuldsp move_data send, retrieve, delete wspmvdata Software Distribution Scenarios This section describes the following typical distribution scenarios using Software Distribution: v Scenario 1: Distributing from a Tivoli Management Region Server through a Gateway on page 254 v Scenario 2: Distributing from a Source Host/Tivoli Management Region Server to a Repeater on page 255 v Scenario 3: Distributing from a Source Host through Repeater Depots on page 257 Chapter 11. Configuring a Network Topology 253

274 Software Distribution Methods v Scenario 4: Distributing from a Tivoli Management Region Server to a Mobile Endpoint Installing Images from a CD-ROM on page 259 v Scenario 5: Performing Data Moving Operations on page 260 Scenario 1: Distributing from a Tivoli Management Region Server through a Gateway In the simplest distribution scenario involving gateways and endpoints, the server and source host are the same machine and the endpoints are Ep1 and Ep2, both of which are assigned to an endpoint gateway GW1. One of the endpoints, Ep2, is unavailable at the moment of the distribution and the scenario explains how the notification manager updates information for endpoints on which the distribution has completed and for endpoints that are unavailable. Tivoli management region server / source host GW1 Ep1 Ep2 Figure 2. Distribution from Tivoli server through a gateway. If you distribute a software package to all endpoint target systems (Ep1, and Ep2), the CM operation method install starts the cm_execute_src method on the source host. The cm_execute_src method starts the distribute method that calls the send method to distribute to GW1. When a change management operation is submitted, the SD_INST table in the Inventory database is updated with the temporary change management status, which changes to a final, permanent state when the distribution ends. When the source host or repeater detects that the gateway is connected to the IOM channel, the host machine begins sending the software package data stream to the gateway, where the data is stored temporarily in a depot. This depot serves as a temporary area from which GW1 distributes the software package to the cm_operation_ep2 method on each of the target system. The gateway uses store-and-forward technology to begin data transfer from the depot to the endpoint. On the Ep1 endpoint, the lcfd daemon receives the distribution and starts the specific CM operation method that unpacks and installs the software package. After the distribution has completed, successfully or unsuccessfully, the cm_operation_ep2 method on the endpoint returns distribution status to the send method on the gateway. The gateway send method, in turn, returns final distribution status to the mdist2_result callback method only after each target system has returned its distribution status to its associated gateway. 254 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

275 Distributing from a Server through a Gateway During a distribution, the gateway is responsible for tracking method requests from the server and other managed nodes, and from its endpoints. The endpoint gateway also acts as a gateway for method invocation. All operations to or from an endpoint pass through an endpoint gateway: the gateway receives a distribution request, determines the endpoints, and downloads and executes the cm_operation_ep2 method on the endpoints to perform the requested Software Distribution operation. All the results are handled by the mdist2_result method running on the Tivoli management region server. The mdist2_result method converts the data from MDist 2 to be processed by the notification manager. It also returns the distribution results to the notification manager, which reroutes messages to several listeners, such as Tivoli Enterprise Console events, log files, notices, and notifications. When the gateway receives the distribution request for Ep1 and Ep2, it downloads and executes the cm_operation_ep2 method on the Ep1 endpoint. Because Ep2 is not logged in, the gateway determines that Ep2 cannot receive the distribution so it is set to UNAVAILABLE in the MDist 2 queue. When the gateway is unable to contact an endpoint, it checks to see if the distribution has Wake on LAN support enabled and attempts to start the system. If Ep2 has the Wake on LAN network adapter, a restart is automatically triggered on Ep2. The distribution continues and completes and Ep2 remains up and running after the distribution completes. If the gateway cannot connect to the endpoint and the Wake on LAN distribution option is not enabled, or the endpoint is not equipped with the network adapter, the distribution remains in waiting on the gateway. The same distribution is marked as successful (unsuccessful) for Ep1. In this case, it could be convenient to set the notify_interval parameter to control how often the server and Software Distribution should be notified about results. If the notify_interval is set to five minutes, the gateway will wait five minutes before it bundles all the results that are available and forwards them to the MDist 2 service. The MDist 2 service then updates the MDist 2 database and the control is passed back to Software Distribution which continues to work and update listeners. In this scenario, only the results related to Ep1, which has completed, are sent back to its gateway. To control the distribution and limit the number of connection attempts, you can also configure the deadline and conn_retry_interval parameters. Using the deadline, you can set a date on which the distribution expires. If the endpoint does not reconnect before this date, the distribution expires on the unavailable target. For example, if the deadline is 48 hours and the conn_retry_interval is set to 3600 seconds, at the end of the two days, the connection is attempted 48 times. In the SD_INST table, the final status for Ep1 is registered as IC (installed, committed), whereas, the temporary changing status for Ep2 is reset to its original status. Scenario 2: Distributing from a Source Host/Tivoli Management Region Server to a Repeater Figure 3 on page 256 illustrates the Tivoli management region server and the source host as separate machines. The gateways GW1, GW2, and GW3 are specified in the repeater range for R1. This scenario describes the distribution of a software package, SP^1.0, from the source host to Ep1, Ep2, and Ep3. It also describes the distribution to Ep5 and EP6 of the INSTALL_IMAGE^2.0 software package that retrieves the images referenced in the INSTALL_IMAGE^2.0 software package from a file server (Ep7) on the same LAN as endpoints Ep5 and Ep6 that are located in a different branch and use a slow link. Chapter 11. Configuring a Network Topology 255

276 Distributing from a Source Host to a Repeater Tivoli management region server Source host R1 GW1 GW2 GW3 Ep1 Ep2 Ep3 Ep4 Ep5 Ep6 Ep7 / file server Figure 3. Distributing from a host through a repeater Distributing the SP^1.0 Software Package to GW1 and GW2 The CM operation method install starts the cm_execute_src method on the source host. The cm_execute_src method starts the distribute method that calls the send method to distribute SP^1.0 to R1. From R1, the send method distributes SP^1.0 to GW1 and GW2. GW1 and GW2 distribute SP^1.0 to the cm_op_ep2 method on each target system. When the send method on R1 pulls the software package, the software package is placed in the depot on R1. R1 is configured as a repeater with the wrpt command and the repeater parameters are set using the wmdist command. See Configuring Repeater Sites on page 241 and Setting Repeater Parameters on page 242 for more information. This repeater depot serves as a cache if the endpoints cannot asynchronously receive the software package. The repeater receives the entire distribution before sending it on to the next level. After R1 receives the software package, it distributes the software package to GW1 and GW2, which in turn distribute to Ep1, Ep2, Ep3, and Ep4. MDist 2 uses store-and-forward technology to move the distribution between repeaters and gateways. Distributing from a File Server This network topology includes a slow link between R1 and GW3. In this case, it might be convenient to separate the data from the distribution itself and load the data on a dedicated file server located in the same branch as the target endpoints. For this scenario, the file server is Ep7. Note: When you send a distribution with the From Fileserver option selected, consider increasing the distribution send_timeout value. After this timeout value is exceeded, you can no longer pause or cancel the distribution. The Administrator needs to distribute the INSTALL_IMAGE^2.0 software package block, which is 150 Mb, to Ep5 and Ep6. Before sending the distribution, the 256 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

277 Distributing from a Source Host to a Repeater Administrator must create an installable image of the software package block using either the wldsp -l depot_image_dir=target_spb_path or the wdepot image command. Refer to the Reference Manual for Software Distribution for the syntax and usage of the wldsp command, and refer to the Tivoli Management Framework: Reference Manual for the syntax and usage of the wdepot command. These commands create two files with the extensions.itc/.toc and.dat. These two files contain the data to be used during the distribution operation (cm_operation_ep2). These files are loaded or copied to the file server and accessed by endpoints, Ep5 and Ep6. To access the Ep7 file server, the Administrator needs to configure the remote.dir file on the Ep5 and Ep6 endpoints. The remote.dir text file must be copied under $LCF_DATDIR on each endpoint. This file contains a list of available file servers, one per line. The Administrator can use Software Distribution to distribute the remote.dir file to the endpoints in a software package. At this point, the Administrator submits a dataless install operation, specifying the option from_fileserver. Note: For information about how you can customize the default setting for the from_fileserver option using the wswdmgr command, see Customizing the GUI Settings on page 195. When the endpoint lcfd receives the distribution, it looks for the content of the distribution in the specified shared directory of the first file server listed in the remote.dir file. If it does not find the file, it looks for it on the next file server listed in the remote.dir file. In this scenario, the file server listed in remote.dir is a directory on Ep7. The operation fails if the images (.itc/.toc and.dat files) are not available on the Ep7 file sever. Refer to the Tivoli Management Framework: User s Guide for more information about the remote.dir file and installations from file servers. Scenario 3: Distributing from a Source Host through Repeater Depots A repeater depot is a data repository that acts as an intermediate fan-out point and enables you to temporarily or permanently store distribution data (software packages). Storing data in depots reduces network traffic for frequently distributed datasets. You should use depots at the end of slow, unreliable network links. However, do not use depots for extremely large distributions, or for data that changes frequently. Repeater depots are able to store an entire distribution and resume a distribution that has been halted by unavailable nodes or network failures. Instead of re-sending the entire distribution from the source host, only those undelivered files from the last repeater checkpoint are sent. Data, or distribution segments, can be temporarily or permanently stored in the depot depending on the repeater settings. However, if the disposable attribute is set when installing a software package, and the repeater depots have been configured to accept temporary distributions, the distribution data is removed once the distribution has finished (either all endpoints have completed or the distribution has exceeded its life span). If a repeater depot is configured to accept temporary distributions, and the disposable attribute is not set, the distribution data is not removed. Each repeater in the distribution hierarchy is a potential depot where software packages can be stored. When you have configured a repeater as a repeater depot, you can submit distributions with repeater depots as the targets. You can use the wldsp command to load a software package in a repeater depot or the wuldsp Chapter 11. Configuring a Network Topology 257

278 Distributing from a Source Host through Repeater Depots command to unload a software package from a repeater depot. Refer to the Reference Manual for Software Distribution for more information about these commands. You can also perform these operations from the Tivoli desktop. See Loading and Unloading Software Packages on page 195 for more information. You can specify the from_depot attribute of the winstsp command, to request that a software package be installed directly from the depot connected to the endpoint, rather than from the source host. The depot must be previously loaded with the software package or the install operation fails. Note: If you specify from_depot together with roam_endpoints, the software package must be loaded on all depots to which the endpoint can roam to avoid an install failure. For information about how you can customize the default setting for the from depot option using the wswdmgr command, see Customizing the GUI Settings on page 195 The following examples describe how to configure the R1 repeater as a repeater depot, load a software package in the depot, install a software package from the depot, list the entries in the depot, and remove a software package from the depot. 1. Configure the R1 repeater to be a repeater depot. The repeater needs enough space for all of the active distributions, plus space for all distributions that will be permanently stored on the repeater depot. To configure the R1 repeater to be a repeater depot, use the wmdist command and set the permanent_storage parameter to true as follows: wmdist -s R1 permanent_storage=true 2. Load the mypackage software package block in the R1 repeater depot. To load the software package block, use the wldsp command as follows: R1 If the software package block contains nested software packages, use the wldsp command to load the primary software package. This automatically loads the nested software packages that it contains. In this case, a multi-segment distribution is submitted to MDist 2 where each segment contains a different software package block. 3. Check the content of your depot and information related to each entry, by submitting the wdepot command with the -l argument as follows: wdepot R1 list -l This command returns the ID, version, size, percentage completed, and last modification time for each entry on the depot. 4. Perform an installation software package block from the R1 repeater depot using the winstsp command as follows: winstsp In this case, the distribution skips the source host and finds the data on the depot. If you have configured the MDist 2 database, you can use the wmdist command together with the e, l, and i arguments to monitor and control the distribution. 5. To remove a particular software package block from the R1 depot, use the wuldsp command as follows: R1 The wuldsp command also updates the Inventory database with the change. 258 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

279 Distributing from a Source Host through Repeater Depots You can also delete all the entries in the depot using the wdepot command with the purge argument as follows: wdepot R1 purge You are prompted for confirmation before the depot is purged. The Inventory database is not updated with the change. Scenario 4: Distributing from a Tivoli Management Region Server to a Mobile Endpoint Installing Images from a CD-ROM This scenario describes the distribution of different applications (software package blocks) to endpoint Ep2 configured as a mobile endpoint that is not connected to the network at the moment of the distribution. Tivoli management region server R1 GW1 Ep1 mobile Ep2 mobile Figure 4. Distribution from Tivoli server to mobile endpoints. The software package contains instructions to install the applications whose images are located on a CD. The Administrator must prepare the software package block installable images using either the wldsp -l depot_image_dir=target_spb_path or the wdepot image command. Refer to the Reference Manual for Software Distribution for the syntax and usage of the wldsp command, and refer to the Tivoli Management Framework: Reference Manual for the syntax and usage of the wdepot command. These commands create two files with the extensions.itc/.toc and.dat. These two files contain the data to be used during the distribution operation and must be copied to the CDs. The Administrator provides each mobile user with a CD containing the images of the applications. The Administrator specifies the mobile endpoint settings, including a mandatory date before which the installation must be performed, and then submits a dataless install operation. If the mobile user does not perform the installation by the mandatory date, the software package is automatically downloaded into the local depot, immediately after the next mobile log on. Chapter 11. Configuring a Network Topology 259

280 Distributing from a Server to a Mobile Endpoint When the distribution reaches the gateway, a check is performed to determine if the target is configured as a mobile endpoint. If the endpoint is not connected, the distribution is paused on the gateway until the deadline of the distribution expires, or the distribution is resumed by the user through the Mobile Computing console. Refer to the Tivoli Management Framework: User s Guide for more information about mobile computing. When the mobile user connects, the related gateway inspects the queue and discovers that there is a distribution paused for this mobile user. The mobile user is notified of the distribution in the queue. To minimize the dial-up connection time, the mobile user can decide to download the software package, disconnect, and submit the install command in disconnected mode at a later time. The download begins, and the mobile user is requested to insert the CD because the data referenced in the software package is located on the mobile endpoint CD-ROM. The distributions results are collected in a local mobile depot directory and forwarded to Software Distribution the next time the mobile endpoint makes a network connection. The operation fails if the images (.itc/toc and.dat) are not available on the CD. Scenario 5: Performing Data Moving Operations The Data Moving Service provides for the following Software Distribution operations: v Sending, retrieving, and deleting files on source host and endpoint machines. Any type of file can be sent, retrieved or deleted using the data moving command. v Sending files from a source endpoint to a number of target endpoints. v Send, retrieving or deleting more than one file by using wildcards or matching indicators, in addition to Software Distribution standard variables. For more information on Software Distribution variables, refer to the Reference Manual for Software Distribution. This scenario describes a typical situation where database information is collected from the enterprise branch offices (endpoints): a pre-processing script is run on the endpoints Ep1, Ep2, Ep3, Ep4, Ep5, and Ep6 to extract information from the local database application into a file named database.*.db on each endpoint. The files are then retrieved from the source host, where a post-processing script extracts the relevant data. 260 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

281 Performing Data Moving Operations Tivoli management region server Source host R1 GW1 GW2 GW3 Ep1 Ep2 Ep3 Ep4 Ep5 Ep6 Figure 5. Data moving retrieve operation The data moving command is submitted to the Tivoli management region server from the Tivoli CLI using the wspmvdata command, from the Tivoli desktop or from the Activity Planner. The cm_execute_src method runs on the source host and a check is performed to verify that the path to which the file is to be retrieved is valid. After the check succeeds, a.spb file is created containing the information to be retrieved. The distribution manager method, registerdistribution, is called and the.spb file is then sent and installed on each endpoint calling the cm_operation_ep2 method on the endpoint. The.spb file is used to perform the pre-processing script that collects the required data, and saves them in the database.*.db files. The database.*.db files are built into.spb files, and temporarily stored on the endpoints. Each endpoint must have sufficient space to hold bulk data for the retrieve operation. The new.spb packages are then returned to the source host calling the dm_mdist2_result method, and stored in the destination directory. A separate destination subdirectory is created on the source host for each endpoint, so that files with the same name retrieved from different endpoints are not overwritten. A post processing script is now run on the source host to extract the relevant data from the database.*.db files. The results of the operation are bundled and passed back to the mdist2_result method. Chapter 11. Configuring a Network Topology 261

282 Performing Data Moving Operations 262 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

283 Chapter 12. Integrating the Tivoli Enterprise Console Software Distribution Tivoli Enterprise Console Integration enables Software Distribution to send events to the Tivoli Enterprise Console event server (event server) when a Software Distribution operation is performed. In the Tivoli environment, an event is classified as any significant change in the state of a system resource, network resource, or network application. After the Tivoli Enterprise Console integration is enabled, Software Distribution automatically generates events based on its operations such as successful or failed distributions or change management operations, and sends these events to the event server. This provides a means for centrally collecting Software Distribution events and triggering actions that can be handled the same way as events from other sources or even be correlated with other events. This chapter provides a description of the Software Distribution event configuration file and event classes. You must be familiar with the Tivoli Enterprise Console application and its manuals, specifically the IBM Tivoli Enterprise Console: User s Guide and the IBM Tivoli Enterprise Console: Adapters Guide. These materials provide conceptual and instructional information about events, event adapters, and classes. Enabling the Tivoli Enterprise Console To use Tivoli Enterprise Console integration, perform the following steps: v Install Software Distribution, Version v Install versions or later of the Tivoli Enterprise Console, and the Tivoli Enterprise Console server in your Tivoli management region. v Ensure the integration is enabled. The integration is enabled by default, otherwise, use the wswdmgr command to enable the integration. v Register the Software Distribution event classes on the Tivoli Enterprise Console server. v Configure the event server, if necessary. v Create the Software Distribution Console. Refer to the IBM Tivoli Enterprise Console: User s Guide for more information about installing and using the event server and console. Steps to Enable the Integration The following procedure demonstrates the steps required to enable Software Distribution to send events to the Tivoli Enterprise Console server in an environment with several Tivoli management region servers and Tivoli Enterprise Console event servers, but where the Software Distribution Server does not reside on the same Tivoli management region server as the Tivoli Enterprise Console server. 1. Before connecting the Tivoli management regions, run the wregister command to register the resource for the event server (EventServer) on all the Software Distribution servers from which you want events sent and where you want the EventServer class visible. Run the command as follows: wregister -i -v EventServer Copyright IBM Corp. 2002,

284 Integrating the Tivoli Enterprise Console Refer to IBM Tivoli Enterprise Console: Installation Guide for more information about registering the resource and the Tivoli Management Framework: Reference Manual for more information about the wregister command. 2. After you install Software Distribution, the Tivoli Enterprise Console integration is enabled by default. If it is not enabled, use the wswdmgr command. Run the command on the Software Distribution server as follows: wswdmgr [-s [key={true false}] where key is: is_swd_tec_enabled If this key is set to true, Software Distribution events are sent to the Tivoli Enterprise Console. The default value is true. 3. Software Distribution event classes are defined in the tecad_sdnew.baroc file which is found in the $BINDIR/TME/SWDIS/SPO directory on the Software Distribution server. See Software Distribution Classes on page 268 for more information about Software Distribution event classes. To set a rule base to manage events and to install the Software Distribution event classes on the event server, the swdistecsrvr_inst.sh script file is provided and is located in the $BINDIR/TME/SWDIS/SCRIPTS directory. Copy the following files from the Software Distribution server to a temporary directory (for this example, /tmp) on the Tivoli Enterprise Console server: $BINDIR/TME/SWDIS/SCRIPT/swdistecsrvr_inst.sh $BINDIR/TME/SWDIS/SPO/tecad_sdnew.baroc 4. Run the swdistecsrvr_inst.sh script as follows, specifying the path (/tmp) of the tecad_sdnew.baroc file using the -w option: sh /tmp/swdistecsrvr_inst.sh -b <your_rule> -s aix270 -u root -p <your_password> -t <your_console> -w /tmp/tecad_sdnew.baroc 5. Specify the event server where Software Distribution events should be sent. The event server is specified by defining the SeverLocation key in the tecad_sd.conf file located in the following path: $BINDIR/TME/SWDIS/SPO/tecad_sd.conf The tecad_sd.conf file is described in greater detail in the The tecad_sd.conf File. 6. Complete the process by creating the Software Distribution console. See Creating the Software Distribution Console on page 267. The tecad_sd.conf File The tecad_sd.conf configuration file for the Software Distribution Tivoli Enterprise Console Integration component initially has the following default entries: ServerLocation=@EventServer ConnectionMode=connection_oriented RetryInterval=1 NO_UTF8_CONVERSION=NO ServerPort=0 The keywords are as follows: ServerLocation Specifies the or a fully qualified identifier if multiple event servers are running in an interconnected Tivoli management region environment. You must set the value of this field after installing 264 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

285 Integrating the Tivoli Enterprise Console Software Distribution. Events are sent to the event server specified. To obtain the event server identifier, enter the following command from the command line: wlookup -ar EventServer The following is an example of the output of the command: EventServer#red-region #Tec::Server# EventServer#blue-region #Tec::Server# EventServer#yellow-region #Tec::Server# One of the event servers in this output example assumes the value of ServerLocation as follows: Refer to the Tivoli Management Framework: Reference Manual for more information about the wlookup command. ConnectionMode Specifies the connection mode to use to connect to the event server. Valid values are connection_oriented (or its abbreviations CO and co) and connection_less. The default value is connection_oriented, which specifies that the connection with the event server is maintained for all events sent. A new connection is established only if the initial connection is lost. When connection_less is specified or used by default, a new connection is established (and discarded) for each event that is sent. RetryInterval When ConnectionMode=connection_oriented, and the connection to the event server is lost, an adapter waits the specified number of seconds before connecting to a secondary server or buffering the events. While the adapter is waiting for the expiration of this interval, no new events are processed by the adapter. This option allows an adapter to send all events to the primary event server even if the primary event server is stopped briefly, such as when loading a new rule base. If you use this option to wait for restarting an event server, the value should be set for a period of time longer than necessary for the event server to be stopped and then restarted. The RetryInterval keyword is optional. The default is 120 seconds. NO_UTF8_CONVERSION When this option is set to YES, the Java Event Integration Facility (EIF) does not encode event data in UTF-8, the data is assumed to already be in UTF-8 encoding when passed to the EIF. It will, however, prepend the flag indicating that the data is in UTF-8 encoding if the flag does not exist at the beginning of the event data. The default value is NO. ServerPort Specifies the fixed reception port number on which the Tivoli Enterprise Console server listens for connection and adapter input. This keyword value should be set to 0 (the default value) on UNIX systems unless the portmapper is not available on the server. If the Tivoli Enterprise Console server is a Windows system, the ServerPort should be set to the value of the tec_recv_agent_port entry in the.tec_config file. Refer to the IBM Tivoli Enterprise Console: Adapters Guide for Chapter 12. Integrating the Tivoli Enterprise Console 265

286 Integrating the Tivoli Enterprise Console more information about the server port specification on Windows machines. If the port number is not specified, the value is retrieved by calling the portmapper. ServerPort can contain up to eight values, separated by commas. Specify one port number regardless of the number of ServerLocation values specified; however, if you specify more than one port number, you must specify a corresponding port number for each ServerLocation value. The default is 0. By default, Software Distribution sends all events to the event server. You can optionally specify event filters that indicate which events should not be sent. You can specify as many event filter entries as needed. To do so, you can include a Filter entry in the tecad_sd.conf file, as follows: Filter Specifies how events are filtered. Filter statements are used by the FilterMode entry to determine which events should be discarded. An event matches a Filter statement if each slot=value in the Filter statement is identical to the corresponding slot=value in the event. A Filter statement must contain the event class and can include any other slot=value that is defined for the event class. The format of the Filter statement is: Filter:Class=classname;slot=value;...;slot=value Each Filter statement must be on, and contained in, a single, 512-character (maximum) line. The Filter statement cannot contain spaces. The class name specified for an event filter entry must match a defined class name. See Software Distribution Classes on page 268 for a listing of classes for Software Distribution. For example, you can include the following entry in the tecad_sd.conf file to discard all events generated when the removal operation begins. Filter:Class=Remove_Start; The filtering behavior can be modified by using the environment variable FilterMode. By default, FilterMode is set to OUT. By adding FilterMode=IN to the configuration file, only the events that match the filters are delivered to the event server. Refer to the IBM Tivoli Enterprise Console: Adapters Guide for detailed information about filtering. If you make any changes to the tecad_sd.conf file, you must stop and restart the event server for the changes to take effect. 266 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

287 Integrating the Tivoli Enterprise Console Creating the Software Distribution Console 1. From the Tivoli Enterprise Console - Configuration window, right-click Event Console Configuration and select Create Console to create a new console. The Create Console dialog is displayed. a. Enter the name and a description of the console in the Name and Description text boxes. b. To assign the Software Distribution 4.x event group to the console, select Event Groups from the left pane of the Create Console dialog. Select Assign Groups and the Assign Event Group to Console dialog is displayed. c. Ensure that the Software Distribution 4.x event group is listed in the Available Event Groups scrolling list. Highlight the Software Distribution 4.x event group in the list. d. You can also assign administration roles for the Event Group from the Assign Event Groups to Console dialog. Assign a role by selecting the appropriate check box. Click OK to assign the Software Distribution 4.x event group to the console and the selected administration role. e. To assign operators to the new console, select Operators in the left pane of the Create Console dialog. Select an operator and use the left-arrow button to move the selected operator from the Available Operators scrolling list to the Current Operators scrolling list. Chapter 12. Integrating the Tivoli Enterprise Console 267

288 Integrating the Tivoli Enterprise Console Refer to the IBM Tivoli Enterprise Console: User s Guide for more information about performing tasks from the Tivoli Enterprise Console - Configuration window. 2. To view the event notices for the Software Distribution 4.x event group, select Windows->Summary Chart View from the Tivoli Enterprise Console - Configuration window. Double-click the summary chart and the Event Viewer window is displayed. Software Distribution Classes The Event Viewer window lists all events for the Software Distribution 4.x event group. These events are described fully in Software Distribution Classes. The following table lists the class name of all events defined by Software Distribution. Specifically, these classes are defined in the tecad_sdnew.baroc file. When you enable the Software Distribution Tivoli Enterprise Console Integration and run the swdistecsrvr_inst.sh script, these classes are compiled and included in the event server s rule base. Use this listing to understand how Software Distribution events are mapped to Tivoli Enterprise Console events. Note: This list of classes is provided for reference only. Do not edit the tecad_sdnew.baroc file. The following events are defined in the tecad_sdnew.baroc file. Refer to the Tivoli Event Integration Facility: User s Guide for more information about the syntax of.baroc files. Table 14. Software Distribution Tivoli Enterprise Console events Event Attribute Notes SD_Operation_Submitted dist_id sp_name op_name op_ mode By default, severity = HARMLESS and sub_source = swdist. 268 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

289 Integrating the Tivoli Enterprise Console Table 14. Software Distribution Tivoli Enterprise Console events (continued) Event Attribute Notes SD_Operation_Started SD_Operation_Failed SD_Operation_Successful SD_Operation_More_Targets dist_id sp_name op_name op_ mode dist_id sp_name op_name op_ mode msg_list failed_targets failed_target_exit_code dist_id sp_name op_name op_ mode successful_targets successful_target_exit_code dist_id sp_name successful_targets failed_targets failed_target_exit_code successful_target_exit_code By default, severity = HARMLESS and sub_source = swdist. By default, severity = FATAL and sub_source = swdist. By default, severity = HARMLESS and sub_source = swdist. This class is used when the target_list in any class causes the event to exceed 4 KB. This event is generated until the list of targets is complete. By default, severity = HARMLESS and sub_source = swdist. The Tivoli Enterprise Console event attributes relative to Software Distribution are defined as follows: Table 15. Tivoli Enterprise Console event attributes for Software Distribution Attribute Name dist_id sp_name op_name op_mode msg_list failed_targets failed_target_exit_code Attribute Value/Description The distribution identification number. For SD_Operation_Started events, the dist_id is a timestamp (date, time). The name of the software package in the format name^version or name.version. A change management operation. The change management operation mode. A list of error messages relative to a failed distribution operation. If the event exceeds the 4KB size limit, the list is truncated. A list of failed targets For software packages containing executable programs, this attribute returns the absolute path to the program, change management operation performed, the operation phase, and the exit code of the program for failed distribution targets in the following format: absolute_program_path cm_ operation:phase return_ code Chapter 12. Integrating the Tivoli Enterprise Console 269

290 Integrating the Tivoli Enterprise Console Table 15. Tivoli Enterprise Console event attributes for Software Distribution (continued) Attribute Name successful_targets successful_target_exit_code Attribute Value/Description A list of successful distribution targets For software packages containing executable programs, this attribute returns the absolute path to the program, change management operation performed, the operation phase, and the exit code of the program for successful distribution targets in the following format: absolute_program_path cm_ operation:phase return_ code 270 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

291 Chapter 13. Integrating Inventory with Software Distribution Configuration Repository Inventory is able to scan the machines in your Tivoli management region and gather hardware and software information that it stores in a database called the configuration repository. Software Distribution provides the following features that automatically update information stored in the configuration repository: Historical database This feature stores the following information: v Distribution operations performed on target systems, including the type of operation, the mode, the time it occurred, the result, and the distribution ID v Software names and versions that have been distributed Change management status This feature stores the following information: v Names and versions of software packages v Time of the last successful operation v Last known change management state of a software package on a target system v Software packages loaded on depots Inventory Integration This feature stores the following information: v The signature file Using the Tivoli Management Framework query facility, you can retrieve information from the configuration repository concerning successful or failed software distribution operations that have occurred in your Tivoli management region, and the change management status of a particular software package on a specific target. These features eliminate the need to write scripts to periodically update the configuration repository when software is distributed or removed in your Tivoli environment. This chapter describes how to enable the Software Distribution historical database and change management status features, and how to access information from the configuration repository. To use these features, you must have already configured Inventory and the Tivoli Management Framework query facility. This chapter also provides information about how to map a software package to one or more inventory signatures or how to specify new signatures that represent a software package. This method lets you to have the configuration repository automatically updated with the information of the latest software installed on your system. Inventory and Software Distribution store information in the configuration repository, which is a relational database management system (RDBMS) that holds information about system configurations in your Tivoli environment. Inventory provides the scripts necessary to create the configuration repository as well as to install the configuration repository schema. Copyright IBM Corp. 2002,

292 Configuration Repository Software Distribution uses the configuration repository with new or updated information about software packages, and spblocks that have been distributed to target machines in your environment, and organizes this information in various tables. Query Facility The Tivoli Management Framework query facility, which consists of query libraries and queries, enables you to use Structured Query Language (SQL) query functions to access information stored in the configuration repository. In the Tivoli environment, a query library is used to create and manage Tivoli queries, which specify which view or table to search within the repository and what information to retrieve. A view enables you to access information from one or more tables, and consists of derived instances from a single table or from the relational joining of multiple tables. Inventory has several predefined views and queries that you can use to access information from the configuration repository without having to create a specific query library or individual queries. It also provides a script to populate a unique query library, INVENTORY_QUERIES, with predefined views, tables, and queries that you can use to retrieve Software Distribution information. For more information about the query library and queries, refer to the Tivoli Management Framework: Planning for Deployment Guide and the User s Guide for Inventory. Describing Software Distribution Tables Software Distribution stores and updates information in the tables described below. These tables are stored in the configuration repository. To enable Software Distribution to store and update the information in the table you use the wswdmgr command. For more information about wswdmgr command usage and syntax, refer to the Reference Manual for Software Distribution. The wswdmgr command substitutes the wswsprim command. Although the wswsprim command is available in this release of the product, it will not be supported in future releases. Use instead the wswdmgr command, which replaces it. See also Enabling and Disabling the Historical Database and Change Management Status on page 274 SD_PACKAGES Stores information about names and versions, and other characteristics of software packages that have been distributed, and links this information to profile identifications. This table is updated after an operation has been completed. You can retrieve information from this table about the results of specific distribution attempts by running the query SWDISTDATA_QUERY against the predefined view SWDISTDATA_VIEW. SD_INST Stores information about the names and versions of software packages, the time the last successful action or operation was performed on a software package, and the status of a software package on a particular target machine. The SD_INST table is updated only after an operation has been completed. Running the CM_STATUS_QUERY retrieves software package status information directly from the SD_INST table and not through the use of a predefined view. 272 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

293 Configuration Repository How the Integration Works It is possible that the state registered in the SD_INST table of a software package on a particular target machine is not consistent with the status recorded in the local target catalog of the same software package. This inconsistency occurs when an operation is performed using a disconnected command line command. Refer to the Reference Manual for Software Distribution for more information about disconnected target commands. The status is updated after the next subsequent operation. Alternatively, you can use the wsyncsp command to synchronize the status on the server for software packages on specified endpoints with the actual status on the endpoints. Refer to the Reference Manual for Software Distribution for more information about the wsyncsp command. SD_H_INST Stores the history of operations. Specifically, it stores information about the target machine on which an operation or action was performed (such as install, remove, undo, accept, commit), the type and mode of the operation, the time at which this operation occurred, the name of the profile that was distributed, and the result of the operation. It contains also information about the distribution ID and the results of a distribution. This table is updated after an operation has been completed. You can retrieve information from this table about the results of specific distribution attempts by running the query SWDISTDATA_QUERY against the predefined view SWDISTDATA_VIEW. SD_LOADED Stores information about the depot, software packages loaded in the depot, base software packages loaded in the depot, the administrator ID for the last load operation, and the execution time for the last load operation. The SD_LOADED table is updated each time a load or unload operation is performed. Running the SD_LOADED_COMPONENT_QUERY queries the database for depot information. SIG_SP_MAP Stores information about the relationships between signature files and software packages. The table is updated each time a software package containing a signature file is built. You retrieve information from this table by running the SIG_SP_MAP_QUERY query. Information about the Software Distribution views, queries, and tables is provided in the Database Schema Reference. Inventory also provides the Database Schema poster, which illustrates table and column associations in the configuration repository. The configuration repository must be populated with new or updated information about each target. The configuration repository can be populated in the following ways: v Running an Inventory hardware scan on each target machine v Running a change management operation By default, Software Distribution performs an autoscan the first time you run a change management operation. It reports the global unique identifier for the endpoint to the configuration repository. To change the default behavior of automatically scanning targets, modify the autoscan_active attribute by submitting the following command: Chapter 13. Integrating Inventory with Software Distribution 273

294 Historical Database and Change Management Features wswdcfg -s autoscan_active=n When you set up the integration the following conditions apply: v The configuration repository is updated with the change management status and historical database information. v Software Distribution exchanges information with Inventory. See Exchanging Information between Software Distribution and Inventory for a detailed explanation. v Inventory exchanges information with Software Distribution. An Inventory scan detects the software packages installed on the targets. This association allows you to have an up-to-date list of the software installed in your environment. See Exchanging Information between Software Distribution and Inventory. The integration is performed at the server level. Only the configuration repository is updated. Enabling and Disabling the Historical Database and Change Management Status The exchange of historical database and change management status information is automatically enabled when you install Tivoli Configuration Manager. You enable or disable the historical database and change management status integration by running the wswdmgr command and setting the following keys to true: is_hdb_enabled is_cmstatus_enabled The historical database information is stored and updated in the configuration repository. The default value is true. The change management status information is stored and updated in the configuration repository. The default value is true. Note: If is_cmstatus_enabled is false, the product forces is_hdb_enabled to false. This integration permits you to control the registration of distribution status information in the configuration repository. If you do not need to track distribution information, disable the integration prior to distributing software packages. Re-enable the integration to resume tracking distribution information in the configuration repository. For more information about the wswdmgr command usage and syntax, refer to the Reference Manual for Software Distribution. Exchanging Information between Software Distribution and Inventory To exchange information between Software Distribution and Inventory, perform the following tasks: 1. Enable the exchange of information by running the wsetinvswd command. You can verify if the exchange has been enabled using the wgetinvswd command. For more information about wsetinvswd and wgetinvswd commands usage and syntax, refer to the User s Guide for Inventory. Run the wswdmgr command to set the is_swd_inv_enabled key to true. 274 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

295 Enabling and Disabling Historical Database and CM Status Note: To transfer the signature data from Inventory to Software Distribution and update the SIG_SP_MAP table, also the is_cmstatus_enabled key must be set to true, that is the default value. 2. Define one or more signature files in the software package. See Defining an Inventory Signature on page Import the software package. The SD_PACKAGES table is updated with the information related to the imported software package. 4. Build the software package. The following tables are updated: SWARE_SIG This table contains the information related to the signature files associated with the built software package. The process creates a new entry for each signature file if it does not exist. SD_PACKAGES This table contains information about the software package you created, such as the name and the version of the software package. SIG_SP_MAP This table contains a mapping between the information contained in the SWARE_SIG table and the SD_PACKAGES table. For a detailed explanation of building the software package, see Converting a Software Package on page To view the signatures you defined, use the wmapsigsp command. 6. At this point you can either: v Install the software package. When the operation is performed, Software Distribution updates the catalog directly on the endpoint with the new status of the software package. On the server the MATCHED_SWARE table is updated with package containing the signature, and the SD_INST table is updated with the new status of the software package. v Run an Inventory software scan with the Scan for Installed product using signature matching check box selected. If a signature file is discovered by the scan, Inventory requests an update of the catalog on the endpoint and the SD_INST table is updated with an IC-D- status of the package, while the MATCHED_SWARE table is updated with the signature. If the package has already been installed with Software Distribution, the status is not updated as IC-D- but, remains the same as that already registered in the SD_INST table when it was first installed. When you remove (wremovsp) the software package from the endpoint, the row related to the software package is removed from the SD_INST table, and the row related to the signature is removed from the MATCHED_SWARE table. Run the INVENTORY_SWARE query to verify that the entry with the signature information has been removed. If the query does not return any information, verify the list of created signature files using the wmapsigsp command. For more information about wmapsigsp command usage and syntax, refer to the Reference Manual for Software Distribution. Instead, when you delete (wdel) the software package profile, the row related to the software package is removed from SD_PACKAGES table and the value of the MAP_STATUS field in the SIG_SP_MAP table is changed from 1 to 0. To physically remove the row related to the deleted software package profile from the table, use the wmapsigsp -p command. Chapter 13. Integrating Inventory with Software Distribution 275

296 Enabling and Disabling Historical Database and CM Status Defining an Inventory Signature Inventory signature files are useful to identify whether applications are already installed on workstations in your environment. You can define one or more signature files in a software package using the Software Package Editor GUI or from the command line. Perform one of the following tasks, as appropriate: v Right-click the file that you want to define as signature and then click Properties to display the Add Directory Properties dialog. Select the appropriate option from the Is inventory signature pull-down to indicate that a file in the software package is a signature. See Adding Windows Operating System Directories and Files on page 38 for an example. You can also set the is_signature attribute in the add directory or in the add file stanzas, and define the contained_signature stanza in the software package. For more information about the stanzas, refer to the Reference Manual for Software Distribution. v From the command line, set the is_signature attribute in the add_directory or add_file stanza. v Use the Set Inventory Signature dialog to identify an application with a signature file, as described below: 1. With the software package selected in the Software Package Editor main window, select the System action tab. 2. Select the Inventory signature icon to display the Set inventory signature dialog. 3. In the File Name text box, type the name of the product. 4. In the File Size text box, type the size of the file in bytes. 5. Select the Add if not existing check box to add the inventory signature to the appropriate table in the configuration repository, if it does not already exist. Optionally enter a description and version number of the product in the Description and Version text boxes. Note: No check is performed on the target endpoint machine after the installation of the package to verify that the signature file actually exists. The INVENTORY_SWARE table is updated with the signature file in any case. 276 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

297 Enabling and Disabling Historical Database and CM Status Creating the INVENTORY_QUERIES To create the INVENTORY_QUERIES query library and the related queries submit the following shall script: $BINDIR/../in/SCRIPTS/QUERIES/inventory_queries.sh The following queries are created: v CM_STATUS_QUERY v SD_LOADED_COMPONENT_QUERY v SWDISTDATA_QUERY v SWDIST_WEBUI_QUERY v SIG_SP_MAP_QUERY Running an INVENTORY_QUERY The following steps briefly describe the process of running a query from the INVENTORY_QUERIES query library and of saving the query results to standard output or a file. The following table provides the authorization role required to perform this task: Operation Context Required Role Run a query Query library senior or super You can perform this task from either the Tivoli desktop or the command line. Desktop Complete the following steps to run the predefined query SWDISTDATA_QUERY from the INVENTORY_QUERIES query library. (The steps for running the CM_STATUS_QUERY, SD_LOADED_COMPONENT_QUERY, SIG_SP_MAP_QUERY, and SWDIST_WEBUI_QUERY predefined queries, which also appear in these dialog examples, are similar.) 1. Double-click the SIG_SP_MAP_QUERY query library icon to display the INVENTORY_QUERIES dialog. This query library contains the predefined query SWDISTDATA_QUERY. 2. To run this query, right-click the SWDISTDATA_QUERY icon and select Run Query. OR Right-click the SWDISTDATA_QUERY icon and select Edit Query to open the Edit Query dialog. From this dialog, click Run Query. The Run Query dialog is displayed, showing the results of the SWDISTDATA_QUERY in tabular form. The following dialog illustrates a Chapter 13. Integrating Inventory with Software Distribution 277

298 Running SWDISTDATA_QUERY portion of the results that are displayed: 3. You can save the results of the query from the Run Query dialog by completing the following steps: a. On the Run Query dialog, click Export. The Export Query Results dialog is displayed. b. In the Host text box, enter the name of the machine on which you would like to save the results file. If you do not specify a host name, the file will be saved on the local machine. c. In the File text box, enter a directory and name for the query results file. OR Click browse (...) to browse the file system. d. Select one of the Delimiter options to specify how to separate entries in the query results file. If you want to use a delimiter other than a comma or a tab, select Custom and enter a delimiter in the text box. e. Select the Print Headers check box if you want the output file to include the query name and the names of the columns. f. Click Save & Close to create the file. 278 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

299 Command Line You can use the wrunquery command to run SWDISTDATA_QUERY and either display the results to standard output or save the results to a file. Enter the following from the command line: wrunquery -n -h pescado -f /tmp/query.txt -d ; / SWDISTDATA_QUERY where: n Omits headers from the results file. h pescado Specifies pescado as the name of the machine on which to store the file. f /tmp/query.txt Specifies /tmp/query.txt as the location and name of the query results file. -d ; Specifies a semi-colon as the delimiter. SWDISTDATA_QUERY Specifies the name of the query to be run. For more information about the wrunquery command, refer to the Tivoli Management Framework: Reference Manual. Modifying SWDISTDATA_QUERY Running SWDISTDATA_QUERY As illustrated in the Run Query dialog shown on page 277, SWDISTDATA_QUERY retrieves and posts an extensive list of Software Distribution data that includes information about machine name and identification, profile type and identification, source host name, whether the operation completed successfully, and the time of completion. You can also create a customized query based on the parameters defined in SWDISTDATA_QUERY. Customizing a query enables you to search for more specific information concerning software distributions and removals in your Tivoli environment. An example of how to create a custom query follows. The User s Guide for Inventory provides detailed descriptions of how to create, edit, and run queries. The following example in this section briefly demonstrates how to create a new query that retrieves information about software package installations using the force option. Several of the parameters in SWDISTDATA_QUERY are used in setting up this customized query. To keep the example brief, only text boxes that are specific to customizing this search are described. Refer to the User s Guide for Inventory for more detailed instructions and examples. The following table provides the authorization role required to perform this task: Operation Context Required Role Edit a query Query library senior or super You can perform this task from either the Tivoli desktop or the command line. (The steps for editing the CM_STATUS_QUERY predefined query, which also appears in these dialog examples, are similar.) Chapter 13. Integrating Inventory with Software Distribution 279

300 Modifying SWDISTDATA_QUERY Desktop Complete the following steps to edit SWDISTDATA_QUERY from the Tivoli desktop: 1. In the INVENTORY_QUERIES query library, select Query from the Create menu. The Create Query dialog is displayed. 2. In the Query Name text box, enter Software Packages. 3. In the Description text box, enter Information on software packages installed. 4. Select inventory from the Repository menu. 5. In the Table/View Name text box, enter SWDISTDATA_VIEW and click Set. Doing this populates the Available Columns text box. 6. Use the left arrow to move the following columns from the Available Columns scrolling list to the Chosen Columns scrolling list: v TME_OBJECT_LABEL v SOFTWARE_COMPONENT_NAME v INSTALLED_FILEPACK_TIME v MD2_DIST_ID 7. To create the SQL statement to query for software package installations that use the force option, complete the following steps to add a condition in the Where Clause text box: a. In the Column Name text box, enter FILEPACK_TYPE. You can also click browse (...) and select FILEPACK_TYPE from the list of column names. This list displays the columns in the Chosen Columns scrolling list. b. Leave equals (=) as the logical operator. c. Click browse (...) in the Column Value section. Select SOFTWARE_PACKAGE, then click Close. d. Click Add to add the first criteria to the Where Clause text box. e. In the Column Name text box, enter ACTION_COMPLETED. f. In the Column Value text box, enter install (f). g. Click Add to add the second criteria to the Where Clause text box. The Create Query dialog appears as follows: 280 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

301 Modifying SWDISTDATA_QUERY 8. Click Create to save the query. Click Run Query to query from this dialog. OR Click Create & Close to return to the query library window. Right-click the Software_Packages icon and click Run Query. Inventory returns the following results: Chapter 13. Integrating Inventory with Software Distribution 281

302 Modifying SWDISTDATA_QUERY Command Line The following example creates the SOFTWARE_PACKAGE_INSTALLATIONS query from the command line: wcrtquery -d information on software packages installed \ -r inventory -v SWDISTDATA_VIEW -c TME_OBJECT_LABEL \ -c SOFTWARE_COMPONENT_NAME -c FILEPACK_TYPE \ -c INSTALLED_FILEPACK_TIME -c ACTION_COMPLETED \ -w (FILEPACK_TYPE= SOFTWARE_PACKAGE ) \ -w (ACTION_COMPLETED= install (f) ) \ INVENTORY_QUERIES SOFTWARE_PACKAGE_INSTALLATIONS For more information about the wcrtquery command, refer to the Reference Manual for Software Distribution. 282 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

303 Chapter 14. Upgrading Windows 2000 Professional to Windows XP Environment Configuration Creating a Response File This chapter outlines an example procedure on how to use Software Distribution to upgrade a Windows 2000 Professional system to Windows XP. The example scenario consists of the following procedures: v Creating the response file appropriate for your environment v Copying the files that you need to perform the migration to the Tivoli management region server (Tivoli server) v Copying the Windows XP files to the image server v Customizing the Inst_wXP.spd software package definition file v Creating the software package on the Tivoli server v Subscribing the endpoints to the upgrades profile manager v Distributing the software package to the endpoints v Using the Check_OS^1.0.spd software package definition file to verify the upgrade To complete this scenario, you must have the following environment: v A workstation with Windows XP installed. v A Tivoli server on which to prepare and pack the software package. v An image server on which to store the Windows XP operating system files. v The target workstations with Windows 2000 installed. You must define the target workstations as Tivoli endpoints. To upgrade to Windows XP, you must customize a response file for your environment. You can do this in one of the following ways: v Create a response file using the information provided in the Microsoft Windows XP documentation and customize it for your environment. v Customize the example response file provided in Software Distribution. The provided example that you can customize is the Unattend.txt file in the directory \MSOSUPG\upgrtoWXP\ of the CD1 CD-ROM. The file is as follows: upgrading from Windows NT or Windows 2000 to Windows XP ;SetupMgrTag [Data] AutoPartition=1 MsDosInitiated="0" UnattendedInstall="Yes" [Unattended] UnattendMode=FullUnattended OemSkipEula=Yes OemPreinstall=No NtUpgrade=Yes AutoActivate=yes Copyright IBM Corp. 2002,

304 Creating a Response File [GuiUnattended] AdminPassword=* OEMSkipRegional=1 TimeZone=110 OemSkipWelcome=1 AutoLogon=Yes [UserData] FullName=Administrator OrgName=WORKGROUP ComputerName=* ProductID=yourProductID [Identification] JoinWorkgroup=WORKGROUP [Networking] InstallDefaultComponents=Yes The Unattend.txt response file addresses also the unattended installation procedure because the following attributes have been specified: v In the Unattended section, AutoActivate=Yes v In the UserData section, ProductID=yourProductID. The yourproductid information is located on the Certificate of Authenticity (COA) sticker. Every Windows XP retail installation must have a unique Product ID for activation. If the Internet connection is through a proxy server, specify the proxy settings in the Unattend.txt file as follows: v In the Unattended section, type ActivateProxy=Proxy v In the Proxy section, type your computer s proxy settings Copying the Files That You Need to Perform the Migration to the Tivoli Server To perform the upgrade from Windows 2000 to Windows XP, you must copy the following files that are contained in the CD1 CD-ROM to the Tivoli server. v Inst_wXP.spd v Unattend.txt Note: You can use the response file that you created in Creating a Response File on page 283 instead of this file. v check.bat v Check_OS.spd To copy these files from the CD1 CD-ROM to the Tivoli Server, perform the following steps on the Tivoli server: 1. Create a directory in which to store the files. This scenario uses the upg_xp directory. 2. Copy the Inst_wXP.spd, the Unattend.txt, the Check_OS.spd and the check.bat files: v For UNIX, copy the files from the /MSOSUPG/upgrtoWXP directory to the /upg_xp directory on your Tivoli server by entering the following commands from the /upg_xp directory: cp CD_drive/MSOSUPG/upgrtoWXP/Inst_wXP.spd. cp CD_drive/MSOSUPG/upgrtoWXP/Unattend.txt. 284 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

305 Copying Required Migration Files cp CD_drive/MSOSUPG/upgrtoWXP/Check_OS.spd. cp CD_drive/MSOSUPG/upgrtoWXP/check.bat. v For Windows, copy the files from the CD_drive:\MSOSUPG\upgrtoWXP directory of the CD1 CD-ROM to the drive\upg_xp directory on your Tivoli server by entering the following command from the drive\upg_xp directory: copy CD_drive:\MSOSUPG\upgrtoWXP\Inst_wXP.spd copy CD_drive:\MSOSUPG\upgrtoWXP\Unattend.txt copy CD_drive:\MSOSUPG\upgrtoWXP\Check_OS.spd copy CD_drive:\MSOSUPG\upgrtoWXP\check.bat Copying the Windows XP Files to the Image Server To copy the Windows XP files to the image server, follow these steps: 1. Create a directory called shared on the C: drive of the image server. 2. Start the regedt32.exe registry editor. The Registry Editor - HKEY_ LOCAL_ MACHINE dialog displays. 3. From the HKEY_LOCAL_MACHINE subtree, select System-> CurrentControlSet->Services->LanmanServer-> Parameters->NullSessionShares. 4. Select NullSessionShares. The Multi-String Editor dialog displays. 5. Enter shared and click OK. 6. Share the c:\shared directory with the target workstations that you want to upgrade to Windows XP by entering the following command: net share shared=c:\shared 7. Create the winxp directory under the c:\shared directory. 8. Copy the Windows XP source files from the Windows XP CD-ROM to the c:\shared\winxp directory on the image server by entering the following command: xcopy <CD_drive>:\<winXPsource>\*.* c:\shared\winxp\*.* /s/e where winxpsource is the Windows XP CD-ROM directory that contains the operating system source files. 9. Copy theunattend.txt response file or the response file that you created in Creating a Response File on page 283 to c:\shared\winxp. Customizing the Inst_wXP.spd Software Package Definition File Use the Inst_wXP.spd software package definition file to upgrade to Windows XP. Customize the Inst_wXP.spd software package definition file by specifying the \\ImageServer\shared\winXP in the sp_path, where ImageServer is the name of the server where the image of the Windows XP operating system is located. The Inst_wXP.spd software package definition file follows: Software Package v SPDF" package name = "Inst_wXP" title = "Install Windows XP" version = "1.0" undoable = "o" committable = "o" history_reset = n save_default_variables = n creation_time = " :10:19" last_modification_time = " :14:08" Chapter 14. Upgrading Windows 2000 Professional to Windows XP 285

306 Copying the SPD file default_variables sp_path = "\\ImageServer\shared\winXP" end execute_user_program transactional = n during_install exit_codes success = 0,0 failure = 1,65535 end path = "$(sp_path)\i386\winnt32" arguments = "/unattend:$(sp_path)\unattend.txt /s:$(sp_path)\i386" timeout = 7200 unix_user_id = 0 unix_group_id = 0 user_input_required = n output_file_append = n error_file_append = n reporting_stdout_on_server = y reporting_stderr_on_server = y max_stdout_size = max_stderr_size = bootable = y retry = 1 end end end Creating the Software Package on the Tivoli Server Before creating a software package, you must create on the Tivoli server a profile manager that contains the software package and a directory path in which to store the software package block. Refer to thetivoli Management Framework: User s Guide to learn how to create a profile manager. This scenario assumes that you created the upgrades profile manager and the packages directory path in which to store the Inst_wXP.spb software package block in the Tivoli server. To create and build the software package on the Tivoli server, enter the following command: v In a UNIX environment: wimpspo -f /upg_xp/inst_wxp.spd -t build -p v In a Windows environment: wimpspo -f c:\upg_xp\inst_wxp.spd -t build -p This command does the following: Creates the Inst_wXP^1.0 software package object that is based on the c:\upg_xp\inst_wxp.spd software package definition file Builds a software package block Writes the software package block in the packages directory 286 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

307 Subscribing Endpoints to Upgrades Profile Manager Subscribing the Endpoints to the Upgrades Profile Manager Subscribe the Tivoli endpoints to the upgrades profile manager by entering the following command from the Tivoli @Endpoint:targetn Where target1,..., targetn are the Tivoli endpoints that you want to subscribe. Distributing the Software Package to the Tivoli Endpoints To distribute the software package to the Tivoli endpoints, enter the following command from the Tivoli server: v In a UNIX v In a Windows Where target1, target2,..., targetn are the Tivoli endpoints on which you want to install Windows XP Professional. You can also create a profile manager that contains all the targets to upgrade and specify the name of the profile manager in the winstsp command. In a Windows environment, for example, if you created the win_targets profile manager, enter the following After you enter one of the previous commands, the upgrade process starts on the Tivoli endpoints. When the distribution of the software package ends, the targets reboot. Using the Check_OS^1.0.spd to Verify the Upgrade Using the Check_OS^1.0.spd you can verify if the Windows XP has been installed in your environment. To perform this check perform the following steps: 1. Create and build the Check_OS^1.0.spd software package on the Tivoli server, by entering the following command: v In a UNIX environment: wimpspo -f /upg_xp/check_os.spd -t build -p v In a Windows environment: wimpspo -f c:\upg_xp\check_os.spd -t build -p 2. Distribute the Check_OS^1.0 software package to the Tivoli endpoints, by entering the following command from the Tivoli server: v In a UNIX v In a Windows Where target1, target2,..., targetn are the Tivoli endpoints on which you want to install Windows 2000 Professional. You can also create a profile manager that contains all the targets to check and specify the name of the profile manager in the winstsp command. In a Windows environment, for example, if you created the win_targets profile manager, enter the following Chapter 14. Upgrading Windows 2000 Professional to Windows XP 287

308 Verifying Upgrade After you enter one of the previous commands, the check process starts on the Tivoli endpoints. When the distribution of the software package ends, verify that the operating system indicated in the standard output section of the Check_OS.log file is Windows XP. 288 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

309 Chapter 15. Troubleshooting Troubleshooting Process This section gives an overview of the initial troubleshooting process and provides descriptions of sources of information that will help you in solving problems with Software Distribution operations. It includes the following topics: v Troubleshooting Process, which describes a process by which you can monitor the progress of a software distribution. v Improving Performance on page 293, which describes commands and settings for improving Software Distribution performance. v Checking Configuration Files on page 294, which identifies the configuration information that you can use to customize the various components of Software Distribution. v Software Distribution Logs on page 296, which describes the software package log and other sources of information that are available for users of Software Distribution. v Examining the SPD File on page 305, which provides a summary of the information from the software package file that could be helpful in problem solving. v Troubleshooting the Software Package Editor GUI on page 305, which provides information about improving GUI performance. v Checking Repeaters, Gateways, and Endpoints on page 306, which provides information on network problems that can cause distribution failures, product configuration problems, and how you can identify them. v Checking lost-n-found on page 310, which describes a feature for recovering software packages if they disappear from your desktop. v Checking the Default Directory on a Target System on page 311, which includes information about the default location of installed objects for which the specified destination location cannot be resolved. These topics provide you with an overview to the troubleshooting process. Figure 6 on page 290 shows the typical process of distributing a software package and the stages at which you could check for problems with the distribution. The numbers 1 through 11that appear in the figure relate to the information provided after the figure. Copyright IBM Corp. 2002,

310 Troubleshooting: the Process Figure 6. Troubleshooting the distribution of a software package The following notes expand the information provided in Figure 6; the note numbers refer to the numbers in parentheses: 290 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

311 Troubleshooting: the Process 1. If you cannot find the software package you want to submit in a profile manager on your desktop, it may have been moved to the lost-n-found collection. See Checking lost-n-found on page If you are using the GUI to submit distribution operations, you should check the main panel of the Tivoli desktop to determine the ID returned by the submission. 3. You may have made an error entering the command on the CLI or GUI. Read the error message and, if necessary, the man page for the command. There may be a problem with the software package. Check the error message and see Examining the SPD File on page 305 for attributes you should check in the software package. If the error is not in the command you submitted, use the odstat command to view the methods currently active and any errors associated with them. To view a list of all the cm_execute_src and send methods called by the cm_execute_src method, enter the odstat c command on the source host. This command tracks the activities on servers, gateways, repeaters, and the source host. It lists the CM operation method as running on the server and the cm_execute_src method as running on the source host. It lists the send method as running on the repeater. If you continually enter the odstat c command, you will see each method disappear from the list as each process completes, and the cm_execute_src method completes. See the Tivoli Management Framework: Reference Manual for a description of the odstat command and its arguments. 4. After a reasonable interval has passed after successfully submitting the operation, you should check on its progress, using the wmdist command. v You can use the wmdist -e <distribution_id> or the wmdist -q <distribution_id> command to check on the progress of a distribution on the nodes (repeaters and endpoints) that form the chain through which a distribution passes from the source to the target. MDist2 updates the data retrieved by this command using a notify interval, the default for which is 30 minutes. v The wmdist -I <repeater> command checks the status of distributions at the defined repeater in real time. 5. The distribution could be in the following possible states: v waiting The distribution is still in progress. v paused There are three possibilities for this state: The user paused the distribution The endpoint is a mobile endpoint The timeout period for the user notification dialog on endpoint has not yet elapsed v unavailable Communication failure to endpoint. Check the lcfd process on the endpoint. v interrupted The distribution has been interrupted due to network problems. The distribution is retried on the endpoint each retry interval. 6. When an operation has completed on a target, it may not necessarily have completed successfully. Different types of distributions have different ways of Chapter 15. Troubleshooting 291

312 Troubleshooting: the Process gauging success or failure. Distributions that have not completed inside the maximum time limit are marked as expired. 7. When the operation has completed successfully, errors (for example, a failed after script) and warnings may have been generated. Consult the software package log for information. See Software Distribution Logs on page 296. Note: If the distribution is successful, but the files in the package are not installed in the expected destination location, then a variable may have been used that was not defined. The installed files are placed in a directory named after the variable name. Open the package and check that all variables have been defined. 8. Consult the software package log for details of the error (see Software Distribution Logs on page 296). Errors can be generated because of problems with the definition of the software package. See Examining the SPD File on page 305. Details of the error can also be found in the lcfd.log where the following exception is reported: Jul 10 14:04:24 Q MethInit ** Exception caught in run_impl: unknown exception:exception:userexception:sysadminexception: :ExException:SpDistEngine::Spde::ExNestedSpErrorMsg Error messages are also written to the MESSAGES field in the SD_H_INST inventory table. See Configuration Repository on page All distributions have an absolute maximum time limit, after which they will be reported as expired. The default deadline is 72 hours, which can be changed by setting the -l argument (to change the MDist2 parameters) on the distribution command at the time of submission. However, you will know from your experience how long a particular distribution should take in normal circumstances, and can commence examining all distributions that exceed your anticipated time window. Consult the software package log for details. See Software Distribution Logs on page 296. Problems at this stage of the distribution are probably caused by one of the following: v Problems with the availability or performance of repeaters and endpoints. See Checking Repeaters, Gateways, and Endpoints on page 306. v Execution of a user program that does not complete. If a distribution expires before you expected it to expire, the software package may belong to a policy region in which the deadline was changed using the wswdmgr command or by changing the default GUI settings. Refer to the Reference Manual for Software Distribution for more information about the wswdmgr command. See Customizing the GUI Settings on page 195 for information about modifying the deadline default setting. 10. After the distribution completes, check the result in the Software Distribution log file located at $BINDIR/../swdis/work. See Software Package Log on page 297 for more information about the log file. 11. Use the wmsgbrowse command to check undelivered messages still in the Software Distribution queue. Refer to Reference Manual for Software Distribution for the command syntax of the wmsgbrowse command. 292 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

313 Troubleshooting: the Process Hints and Tips Improving Performance Solaris patch installation problems When a software package containing a Solaris patch installation has completed successfully, but you find problems with the installation, run the following commands: widmap list_entries root_group which returns the list of entries currently defined in root_group to determine whether the entry other is present for the solaris2 interp. If it is not, run widmap add_entry root_group solaris2 other to add the entry. Refer to Tivoli Management Framework: Reference Manual for the command syntax of the widmap command. Error unmounting a remote disk A software package containing an execute user program that unmounts a remote disk could encounter an error due to locked files after the installation. For example, a software package contains the following objects: 1. An execute user program where a net use command mounts a remote disk. 2. An InstallShield program object that installs an application. 3. An execute user program where a net use delete command unmounts a remote disk. If the software package installation fails, redefine the software package using a default variable that represents a remote disk as follows: 1. Define a default variable in the software package, net_dir, and assign the path to the remote disk as the value 2. Define an installshield program object and use the net_dir variable in the response file path. Scheduling a distribution using the Tivoli Scheduler Performing a Software Distribution operation with retry options specified, the following error message is reported: Execution of the job failed! The scheduled job has not failed, but Software Distribution sends an exception to the Tivoli Scheduler so that the Scheduler retries the operation. To improve Software Distribution performance, you can perform one or more of the following tasks: Setting the Number of Endpoints to Be Handled To improve the management of several endpoints during the reporting phase, define the max_endpoint_answer parameter on the Software Distribution server using the wswdcfg command. When you use this parameter, Software Distribution chunks the number of endpoints to handle during a distribution. The value of this parameter is expressed as a positive integer greater than or equal to 30. The default Chapter 15. Troubleshooting 293

314 Troubleshooting: the Process value is 30. If you leave the default value, Software Distribution processes all the endpoints, while if you enter a higher value, Software Distribution handles that number of endpoints at a time. Setting the Report Timeout for the Server To prevent MDist 2 from sending the same reports to the Software Distribution server more than once, set the report_execute_timeout parameter on all the source hosts of the region using the wswdcfg command. This parameter indicates the maximum amount of time the Software Distribution server needs to process the reports sent by MDist2. Its value is expressed as a positive integer representing minutes (the default value is 30). Setting the Number of Threads To prevent MDist 2 from sending too many threads during the reporting phase, set the report_threads_limit parameter on the Tivoli Distribution server using the wswdcfg command. The default value is 10. If the number of threads reaches the limit value, MDist2 tries to send the other threads later. Checking Configuration Files This section gives information about the configuration files for the various components of the system. It is divided the following sub-sections: v Base Configuration Information on the Distribution Server and Source Host. v Base Configuration Information on the Endpoint. Base configuration information includes the location of platform-specific data on endpoints, distribution servers, and source hosts. Base Configuration Information on the Distribution Server and Source Host Base configuration information on distribution servers and on source hosts is managed using the wswdcfg command. For information about using this command to customize base configuration settings, refer to the Reference Manual for Software Distribution. Base Configuration Information on the Endpoint Base configuration information on an endpoint is stored in a file called swdis.ini, which is located in the appropriate system directory on the target system, depending on the platform. The following table indicates the location of the swdis.ini file on various platforms. Table 16. Location of swdis.ini file Platform Windows NetWare OS/2 OS/400 Location sysem_drive:\system_path, for example, on Windows XP, system_drive:\windows sys:\system system_drive:\os2 /swdis 294 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

315 Troubleshooting: Configuration Files Table 16. Location of swdis.ini file (continued) Platform UNIX Location etc/tivoli This file is only accessed by user root, as the owner of the global SD catalog. Other users, who can execute commands, have their own private SD environments where the swdis.ini file is stored in the $HOME/.swdis directory. The swdis.ini file contains parameters such as the following examples, which are based on the use of the UNIX platform: [lab16003-hp] product_dir=/opt/tivoli/swdis/1 working_dir=/opt/tivoli/swdis/1/work backup_dir=/opt/tivoli/swdis/1/backup trace_level=0 trace_size= send_timeout=300 autopack_dir=/opt/tivoli/swdis/1/autopack staging_dir=opt/tivoli/swdis/1/service user_file_variables=/opt/tivoli/swdis/1/swdis.var import_libraries=spd,libecimp inventory_scan_file=/opt/tivoli/lcf/inv/scanner/sd_scan.nfo speditor_dir=/opt/tivoli/swdis/1/speditor [#GENERIC] The following table gives a brief explanation of the keys included in this file: Table 17. Directory assignments in swdis.ini file Key product_dir working_dir backup_dir trace_level Description Identifies a parent directory where Software Distribution data, such as catalogs, messages, traces, and backup packages, are stored. History file (catalog) for each target system. Backup area for undo operations. v 0 = none (default) v 1 = fatal v 2 = error v 3 = warning v 4 = info v 5 = verbose trace_size send_timeout autopack_dir staging_dir Maximum size of the trace file (default size is 1,000,000 bytes. If the software package contains at least one program with a timeout setting, this value is used to extend either the repeater execute_timeout or the repeater send_timeout, depending on where the program action is positioned in the package. See User Program Timeout on page 308 for more information. Identifies the directory name where you want to temporarily store the results of the Autopack snapshots. The default is <product_directory>\autopack. Staging area for transactional operations. Chapter 15. Troubleshooting 295

316 Troubleshooting: Configuration Files Table 17. Directory assignments in swdis.ini file (continued) Key user_file_variables import_libraries inventory_scan_file speditor_dir ep_trace_level* Description Identifies the location of the swdis.var file that contains user-file variables. The default location is the product directory of the endpoint. Identifies the path name of the library that contains the object to be added to the software package. The path cannot contain wildcards. Retrieves hardware information on the system. Directory where the Software Package Editor is installed. Default values are: v Windows: <system_drive>\swdis\speditor v UNIX: /opt/tivoli/swdis/1/speditor v OS/2: <system_drive>\tivoli\swdis\speditor v O = disabled (default) v 5 = enabled ep_trace_size* value in bytes, default ep_trace_style* ep_trace_tags* 0 = trace file named spde.trc 5 = trace file named spde.dxxhyy.trc tag1, tag2,... (currently the only available tag is datamoving ) * These keys permit mobile users to check the status of data retrieve operations. Software Distribution Logs When this file is created and each time it is accessed, a backup copy called swdis.bak is created in the same directory and marked as a read-only file. To change configuration information, you edit the swdis.ini file. The swdis.bak file is updated automatically with the previous configuration the next time you use the product. If the swdis.ini file is accidentally deleted, the file is re-created using the information stored in swdis.bak, not from other default values, which preserves your customized configuration. If the product is removed and then re-installed, for a completely new configuration you should be sure to delete both of the existing swdis.ini and swdis.bak files. During the use of the Software Distribution components, information is collected in the following log files and listeners: v Software Package Log on page 297 v Notices and Mail on page 303 v Tivoli Enterprise Console on page 304 v Configuration Repository on page 304 v Data Moving Logs on page 302 v Log Object List on page 303 All reporting activities, apart from those in the pre-submission phase of an operation, are handled so that if one of the listeners cannot be reached, the information is stored on the file server and delivered the next time an operation is completed. 296 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

317 Logs: Software Package Software Package Log The software package log is the main source of information for software distribution operations. Logging is always active and available, as long as the log host is accessible. Every software package has a log file, which by default is named software_package_name.version.log and is located at $BINDIR/../swdis/work. The default location of the log is the directory specified in the working_dir attribute (defined in the swdis.ini file) on the server. It is the default log host. You can specify a different host and location by assigning values to the log_host and log_path attributes in the SPD file. You can use the wgetspop command with the -h and -L arguments to find the values that have been set for the log host and log path attributes. You can use the wsetspop command with the -h and -L arguments to change the values that have been set in the SPD file. In UNIX environments, additional software package attributes, log_gid, log_mode, and log_user, allow you to customize log file rights and log ownership. These attributes can be retrieved and overridden in the wgetspop and wsetspop commands, using the -j and -u arguments. Each time a distributive operation is performed, information is written to the software package log for the software package or packages that are involved. The wsyncsp command creates a log file on the Tivoli management region server, wsyncsp.log, where the results of the synchronization are recorded. When synchronization causes a change in the state of a package that exists on the desktop, this information is also written to the software package log for that package. The information recorded in the log depends on the mode in which an operation is performed. For logging purposes, there are three modes, as follows: Distributive This is the normal mode for an operation. In this mode the action specified, for example install, remove, or undo, is performed on the specified endpoints. When a distributive operation is performed, a log entry is made before submitting and when the operation is completed. Preview An operation runs in preview mode when the preview argument (-p) is specified. When an operation runs in this mode, it updates the software package log file on the server with a list of actions that would be carried out if you performed the operation. The operation is not actually carried out. A check is performed on the target and the list of files to be repaired or a list of source files that have been modified is returned to the log file. Note: The preview source mode (-p -m s) produces preview mode log entries because it returns information about source files that have been modified since the last successful distribution. However, the preview repair mode (-p -m r) returns information about both source files as well as files on the endpoint that have been changed or corrupted since the last successful operation and so produces distributive mode log entries. Chapter 15. Troubleshooting 297

318 Logs: Software Package Check An operation runs in check mode when the check argument (-i) is specified. Checks are performed to ensure that the operation is possible, for example, whether cm status checks or dependency checks return true values on all endpoints. Log entries are made for any endpoints that fail a check. You can use the verbose logging argument (-v) when you run a command in check mode. This produces a much more detailed report of any failed checks. Note: Check mode operations are only available if Inventory integration is enabled. Example Software Distribution Server Log This section contains examples of Software Distribution server log entries for the following distribution scenarios: v Example 1: Standard log entry for a successful install operation v Example 2: Distribution of a software package containing a Solaris package v Example 3: Change Management Status Database Disabled v Example 4: Install operation in preview mode on page 299 v Example 5: Install operation in check mode on page 299 v Example 6: Install operation without the force option on page 300 v Example 7: An install operation where some of the specified targets are no longer valid on page 300 v Example 8: An execute user program whose timeout has expired and program has not completed on page 301 v Example 9: An Execute User Program action with a timeout setting of -1 on page 302 Example 1: Standard log entry for a successful install operation: is the standard log entry for a successful install operation. ***************************************************** Software Package: "file.1.0" Operation: install Mode: not-transactional,not-undoableforce Time: :46:23 ========================== The following Example 2: Distribution of a software package containing a Solaris package: The following is the log entry for the successful distribution of a software package containing a Solaris package. Software Package: "Net.478.solaris" Operation: install Mode: not-transactional,not-undoable Time: :55:41 ================= lab16072-sun: DISSE0155I Distribution ID: ` DISSE0029I Current software package status is IC---. DISSE0005I Operation successful. Example 3: Change Management Status Database Disabled: A message similar to the following would be recorded in the log if the change management status is disabled when an install operation is carried out. Software Package: "a.1" Operation: install Mode: not-transactional,not-undoable force Time: :28:02 ================= 298 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

319 Logs: Software Package DIS:SENG:0175 The following warning messages occurred before the distribution was submitted: -> FRWTT0003E An instance named "SwdistCMSTATUSupport" of resource "distinguished" was not found. ================= Software Package: "a.1" Operation: install Mode: not-transactional,not-undoable force Time: :28:05 Log File: lab15056:/tivoli/usr/local/tivoli/bin/swdis/work/a.1.log ================= lab16012-wnt: Operation successfully submitted. Distribution ID is ================= Software Package: "a.1" Operation: install Mode: not-transactional,not-undoable force Time: :28:16 ================= lab16012-wnt: Distribution ID: ` Current software package status is IC---. Operation successful. Example 4: Install operation in preview mode: The following is an example of log entries for an install operation run in preview mode. ***************************************************** Software Package: "file.1.0" Operation: install Mode: Preview Time: :50:13 ========================== Actions to be performed: add directory c:\newfiles add file c:\newfiles\file1.txt ========================== Example 5: Install operation in check mode: The following is an example of log entries for an install operation run in check mode. ***************************************************** Software Package: "file.1.0" Operation: install Mode: not-transactional,not-undoable Time: :55:17 ========================== List of targets for which the requested operation cannot be submitted: endpt1 Failed dependency check. endpt2 Failed dependency check. ========================== The following is an example of log entries for the same install operation run in check mode with verbose logging. ***************************************************** Software Package: "file.1.0" Operation: install Mode: not-transactional,not-undoable Time: :55:17 ========================== endpt1 ** Dependency Checking : Dependency check $(installed_software) == file^1.0 for package dep.1.0 failed $(installed_software) == "file^1.0" [ false ] Chapter 15. Troubleshooting 299

320 Logs: Software Package ** Versioning : The package `dep.2.0 is a later version in state `IC---. The requested operation is not allowed for the software package dep endpt2 ** Dependency Checking : Dependency check $(installed_software) == file^1.0 for package dep.1.0 failed $(installed_software) == "file^1.0" [ false ] ============================== Example 6: Install operation without the force option: The following is the log entry for a software package distributed without specifying force to a target system on which the same software package has already been installed. The log shows that the current status of the software package is already IC---. ================= Software Package: "Testcase3.8.4" Operation: install Mode: not-transactional,not-undoable Time: :14:48 Log File: lab16185:c:\tivoli\bin\swdis\work\testcase3.8.4.log ================= lab16212-sles8: DISSE0074I Operation successfully submitted. Distribution ID is ================= Software Package: "Testcase3.8.4" Operation: install Mode: not-transactional,not-undoable Time: :14:50 ================= lab16212-sles8: DISSE0155I Distribution ID: ` DISSE0029I Current software package status is IC---. DISSE0005E Operation unsuccessful. DISSE0316E The following error messages have been generated during software package Testcase3.8.4 status validation: DISSE0028E The requested operation is not allowed for the software package Testcase3.8.4 due to a validation failure. ================= Example 7: An install operation where some of the specified targets are no longer valid: The following is the command line message received and the log entry for a software package sent to a number of targets specified in a text file in which some targets are no longer valid. With the continue_on_invalid_targets key set to y, the distribution continues on valid targets and logs a message to the Software Distribution server log for targets not valid. Message received after submitting command from command line with continue_on_invalid_targets enabled: C:\test_cli>winstsp -f -t y -u y -T `lab16109-aix#lab16037-region is neither the name of profile manager nor the name of a resource that is capable of receiving a software package distribution. The name you provide must be a fully specified name (starting with `@ ) or a name relative to the current working collection. if continue_on_invalid_targets=y C:\>winstsp -f -t y -u y -T DISSE0576W The operation failed on some of the targets (or subscribers) specified. Check the Software Distribution log file for further details. DISSE0074I Operation successfully submitted. Distribution ID is IBM Tivoli Configuration Manager: User s Guide for Software Distribution

321 Logs: Software Package Log file entry: ================= Software Package: "testcase1.0" Operation: install Mode: transactional undoable force Time: :21:24 ================= DISSE0575I Some of the targets (or subscribers) specified are not valid. The requested operation cannot be submitted on the following subscribers: lab16109-aix#lab16037-region lab16212-ulinux#lab16185-region ================= Software Package: "testcase1.0" Operation: install Mode: transactional undoable force Time: :21:30 Log File: lab16185:c:\tivoli\bin\swdis\work\testcase1.0.log ================= lab16212-ulinux#lab16037-region: lab16074-rh#lab16037-region: lab16074-rh: lab15158-sun#lab16037-region: lab15158-sun: DISSE0074I Operation successfully submitted. Distribution ID is ================= Software Package: "testcase1.0" Operation: install Mode: transactional undoable force Time: :21:36 ================= lab16074-rh: DISSE0155I Distribution ID: ` DISSE0029I Current software package status is IPU--. DISSE0001I Operation successful. ================= Software Package: "testcase1.0" Operation: install Mode: transactional undoable force Time: :21:37 ================= lab15158-sun: DISSE0155I Distribution ID: ` DISSE0029I Current software package status is IPU--. DISSE0001I Operation successful. ================= Example 8: An execute user program whose timeout has expired and program has not completed: The following is a log entry for a software package containing an execute program action in which the timeout specified for the program has expired and the program has not yet completed. ================= Software Package: "executeuserprogram.1" Operation: install Mode: not-transactional,not-undoable force Time: :51:30 Log File: lab16105:c:\tivoli\bin\swdis\work\executeuserprogram.1.log ================= lab16043_suse8.1: DISSE0074I Operation successfully submitted. Distribution ID is ================= Software Package: "executeuserprogram.1" Operation: install Mode: not-transactional,not-undoable force Time: :51:43 ================= Chapter 15. Troubleshooting 301

322 Logs: Software Package lab16043_suse8.1: DISSE0155I Distribution ID: ` DISSE0029I Current software package status is IC--E. DISSE0005E Operation unsuccessful. DISSE0283E Timeout of 5 seconds has expired. DISSE0123E Unable to execute or complete execution of program during_install - /tmp/script.sh (). ================= Example 9: An Execute User Program action with a timeout setting of -1: The following is a log entry for a software package containing an execute program action in which the timeout is set to -1. A program timeout equal to -1 indicates that the value set for send_timeout in the swdis.ini file must be used as the program time out. When this timeout expires, the distribution goes to an INTERRUPTED status. When a retry occurs and the program is still running, a warning message is returned to the server as follows ================= Software Package: "executeuserprogram.1" Operation: install Mode: not-transactional,not-undoable force Time: :51:43 ================= lab16041-nt: Distribution ID: ` Current software package status is ----C. Warning: operation may not succeed. Check the message log. Program C:\scen1.cmd is still running; session timeout expired Data Moving Logs The Data Moving log file is called DataMovingRequests.1.log. It is written in the working_dir defined in the swdis.ini file (see Checking Configuration Files on page 294 for more details about the swdis.ini file). The log file traces all actions performed by the Data Moving service. Example Log The following is an example of a Data Moving log for the submission of a send request and its execution, the submission of a retrieve request and its execution, and the submission of a delete request and its execution. Software Package: "DataMovingRequests.1" Operation: send Origin Host: vienna Origin file: <default_path>\sample.txt Time: :19:52 Log File: vienna:d:\tivoli\bin\swdis\work\datamovingrequests.1.log Operation successfully submitted. Distribution ID is ================= Software Package: "DataMovingRequests.1" Operation: send Origin Host: vienna Origin file: D:\Tivoli\db\vienna.db\sample.txt Time: :20:03 Log File: vienna:d:\tivoli\bin\swdis\work\datamovingrequests.1.log ================= linz: Distribution ID: ` Operation successful. Operation (send) completed: destination file: (D:\Tivoli\swdis\1\sample.txt). ================= 302 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

323 Log Object List A software package can contain a stanza, the log_object_list stanza, which stanza enables you to create an SPD log file on the target system. The log file contains the actions and results of the change management operations performed on the software package. The log file, in the format package-name.version.log, is written to the target in a directory specified in the stanza and by default, it is overwritten for each distribution of the software package. Refer to the Reference Manual for Software Distribution for information about the attributes that can be defined in this stanza. The following is an example of the log entry on an endpoint where a software package has been installed containing add directory and file actions: ================= Software Package: "SPack2^0" Operation: install Mode: not-transactional force Time: 07/10/ :47:20 PM [success] add directory C:\test\C_\myfolder\data1 [success] add file \myfolder\data1\data1.txt [success] add file \myfolder\data1\appl.ini Notices and Mail Both Notice and Mail supply information similar to that provided by a non-verbose log. Notice is controlled by the post_notice attribute of the SPD file, which is set to yes by default. In addition to setting this attribute you must also run the wsetspop P true spobj_name command. Mail is controlled by the mail_id attribute of the SPD file. Mail can only be sent if a valid address is supplied for this attribute. Both the post_notice and mail_id attributes can be set by the wsetspop command, using the -P and -m arguments. Notices are sent to the Software Distribution 4 notice group of the Tivoli Management Framework Notification utility. To read the notices, you must be subscribed to the group. Notices and mails are sent on submission of a software package operation and after completion of the operation. The following example shows a notice or mail sent on submission of an install operation. ***************************************************** Operation: install Mode: not-transactional,not-undoableforce Time: :46:23 Log File: myloghost:d:\tivoli\bin\swdis\work\file.1.0.log ========================== Operation successfully submitted. Distribution ID is ========================== Logs: Software Package The following example shows a notice or mail sent on completion of an install operation. Chapter 15. Troubleshooting 303

324 Logs: Notices and Mail ***************************************************** Operation: install Mode: not-transactional,not-undoableforce Time: :46:23 Log File: myloghost:d:\tivoli\bin\swdis\work\file.1.0.log ========================== Distribution ID: Succeeded on hosts: endpt1 Failed on hosts: <none> ========================== Tivoli Enterprise Console If the Tivoli Enterprise Console is installed and the related integration is active, Software Distribution operations can be monitored in the same way as other events. A Software Distribution operation triggers three events on the Tivoli Enterprise Console, as follows: v Before the check in the configuration repository v Before submission v On completion Upon completion of a Software Distribution operation, error messages for failed distribution operations are returned to the distribution log, and a Tivoli Enterprise Console event is sent to the Enterprise Console. This information is assigned to the msg_list event attribute. The error message posted to the msg_list might be truncated due to character size limits. The more significant messages are listed first. See Chapter 12, Integrating the Tivoli Enterprise Console, on page 263. For software packages containing executable programs or scripts, the Tivoli Event Console also returns the related change management operation performed, the operation phase, and the exit code of the program for failed and successful distribution targets. This information is assigned to the failed_target_exit_code and successful_target_exit_code. Configuration Repository During a software distribution operation, changes are made to information stored in the configuration repository, as follows: v The SD_INST value for the software package on each target is changed. When the operation starts, the five character CM_STATE string is changed so that the final character is set to C to indicate a changing status. When the operation is completed, the CM_STATE string is set to its new value. For example, IC--- if an install and commit operation has been performed or IP--- if an install transactional operation has been performed. v The SD_H_INST table (historical database) is updated with the new information. For failed distributions, error messages are written to the MESSAGES field in the SD_H_INST inventory table. The error message written in the MESSAGE field might be truncated due to character size limits. Inventory integration must be enabled for this information to be updated. You use the wswdmgr command to enable the integration. 304 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

325 Logs: Configuration Repository Examining the SPD File In addition, targets of the operation must have been scanned using Inventory. If this has been done, the sd_scan.nfo file is stored in the lcf installation directory. Note: No information about data moving operations is reported to the configuration repository. If you can successfully distribute one software package, but are unable to distribute a similar one, examine the software package definition (SPD) file. The SPD file enables you to view every property and option set for a software package. In particular, verify the following in the software package: v Check that file names and directories are correctly referenced in the add and remove file and directory stanzas v Check that files, programs, and other software package objects referenced in the software package are located on the source host v Ensure that the source host is correctly specified in the source_host_name attribute (the default is the Tivoli management region server) You can use the wgetspat command to obtain information about the following attributes of a software package: v Whether or not you can execute a committable operation on the package. If this attribute is set to y, the operation must be performed in transactional mode. v The source host. v Whether or not the operation is a lenient distribution. v The default server mode, for example, all, source, repair, force. v The default mode for the operation, for example, undoable, transactional. v The default operation, for example, install, remove. v The source path where the software package block is located. v The format of the software package file, for example, built. v Whether or not you can execute an undoable operation on the package. v Access permissions to the package when using the Web Interface module. v The path to the working directory of the distribution server. v Package dependencies, versioning and nested software packages Troubleshooting the Software Package Editor GUI If you experience performance problems when using the Software Package Editor, verify the following conditions: v Enable host access. Before launching the Software Package Editor on a UNIX system, enable host access to the X server by entering the xhost + command. v Different domains. If the Software Package Editor is on a managed node that is installed on a network domain different from the Tivoli management region domain, to start the Software Package Editor, you must specify on the Tivoli management region, the domain where the managed node resides. To specify a new domain on a UNIX Tivoli management region, add an entry to the /etc/resolv.conf file. To specify a new domain on a Windows Tivoli Management region, add the required DNS to the DNS list for the TCP/IP settings. Chapter 15. Troubleshooting 305

326 Troubleshooting: Examining the SPD File v Accessing remote drives. Performance of the Software Package Editor can be degraded if remote drives that were not accessible when the Software Package Editor was launched have since been mapped to the machine. v Large software packages. Any operation launched from the Software Package Editor hangs if the software package being processed is too large. To correct the problem, tune the mx100m value in the speditor.bat file. Increase the value gradually by small increments until you find the optimal value for your environment. For example, replace mx150m with mx200m and then continue to increase this value until the machine performance improves. v OS/2 machines, when specifying file names, use only.cmd or.exe files, because.bat files are not supported. Checking Repeaters, Gateways, and Endpoints Software Distribution relies on the MDist 2 service of the Tivoli Management Framework. This MDist 2 service, enabled through the use of repeaters, is configured with the wmdist command. Several arguments of this command may help you troubleshoot problems with your network. See the Tivoli Management Framework: User s Guide for more information. Many distribution problems are caused by problems transmitting the package along the chain of repeaters to the endpoints that are the targets of a distribution. Failures occur, for example, because a connection is lost between an endpoint and its gateway, a distribution times out because of performance problems, or a user program fails or does not complete. The following list provides some examples of distribution failures that are symptoms of problems with the distribution network of repeaters, gateways, and endpoints: v You can successfully distribute a software package to one endpoint but a distribution to multiple endpoints fails. Ensure that the repeaters are optimized and configured correctly. v You have network storms. Use the wmdist command to examine the MDist 2 parameters and to change them if necessary. In particular, check the value of the max_sessions_high, max_sessions_medium, and max_sessions_low parameters, which set the number of allowable connections: high-priority (default: 5), medium-priority (default: 10), and low-priority (default: 40) connections, respectively. v If you can no longer distribute to an endpoint to which you previously were able to send distributions, ensure that the endpoint is connected to its gateway and is active. v Distribution times out. If the distribution times out, check the values for send_timeout and execute_timeout using the wmdist command. v Distribution takes longer than expected. You can use the wmdist -I <gateway/repeater name> command to monitor the progress of loading the software package at each repeater (it gives the number of bytes transferred and the percentage complete). If you decide that performance is not optimal, you may decide to change the way in which your network is configured (netload). The wdepot command checks the existence of a package on the depot, and is useful if you are not interested in the level of completion. 306 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

327 Troubleshooting: Verifying Repeater Parameters You may also consider configuring a source host machine that is used continually as a repeater. By configuring the source host as a repeater, you can tune the communication parameters of the machine so that the software package is routed directly from the source host to its gateway. This saves time and network load. For more information on the use of the above commands, see the Tivoli Management Framework: Reference Manual. Setting Timeout Values for a Distribution Setting distribution timeout parameters enables you to specify a time interval after which either the server or client interrupts a distribution. These timeouts include the following: v Repeater timeout sets the parameter to specify a timeout value for connections between a repeater and its endpoints or between repeaters. This value is set individually for each repeater using the wmdist s command. v User program timeout sets the timeout keyword in the SPD file to specify a timeout value for user programs running on the client. Repeater Timeout There are two attributes that impact the total timeout for a repeater: send_timeout This is the time allowed for the transmission of the package across a network. If a transmission times out, the distribution remains in the repeater queue and attempts to resend after the interval defined in the conn_retry_interval attribute. execute_timeout This is the time allowed between the end of the transmission and the return of results to the repeater. This period allows for running any post-transmission scripts on the target. Note: When retrieve and send from endpoint to endpoint operations are performed, the software package is built on the endpoint. As this operation can require a longer amount of time than the default timeout value allows for, set a higher timeout value. You can set the send_timeout and execute_timeout attributes at the repeater level by using the wmdist s command, as follows: wmdist -s <repeater_name> send_timeout=<seconds> wmdist -s <repeater_name> execute_timeout=<seconds> For more information on the syntax and usage of the wmdist command, see the Tivoli Management Framework: Reference Manual. You can override the values for send_timeout and execute_timeout set at repeater level in the following ways: v By defining values for the mdist2 send_timeout and execute_timeout attributes, using the l argument in the following Software Distribution commands: waccptsp wcommtsp winstsp wldsp Chapter 15. Troubleshooting 307

328 Troubleshooting: Setting Timeout Values for a Distribution wremovsp wspmvdata wsyncsp wuldsp wundosp wversp For more information on Software Distribution commands, refer to Reference Manual for Software Distribution. v By setting user program timeouts for any programs that you include in the following stanzas of the SPD file: execute_user_program execute_installshield_program execute_mssetup_program execute_cid_program lcf_before_program_timeout lcf_after_program_timeout Rules for calculating the total user program timeout and the circumstances in which the user program timeout replaces either the send timeout or the execute timeout are explained in User Program Timeout. v By changing the timeout keyword in the swdis.ini file for the endpoint. The default value for this keyword is 300 seconds. User Program Timeout You can set a timeout attribute when you specify a program to be executed as part of a software distribution. You do this by defining an execute_user_program, execute_installshield_program, execute_mssetup_program, execute_cid_program, lcf_before_program_timeout, or lcf_after_program_timeout stanza. This attribute can override either the send_timeout or execute_timeout attribute of the repeater. Which of the repeater timeouts is overridden depends on where the execute program action is defined in the software package. If the execute program action is inserted within the software package, the send_timeout attribute is set. If the execute program action is inserted at the end of the package, the execute_timeout attribute is set. The value of this attribute can be set to either a number of seconds or to -1. Setting the timeout to -1 indicates that the user program timeout should be set to the highest value between the send_timeout attribute of the swdis.ini file on the endpoint and the repeater timeout setting. The program timeout is calculated as the sum of the timeouts for each executed phase. However, if any of the timeouts included in the sum is set to -1, the program timeout is set to -1. A program timeout equal to -1 indicates that the value set for send_timeout in the swdis.ini file must be used as the program time out. When this timeout expires, the distribution is in an INTERRUPTED status. When a retry occurs and the program is still running, a warning message is returned to the server. The package status is kept to a changing value, for example, C. If the program completes, the operation is successful only if all the data has been sent from the gateway, otherwise, it fails. The local catalog on the endpoint is updated. At the next software distribution operation, the status of the package is updated on the server database. 308 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

329 Troubleshooting: Setting Timeout Values for a Distribution Note: In the case of the operations preferably-not-transactional, preferably-undoable, and preferably-not-in-a-reboot, which can behave differently based on the situation, the worst case is considered. This means that the timeout is calculated based on the situation which will take the longest period to complete. For example, the operation wundosp to (undo in a preferably-not-transactional mode) is calculated to the same timeout as wundosp tn (undo in a not-transactional mode), not to the timeout of wundosp -ty, where user programs are not executed and the timeout is shorter. The program timeout replaces the appropriate repeater timeout only when the program timeout is greater than the repeater timeout. For example, a program is inserted at the end of a software package and the following timeouts are set: v repeater execute_timeout (set by wmdist -s) = 600 v during_install timeout for the program = 1200 v during_cleanup timeout for the program = 1200 In this case, the sum of the user program timeouts is equal to 2400 seconds and so exceeds the execute_timeout set for the repeater. Therefore, the execute timeout is set to 2400 seconds. However, if one of the user program timeout settings is changed to -1, the total becomes -1 and so is replaced by the send_timeout from swdis.ini (300 seconds). The program timeout is now 300 seconds, and so less than the repeater timeout of 600 seconds. The repeater timeout is retained. Verifying Setup for Endpoints You can verify the setup of endpoint systems when trying to distribute software packages. This can include: v Verifying the endpoint connection. The wep command provides a list of all endpoints in a TMR and their assigned gateways, retrieves and sets endpoint information, migrates an endpoint from one gateway to another, or updates any endpoint data changes within a TMR. This command lists information in the endpoint list that is maintained by the endpoint manager. v Verifying endpoint configuration settings. You can use the web to check the endpoint configuration settings by sending the following URL from your browser: Then click Show Config Settings to show the configuration settings, as in the following example: ********************************************* lcfd_port=9495 lcfd_preferred_port=9495 fail_if_pref_port_busy=0 gateway_port=9242 protocol=tcpip wol_enable=0 bcast_disable=0 http_disable=0 log_threshold=3 start_timeout=120 run_timeout=120 lcfd_version=41003 logfile=c:\program Files\Tivoli\lcf\dat\1\lcfd.log config_path=c:\program Files\Tivoli\lcf\dat\1\last.cfg Chapter 15. Troubleshooting 309

330 Verifying Setup for Endpoints Checking lost-n-found run_dir=c:\program Files\Tivoli\lcf\dat\1 load_dir=c:\program Files\Tivoli\lcf\bin\w32-ix86\mrt lib_dir=c:\program Files\Tivoli\lcf\bin\w32-ix86\mrt cache_loc=c:\program Files\Tivoli\lcf\dat\1\cache cache_index=c:\program Files\Tivoli\lcf\dat\1\cache\Index.v5 cache_limit= debug_flags=0 log_queue_size=1024 log_size= udp_interval=300 udp_attempts=6 address_notif_interval=0 login_interval=1800 lcs.machine_name=lab15189-w2k lcs.machine_unique_id=5btjxfcppm20thph6zrn000005a9 lcs.crypt_mode= lcs.crypt_key_len=0 lcs.mode=0x0 lcs.interp=w32-ix86 lcs.login_interfaces= lcs.gateway_address= preload_loc= lcfd_alternate_port=9496 local_ip_interface= login_mode= start_delay=0 ************************************************* The endpoint_name is the hostname of the endpoint and the endpoint_port_number is the lcfd port number. v Verifying the gateway/repeater log which are located in the following paths, respectively $DBDIR/gatelog and $DBDIR/rpt2log. Use the wmdist command to change the debug level for a repeater to show the maximum information: wmdist -s <repeater> debug_level=9 If the node is also a gateway, you can set the set_debug_level attribute to the wgateway command to track information about the gateway (the maximum level is 9). The wgateway command lists gateway object identification numbers, gateway names, and status within a TMR. The format is: wgateway <gateway> set_debug_level 9 If a software package object no longer appears in a profile manager on your desktop, it may have been moved to the lost-n-found collection because it was found to be inconsistent. Tivoli Management Framework provides a lost-n-found collection on the server to store database objects that are "orphaned" due to broken links or lost data. Tivoli Management Framework transfers software packages that have encountered one of the following problems to the lost-n-found collection: v The software package source host no longer exists. v The log host no longer exists. In any of these cases, the wchkdb method moves the software package to the lost-n-found collection. Use the wls /lost-n-found command to list the contents of this collection. Check the notice groups to determine why the software package was moved a notice is generated anytime a software package is moved to the lost-n-found collection. Use the wmvspobj command to move the software 310 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

331 Troubleshooting: Checking lost-n-found package from the lost-n-found collection to a profile manager. Finally, correct the problem that initially moved the software package before distributing it. See Checking Object Consistency in the Reference Manual for Software Distribution for a full description of the lost-n-found feature. Checking the Default Directory on a Target System When specifying software package options to set platform-specific information, you must designate a valid destination directory path where the distributed files will reside on the target system. You can view the settings for any endpoint over the web, as described in Verifying Setup for Endpoints on page 309. Check in the appropriate default directory (as defined by the run_dir parameter) if you have distributed a software package without error and cannot locate the distributed data. Resolve the error, which may have been caused by an environment variable with an incorrect value or without a value at all, and either reinstall the package or copy the data from the default location to the desired destination directory, as appropriate. Chapter 15. Troubleshooting 311

332 Troubleshooting: Checking the Default Directory 312 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

333 Part 3. Appendixes Copyright IBM Corp. 2002,

334 314 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

335 Appendix A. Accessibility Accessibility features help users who have physical disabilities, such as restricted mobility or limited vision, to use software products successfully. The major accessibility features in this product enable users to do the following: v Use assistive technologies, such as a screen-reader, to hear what is displayed on the screen. Consult the product documentation of the assistive technology for details on using those technologies with this product. v Operate features using only the keyboard. v Magnify what is displayed on the screen. In addition, the product documentation includes the following features that enable the use of a screen-reader, thereby aiding accessibility: v All documentation is available in both HTML and convertible PDF formats. v All images in the documentation are provided with alternative text so that users with vision impairments can understand the contents of the images. Navigating the Interface Using the Keyboard Standard shortcut and accelerator keys are used by the product and are documented by the operating system. Refer to the documentation provided by your operating system for more information. Using Software Distribution Java-based GUIs you press the Tab key to select GUI buttons. Perform the function related to the selected button by pressing: v Enter for the default selection v The spacebar for all other selections Additional keyboard shortcuts that you can use to navigate inside windows follow. Software Package Editor The following table lists the additional keyboard shortcuts that you can use to navigate inside the windows of the Software Package Editor: Table 18. Keyboard shortcuts for the Software Package Editor Shortcut Ctrl+P Ctrl+Y Function Performed Opens the properties dialog for the selected object Repeats the previous operation. Magnifying What Is Displayed on the Screen You can enlarge information on the product windows using facilities provided by the operating systems on which the product is run. For example, in a Microsoft Windows environment, you can lower the resolution of the screen to enlarge the font sizes of the text on the screen. Refer to the documentation provided by your operating system for more information. Copyright IBM Corp. 2002,

336 Accessibility Enabling the IBM Home Page Reader to Function with the Software Package Editor To enable the IBM Home Page Reader to function with the Software Package Editor, you must add the path to where the Java Runtime Environment (JRE) is installed to the PATH system environment variable. The JRE is installed with the Tivoli_JRE_$INTERP.spb software package. For example, if you are working in a Windows environment, add the following path to the PATH system environment variable: C:\Program Files\Tivoli\JavaTools\JRE\1.3.0\jre 316 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

337 Appendix B. Using Deployment Services with Software Distribution Activity Planner Change Manager This appendix outlines where you can find information related to the IBM Tivoli Configuration Manager, Version services, which are the following: v Activity Planner v Change Manager v Web Interface (Distributions Across Firewalls) v Resource Manager v Enterprise Directory Query Facility v Pristine Manager Information related to these services is available from the following sources: v Introducing IBM Tivoli Configuration Manager. This provides an overview of some of the services. v IBM Tivoli Configuration Manager: Planning and Installation Guide. This includes information about how to install the service. v IBM Tivoli Configuration Manager: User s Guide for Deployment Services. This includes information about how you use the service. v IBM Tivoli Configuration Manager: Messages and Codes. This provides details of all messages generated by the IBM Tivoli Configuration Manager components and services. Activity Planner enables you to define a group of activities in an activity plan, submit the plan to be executed, and monitor the execution of the plan. Activities are single operations that are performed on a set of targets at specified times. Operations include Tivoli Management Framework Task Library tasks by default, and include Software Distribution and Inventory operations if the corresponding plug-ins are installed. Activities contained in a plan can have dependencies associated with them which define circumstances under which the activity is executed. The execution of the operation defined in the activity is performed by the application to which the operation belongs. The group of activities forms the activity plan. Change Manager works with Activity Planner to manage specified groups of users, workstations, or devices as single subscriber entities. Change Manager allows users to create reference models that define hardware and software requirements for these subscribers. After a reference model is created, Change Manager can generate an activity plan that includes all the tasks required to ensure that the subscribers match the requirements defined in the reference model. These tasks can include software distribution and inventory operations, if the corresponding plug-ins are installed. The activity plan can then be submitted to Activity Planner for implementation. Copyright IBM Corp. 2002,

338 Using Deployment Services with Software Distribution Web Interface Resource Manager The Tivoli Configuration Manager Web Interface allows users on Microsoft and UNIX platforms to publish and remove web objects such as software packages, inventory profiles, and reference models, download and install software packages, run inventory scans, and synchronize reference models. Resource Manager enables you to manage resources in your Tivoli environment. Resources can be users and pervasive devices, such as Palm devices, Nokia 9200 Communicator series devices, and Windows CE devices. You can keep track of devices in your environment and customize their settings from a central location. You can also distribute software to and scan inventory of pervasive devices and the endpoints associated with users. Enterprise Directory Query Library Pristine Manager The Enterprise Directory Query Facility allows users to use information stored in Enterprise directories to create lists for software distribution or inventory scanning. It allows a Change Manager administrator to select a specific directory object or container of directory objects as subscribers to a Change Manager reference model. Leveraging the Automated Deployment Services (ADS) and the Microsoft Remote Installation Services (RIS) technology, you can use Pristine manager to: v Perform remote, unattended pristine installations without having to use a boot diskette on site v Install on machines that are already configured, for example, to reinstall the operating system or a new operating system from scratch. v Automatically install a Tivoli endpoint on a target machine. 318 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

339 Appendix C. Pristine Installations This chapter describes how the pristine tool can be used to make pristine installations. A pristine installation installs an operating system on a system where no operating system or other software is installed. The pristine tool enables you to: v Install an operating system on a pristine machine using a boot diskette v Specify installation and configuration information at a different time and place from when and where the software is being installed. Thus, the processes of preparation and installation can be approached as separate tasks. v Provide information for the installation process in a response file so that the installation can run almost completely unattended. With this release, IBM Tivoli Configuration Manager introduces the Pristine Manager which is similar to the pristine tool. The Pristine Manager enables you to: v Install an operating system on a pristine machine remotely and unattended. v Utilize Change Manager and Activity Plan Monitor, which reduces the number of complex configuration steps and offers more flexibility. v Define new machines in the Tivoli environment as endpoints so that Change Manager and Activity Plan Monitor can work with the machines as if they are Tivoli endpoints. v Reinstall the operating system or a new operating system on machines that are already configured. Refer to User s Guide for Deployment Services for more information about the Pristine Manager. The chapter is divided into three main sections: v Overview gives an overview of the pristine installation process v Windows Steps on page 323 describes how to make pristine installations of the supported Windows operating systems v OS/2 Steps on page 337 describes how to make pristine installations of the supported OS/2 operating systems Overview This section gives an overview of the pristine installation process and provides details of the prerequisites for the use of the tool. For information about installing the pristine tool, refer to Planning and Installation Guide. The pristine tool provides support for remote, almost completely unattended pristine installations, by preparing and storing operating system images and configuration information on a server, which can be accessed through the network by boot diskettes running on the pristine system. Pristine installations can be made of the following operating systems with the pristine tool: Windows 2000 Professional Windows XP Professional Copyright IBM Corp. 2002,

340 Pristine Installations: Overview OS/2 Warp Server 4.0 OS/2 Warp Server for e-business 4.5 Any additional operating system software or any other software should be installed using Software Distribution after the pristine installation has completed. Typical Network Environment A typical network environment has, apart from the pristine systems themselves, three essential elements: a pristine preparation site a code server, and a dedicated pristine gateway, as shown in the following figure: Figure 7. Pristine installation scenario Pristine Preparation Site The pristine preparation site is the system where the pristine tool is installed and running. It must be a Tivoli endpoint, in order for the pristine tool to be installed on it. Code Server The pristine tool on the pristine preparation site prepares the operating system code images and saves them on a code server, from which they can be accessed by the pristine installation process over the network, in a code server object. The pristine tool also adds code images of any other, non-operating system software, that is required by the installation process; for example, Tivoli management agent. Finally, the tool allows you to customize the response files for the operating system software and other required software. Separate code server objects can be created for each type of operating system to be installed, and, if necessary, more than one object can be created for each operating system, for example, for multiple language versions of the same operating system. The tool is also used to add configurations to each object. A configuration contains all the information that defines how a specific system or group of systems is to be configured, in terms of the following: 320 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

341 Pristine Installations: Overview v Customized operating system response file v Customized Tivoli management agent response file v Hard disk sizes (up to two hard disks) v Hard disk partitioning requirements v Optional Change Manager reference model to use, refer to User s Guide for Deployment Services for more information about Change Manager v Configuration notes For each configuration, a boot diskette (for OS/2 a set of three boot diskettes) is created. This diskette is transported to the appropriate pristine system where it is used to boot the system. The boot process accesses the code server and downloads the code images, response files and configuration files, and installs the operating system. Although shown in Figure 7 on page 320 as a separate system, the code server can be the same system as the pristine preparation site. Dedicated Pristine Gateway The final stage in the pristine process is to assign the pristine system to a dedicated pristine gateway (a Tivoli Enterprise gateway). If the Code Server Object configuration contains a reference model, and on the gateway a specific Login-Policy has been activated, a Change Manager operation will be started, for example, to install software on the pristine system. Prerequisites This section details the prerequisites for the code server, the pristine tool, the creation of the system diskette and the pristine system itself. Code Server Prerequisites The basic operating system requirements for the code server differ, whether you wish to install a Windows or an OS/2 operating system. Windows OS/2 To install any of the Windows operating systems detailed above, the code server must have Windows 2000 Professional installed. To install any of the OS/2 operating systems detailed above, the code server must be a system of the same type (for example, to install OS/2 4.0 on a pristine system the code server must be on an OS/2 4.0 system). Apart from the operating system prerequisites, the following are also prerequisites: v The code server must be an endpoint, or any system in the network to which the pristine system is connected. v Batch file utilities. Pristine Tool Prerequisites The pristine tool can be installed on any of the platforms that can be used as a code server, except that: v To prepare a pristine installation of a Windows operating system the tool must be installed on a Windows system. v To prepare a pristine installation of an OS/2 operating system the tool must be installed on an OS/2 system. Other prerequisites for the pristine tool are as follows: v The operating system images that you want to prepare must be available either from the operating system installation CD-ROMs or from hard disk. Appendix C. Pristine Installations 321

342 Pristine Installations: Prerequisites v CD-ROM drive for the operating system images (optional - images can also be loaded from a hard disk). v A diskette drive and, for each separate code server configuration, one blank diskette for Windows, or three blank diskettes for OS/2. v Code images must be available for the following required software: Windows OS/2 Tivoli management agent for Windows Tivoli management agent for OS/2 TCPIP MPTS Netscape (OS 4.0 only) Java (OS 4.0 only) System Diskette Creation Prerequisites The prerequisites for the system diskettes differ according to whether the diskette is for Windows or OS/2: Windows: v The first phase of the system diskette creation requires the use of the DOS format command and must be done on a system running native MS-DOS, Version 7.0 or higher. v The second phase uses the Network Client Administrator utility, which is provided with Windows NT Server, but which can also be manually installed (by copying the executable file) on other Windows platforms, such as Windows NT Workstation or Windows 2000 Professional. v The second phase also requires the use of the Windows NT Server CD-ROM. OS/2: The following Configuration, Installation and Distribution (CID) utilities must be available, in the appropriate versions for the platform to be installed: THINLAPS THINIFS CASINSTL SEDISK Pristine System Prerequisites The pristine system requires: v An appropriate network card and connection v A diskette drive Dedicated Pristine Gateway Prerequisites The dedicated pristine gateway can be any Tivoli Gateway, but it must be dedicated to the first-time registration of pristine systems. If you decide to use the Change Manager component to install software after the operating system has been installed, the gateway must have the following installed products: v Inventory Server and Gateway v Software Distribution Gateway v Managed Node component of the Change Manager component In addition, after these components have been installed you should: v Create a reference model in the Change Manager component to install software on the pristine system; the reference model name and version must be the same as that used in the code server object configuration 322 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

343 Pristine Installations: Prerequisites Windows Steps v Activate the login policy script by using the command: wputeppol login_policy < login_policy_pristine This section commences with an overview of the steps to be carried out if you wish to install any of the supported Windows operating systems on a pristine system. It then describes each of those steps in detail. Pristine Installation Scenario To prepare for and carry out one or more pristine installations, follow the steps detailed below: Step 1. Plan the installations you want to make, deciding which code server objects are required to be installed, and for each object how many separate configurations will be required See Step 1: Planning. Step 2. Use the Pristine tool to create the code server objects identified in 1 See Step 2: Creating and Maintaining Code Server Objects on page 324. Step 3. For each code server object use the pristine tool to create a configuration for each system or group of systems with similar characteristics, as determined in 1 See Step 3: Creating and Maintaining Code Server Object Configurations on page 329. Step 4. Prepare a system diskette for each configuration. See Step 4: Preparing a System Diskette on page 333. Step 5. Use the pristine tool to add to the system diskette information that points to the code server object, thereby creating a pristine boot diskette, for each configuration See Step 5: Creating a Pristine Boot Diskette on page 334. Step 6. Use the boot diskette to run a pristine installation, and optionally carry out Change Manager activities. Finally, migrate the new endpoint from the dedicated pristine gateway to a normal gateway. See Step 6: Running a Pristine Installation on page 335. If you intend to make pristine installations on a group of systems with the same configuration sequentially, you will need only one diskette for each configuration; if the systems are at remote locations and you want to carry out the pristine installations contemporaneously you will have to create a system diskette (Step 4) and subsequently transform it into a pristine boot diskette (Step 5) for as many systems for which you need contemporaneous installations. Step 1: Planning In this section you plan how to use the pristine tool to install an operating system on a pristine system. Planning for pristine installations considers two questions: v Which code server objects need to be created v Which configurations need to be created for each code server object Code Server Objects A code server object needs to be created for every version of every operating system you wish to install. If you work in a multi-language environment you should create a separate object for each language version of each system. A code server object comprises, apart from the configurations, just the code images for the operating system software and the required additional software (Tivoli management agent). Thus, if you only have one operating system image and one image for Tivoli management agent, you will only need one code server object. Appendix C. Pristine Installations 323

344 Pristine Installations on Windows: Planning The pristine tool allows you to modify code server objects, for example, in the event that a new version of Tivoli management agent becomes available, and to delete them when they are no longer required. Code Server Object Configurations Each code server object must have at least one configuration defined. A configuration contains the following information: v Customized operating system response file; the tool lets you modify the default response file supplied with the operating system, changing values, and adding or deleting sections and keys v Customized Tivoli management agent response file; the tool lets you customize the default response file in the same way v The size of the hard disks of the pristine system; up to two hard disks can be defined using the pristine tool - if the system has additional disks they must be partitioned and formatted manually after the pristine installation is complete v The partitioning requirements of the hard disks, including the drive letters by which each partition can be identified; the primary partition must be identified v The device drivers which are to be loaded onto the pristine system v The Change Manager reference model to use, if any; both the model name and the version number can be specified. Refer to User s Guide for Deployment Services for information about Change Manager reference models. v Configuration notes. You should determine this information for each pristine system to be installed and then create a separate configuration for each system or group of systems that has a unique combination of these values. Step 2: Creating and Maintaining Code Server Objects This section shows you how to use the pristine tool to create a code server object containing the code images of the supported Windows operating system, and of the Tivoli management agent that is required to be installed with the operating system. Using the pristine tool, you create a new code server object by doing the following: v Select the operating system to install on the pristine system. v Locate the source code images for the operating system. v Define the required location for the code server object on the code server (ensure that the code server is accessible in the network before commencing this procedure). v Enter any useful information about the code server object. v For each additional product required to be installed with the operating system (in the case of Windows only Tivoli management agent is required), locate the source code images. v Save the code server object. The tool also subsequently lets you modify any of the parameters you have defined, or to delete the object completely (if you delete the object you will not delete the original code images). Creating a New Code Server Object All operations using the pristine tool can be selected in the dialogs by any of these methods: v Select the item from the hierarchical menus. v Click on an icon in the toolbar. v Right click and select an item from the context-sensitive menu that is displayed. 324 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

345 Pristine Installations on Windows: Code Server Objects In order to avoid unnecessary repetition in the instructions that follow, all options are described as being selected from the hierarchical menus. In addition, you should note that items can be selected either by clicking on them or by using the tab and arrow keys to navigate around the dialog. The steps are as follows: 1. Start the pristine tool and the Configuration Manager Pristine Tool main window is displayed. 2. Optionally select the required operating system and select Tools -> New Code Server. The New Code Server Object dialog is displayed. Appendix C. Pristine Installations 325

346 Pristine Installations on Windows: Code Server Objects 3. Enter the name of the new code server object and click OK. The code server object setup dialog is displayed. 4. Under the General tab, enter the following identification information for the operating system image: Operating System If you did not select the operating system on the previous screen select it from this pull-down. Source path Select the source path from Table 19, enter the full pathname for the directory in which the operating system image is located, or click the ellipsis (...) button and browse for the source directory. Table 19. Source path location for operating system image on CD-ROM Operating System Windows 2000 Professional Windows XP Professional Source Path <CD-ROM>\I386 <CD-ROM>\I386 Destination path Enter the full path on the code server where the code server object is to reside. New destination path This field is only used to change the location of an existing code server object, so it should be left blank when creating a new object. 5. Select the Information tab if you want to add additional information about the code server object (for example, creator, date, purpose of the object). 326 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

347 Pristine Installations on Windows: Code Server Objects 6. Select the Products tab. 7. Click on the check box for Tivoli Management Agent. The <Tivoli Management Agent>: Source Directory Location dialog is displayed. 8. In the Source path field enter the path for the Tivoli management agent software image, either from the Tivoli Management Framework CD-ROM or from a hard disk location where you have previously copied it. The tool will propose a Destination Path which you are strongly advised not to alter. Click OK to save the settings and return to the code server object dialog. 9. Click the Apply button to update the object. A syntax check is performed to ensure the paths you have entered are valid and that there is enough room for the operating system image in the destination folder. If the destination folder is not found after this check, it is created. Appendix C. Pristine Installations 327

348 Pristine Installations on Windows: Code Server Objects The platform name and the object name is displayed in the Code Server created list: 10. Click Add if you want to create another code server object, and the New Code Server Object dialog is displayed (go back to step 3 on page 326); or click OK to return to the pristine tool main menu. Note: If you add another code server object, you must choose a platform from the Operating System drop-down list in the code server window. Editing a Code Server Object You can change all but one of the code server object parameters by selecting the object, selecting Tools-> Code Server, changing the value previously entered and selecting Apply. The exception is if you want to move the code server object to a new location: 1. Select a code server object in the Main dialog and then select Tools -> Code Server. 2. Select the object you want to edit from the Code Server Created list and click Edit. 3. Enter a new path in the New Destination Path text box. 4. Click Apply. A check is performed to ensure the paths you have entered are valid and that there is enough room for the operating system image in the destination folder. If there is, the code server object will be moved to the location identified in New Destination Path. 5. Click OK to return to the pristine tool main menu. Deleting a Code Server Object To delete a code server object perform the following steps: 1. Select a code server object in the Main dialog and then select Tools-> Code Server. 2. Select the object you want to delete from the Code Server created list and click Delete->Apply. A confirmation dialog box appears. Click Yes. The object is deleted. 328 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

349 Pristine Installations on Windows: Code Server Objects 3. Click OK to return to the main menu. Step 3: Creating and Maintaining Code Server Object Configurations For every code server object created you must create at least one configuration, which tells the pristine installation process how to configure the new operating system. The following actions are possible: v Customizing the Operating System Response File v Customizing the Tivoli Management Agent Response File on page 331 v Adding Device Drivers on page 331 v Partitioning the Client Hard Disk on page 332 v Defining a Reference Model on page 332 v Adding Configuration-Specific Information on page 333 Customizing the Operating System Response File The pristine tool provides you with an easy way to customize the response files that determine how the operating system will be installed. The default response files are located in the pristine tool s RSP subdirectory. These files can be edited using a text editor if you want to change the default values offered in the tool. 1. From the pristine tool main window, see the list of available code server objects by double-clicking the platform name. Select the object you want to configure. 2. Select File -> New Configuration. The Pristine Configuration dialog is displayed. Appendix C. Pristine Installations 329

350 Pristine Installations on Windows: Configurations 3. Enter a name for the configuration and click OK. The Configuration dialog is displayed. This dialog lets you customize the operating system response file. The left panel lists all of the sections in the response file. Select a section and its installation keys and their default values are displayed in the right panel. Full details of the sections and keys and their meaning should be found in the documentation for the operating system. Note: To select a section you are recommended to double-click on the section name; a single click may be sufficient, but on certain platforms the Java code that controls the user interface does not always respond to a single click 4. To change the value of an installation key: v Select a section v Double-click on the key for which the value is to be changed. The Installation Key dialog is displayed. v Edit the displayed value. v Click on OK to return to the Configuration dialog. 5. To add, remove or rename installation keys, do the following: a. Select a section b. Select an installation key (you do not have to do this if you are only adding a new key). c. Select Edit Key -> Key -> New, Delete or Rename. d. The appropriate dialog will be displayed allowing you to add, delete or rename the key, as appropriate. e. Click on OK to save the settings you have made and to return to the Configuration dialog. Note: While for many of the keys you can use their factory defaults, your attention is particularly drawn to the keys for the installation path, the 330 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

351 Pristine Installations on Windows: Configurations gateway port and the endpoint port which must be completed for both the operating system and for Tivoli management agent. 6. To add, remove or rename installation section names, do the following: a. Select the section (you do not have to do this if you are only adding a new section). b. Select Edit Key -> Section -> New, Delete or Rename. 7. Click on OK to save the settings you have made and to return to the Main dialog. Customizing the Tivoli Management Agent Response File From the Configuration dialog click on the No Product pull-down and select Tivoli Management Agent. The response file sections and keys for this product will be displayed and can be customized as described for the operating system response file, above. Adding Device Drivers For most pristine installations, the device drivers incorporated in the operating system software will be sufficient to enable the full operation of most pristine systems. However, if necessary, you can add to the code server object any device drivers that are required to be installed on the pristine system. For Windows 2000, this step is carried out by the pristine tool, as follows: 1. Select Configuration->Add new device driver. The Add New Device Driver dialog is displayed: 2. Click Add files and select the device driver file(s) to add. 3. Click Save to save the list of device drivers and return to the Configurations dialog. Remove a driver file by selecting the file and clicking Remove. Note: For Windows 2000 Professional, the driver files are added by default to a subdirectory called...\$oem$ within the destination operating system Appendix C. Pristine Installations 331

352 Pristine Installations on Windows: Configurations directory. However, if you need to add network adapter files, they should be added to...\$oem$\net, creating the subdirectory if necessary. Partitioning the Client Hard Disk You must define the partitions on the hard disks of the pristine system. Up to two hard disks can be partitioned. The steps are as follows: 1. Select Configuration ->Prepare hard disk. The Partition Hard Disk dialog is displayed: There are tabs for each of two physical volumes. On the first volume there is a default definition of a primary partition, with the drive letter C, of 2000 megabytes. 2. To change the primary partition size click on Size and change the value. 3. To add a partition, click Add. A new partition is created, with a default size of 2000 megabytes, using the next available drive letter. The Partition type defaults to Logical, but can be changed by clicking on the Partition type of the partition in question. The total of all partitions created is shown in the box at bottom right. To change the partition size click on Size and change the value. 4. Click OK to save the partitioning details and return to the Configurations dialog. Remove a partition by selecting the partition and clicking Remove and then OK. Defining a Reference Model In order to use Change Manager on the pristine system you are given the option of defining a reference model. The steps are as follows: 1. Select Configuration ->Reference Model. The Tivoli Pristine Configuration dialog is displayed: 2. Enter the reference model name and/or version. 332 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

353 Pristine Installations on Windows: Configurations 3. Click OK to save the reference model definition and return to the Configurations dialog. Remove a reference model definition by clicking Remove and then OK. Adding Configuration-Specific Information Configuration-specific information can be added to the configuration. The steps are as follows: 1. Select Configuration ->Information. The Information dialog is displayed. 2. Enter the required information. 3. Click OK to save the information and return to the Configurations dialog. Step 4: Preparing a System Diskette For each code server object configuration you will need to create a system diskette that will be used in Step 5: Creating a Pristine Boot Diskette.. You will use the standard diskette formatting command, and then the Network Client Administrator utility to add the files required by the client to establish a network connection with the Code Server. The steps are as follows: 1. Prepare a system diskette on a system running MS-DOS 7.0 or higher. At the DOS prompt, enter: format /s a: This prepares a formatted disk containing the required system files. 2. From the MS-DOS system, copy the following applications onto the diskette: v fdisk.com v format.com v smartdrv.exe 3. On a Windows NT Server, or other Windows system with Network Client Administrator installed, run Network Client Administrator (on the Windows NT server select Start -> Administrative Tools -> Network Client Administrator). The Network Client Administrator dialog is displayed. 4. Select the Make Network Installation Startup Disk option button and click Continue. The Share Network Client Installation Files dialog is displayed. 5. In the Path field, enter the location of the CLIENTS directory in the root of the Windows NT Server CD-ROM. Alternatively you can use the ellipsis (...) button to browse for the folder. 6. The first time you run this procedure, select the Copy files to a New Directory, and then Share option button. This creates a new shared directory in a location of your choice (the default is c:\clients). Note: You can write diskettes subsequently from the shared directory that you created in the previous step by selecting Use Existing Shared Directory. The utility points to the copied files each time it is run. 7. Click OK. The Target Workstation Configuration dialog is displayed. 8. Select the appropriate type of disk drive for your system. 9. In the Network Client list box, select Network Client 3.0 for MS-DOS and Windows. 10. Choose a network adapter card from the list provided. If your network adapter is not included, select any of the cards listed. You can then copy the correct adapter files and make the appropriate modifications to the start diskette at a later stage (this is described in step 16 on page 334). Appendix C. Pristine Installations 333

354 Pristine Installations on Windows: System Diskette 11. Click OK. The Network Startup Disk Configuration dialog is displayed. 12. In the Computer Name, User Name, and Domain text boxes, enter the required details, and select the TCP/IP Network Protocol. 13. Select the Enable Automatic DHCP Configuration check box or type the appropriate data into the activated TCP/IP fields. 14. Insert the system diskette created in step 1 on page 333 into the diskette drive and click OK. A confirmation dialog box appears. 15. Click OK to create the boot diskette. 16. The system diskette has now been created and is ready to be used by the pristine tool to create a pristine boot diskette (see Step 5: Creating a Pristine Boot Diskette ). However, if your network card was not present in the adapter list, now do the following: a. Copy the appropriate DOS driver to the /NET directory on your start diskette. Attention: The PCI Token-Ring network adapter card is not supported. Do not copy DOS driver files for this card onto the diskette. b. Using a text editor, modify the netcard statement in the system.ini file in the /NET directory so that it reads: netcard=<new name>.dos c. Locate the oemsetup.inf file for your network card and open it using a text editor. Search for the options section and make a note of the card name. An example is shown below: ;************************************************* ; Define Option ;************************************************* [Options] IBMFE [OptionsText] IBMFE = "IBM 10/100 Ethernet PCI Adapter" d. Using a text editor, modify the drivername statement in the protocol.ini file in /NET directory so that it corresponds to the name you observed in the oemsetup.inf file. e. Save and close all files. Step 5: Creating a Pristine Boot Diskette When you have created at least one configuration for a code server object (see Step 3: Creating and Maintaining Code Server Object Configurations on page 329) and have prepared a system diskette (see Step 4: Preparing a System Diskette on page 333), you can use the pristine tool to transform the prepared system diskette into a pristine boot diskette. 1. From the toolbar, click Tools ->Create Boot Diskettes. A dialog specific to the Windows operating system for which you are preparing the pristine boot diskette is displayed: 334 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

355 Pristine Installations on Windows: Boot Diskette 2. Place the diskette you created in Step 4: Preparing a System Diskette on page 333, into the diskette drive. 3. Complete the following fields: Server name Share name User name Password Map drive Hostname of the code server Share name of the folder that contains the code server objects (i.e. the Destination Path) User name under which to login to the code server (usually Administrator) Password to login to the code server Select the drive letter to which the shared code server object directory is to be mapped Network protocol Select TCP/IP from the drop-down list 4. Click OK. The pristine tool writes the data to the system diskette, creating a pristine boot diskette. Step 6: Running a Pristine Installation When you have completed the preparation of the boot diskette for a system or group of systems (see Step 5: Creating a Pristine Boot Diskette on page 334), you can commence a pristine installation. The installation procedure carries out the following operations: v It uses the boot diskette to start up the pristine system and load a minimum system configuration into memory v It installs the necessary protocols to connect itself into the network and to locate the code server. v Using the configuration information it partitions the hard disks and commences to download and install the operating system software, using the response file to drive the installation. v Each system, or group of systems is assigned to a dedicated Tivoli gateway. Appendix C. Pristine Installations 335

356 Pristine Installations on Windows: Running an Installation v If the code server object configuration contains a reference model, and on the gateway a specific login-policy has been activated, a Change Manager operation will be started. When these activities are completed, the new endpoint must be migrated from the dedicated pristine gateway to a normal gateway. Pristine Installation Procedure A person must be present where the pristine systems are located. The tasks executed locally are: v Starting the system. v Removing the diskette when necessary. v Restarting the system if required. Once the diskette is ready and delivered to the person performing the local installation, the installation process can begin. When the first Tivoli management agent login is connected, an automatic notification of the presence of a new machine in the Tivoli management region takes place. If you have defined a reference model you should ensure that the Change Manager component is activated, in order to compare the new system to the appropriate reference model and to start the specific action. This action completes the pristine installation process. Note: If you want to use a reference model to install Software Distribution, you should remember to install any prerequisite software. The final step is for the pristine system administrator, who must, after all installation processes are completed, migrate the new endpoint from the dedicated pristine gateway to a normal gateway. 336 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

357 Pristine Installations on OS/2 OS/2 Steps This section commences with an overview of the steps to be carried out if you wish to install any of the supported OS/2 operating systems on a pristine system. It then describes each of those steps in detail. Pristine Installation Scenario To prepare for and carry out one or more pristine installations you will need to follow the steps detailed below: Step 1. Plan the installations you want to make, deciding which code server objects are required to be installed, and for each object how many separate configurations will be required See Step 1: Planning. Step 2. Use the pristine tool to create the code server objects identified in step 1 on page 323 See Step 2: Creating and Maintaining a Code Server Object on page 338. Step 3. Use the OS/2 utilities to add system files to each code server object you created in Step 2. See Step 3: Adding System Files to Code Server Objects on page 340. Step 4. For each code server object use the pristine tool to create a configuration for each system or group of systems with similar characteristics, as determined in step 1 on page 323. See Step 4: Creating and Maintaining Code Server Object Configurations on page 342. Step 5. Prepare a set of three system diskettes for each configuration. See Step 5: Preparing the System Diskettes on page 344. Step 6. Use the pristine tool to add to the system diskettes information that points to the code server object, thereby creating a set of pristine boot diskettes, for each configuration. See Step 6: Creating Pristine Boot Diskettes on page 345. Step 7. Use the set of boot diskettes to run a pristine installation, and optionally carry out Change Manager activities. Finally you will migrate the new endpoint from the dedicated pristine gateway to a normal gateway. See Step 7: Running a Pristine Installation on page 346. If you intend to make pristine installations on a group of systems with the same configuration sequentially, you will need only one diskette (set of diskettes for OS/2) for each configuration; if the systems are at remote locations and you want to carry out the pristine installations contemporaneously you will have to create a system diskette (Step 5) and subsequently transform it into a pristine boot diskette (Step 6) for as many systems for which you need contemporaneous installations. Note: To avoid repetition, the dialogs for the OS/2 version of the pristine tool have not been reproduced here; please refer to pages 324 to 334 for the corresponding dialogs in the Windows format. Step 1: Planning In this section you plan how to use the pristine tool to install an OS/2 operating system on a pristine system. Planning for pristine installations considers two questions: v Which code server objects need to be created. v Which configurations need to be created for each code server object. Appendix C. Pristine Installations 337

358 Pristine Installations on OS/2: Planning Code Server Objects A code server object needs to be created for every version of the operating system you wish to install (for OS/2 you can only prepare code server objects for the operating system on which the code server is installed). If you want to make pristine installations in a multi-language environment you should create a separate object for each language version of each system. A code server object comprises, apart from the configurations, just the code images for the operating system software and the required additional software (Tivoli management agent, TCPIP, MPTS, etc.). Thus, if you only have one operating system image and one image for each of the items of additional required software, you will only need one code server object. The pristine tool allows you to modify code server objects, for example, in the event that a new version of Tivoli management agent becomes available, and to delete them when they are no longer required. Code Server Object Configurations Each code server object must have at least one configuration defined. A configuration contains the following information: v Customized operating system response file; the tool lets you modify the default response file supplied with the operating system, changing values, and adding or deleting sections and keys v Customized additional required software response files; the tool lets customize the default response files in the same way v The size of the hard disks of the pristine system; up to two hard disks can be defined using the pristine tool - if the system has additional disks they must be partitioned and formatted manually after the pristine installation is complete v The partitioning requirements of the hard disks, including the drive letters by which each partition can be identified; the primary partition must be identified v The device drivers which are to be loaded onto the pristine system v The Change Manager reference model to use, if any; the model name and optionally the version number can be specified (refer to User s Guide for Deployment Services for information about Change Manager reference models. v Configuration notes You should determine this information for each pristine system to be installed and then create a separate configuration for each system or group of systems that has a unique combination of these values. Step 2: Creating and Maintaining a Code Server Object This section shows you how to use the pristine tool to create a code server object containing the code images of the supported OS/2 operating system and of the additional software that is required to be installed with the operating system. Using the pristine tool, you create a new code server object by doing the following: v Select the operating system to install on the pristine system. v Locate the source code images for the operating system. v Define the required location for the code server object on the code server (ensure that the code server is accessible in the network before commencing this procedure). v Enter any useful information about the code server object. v For each additional product required to be installed with the operating system, locate the source code images. v Save the code server object. 338 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

359 Pristine Installations on OS/2: Code Server Objects The tool also subsequently lets you modify any of the parameters you have defined, or to delete the object completely (if you delete the object you will not delete the original code images). Creating a New Code Server Object All operations using the pristine tool can be selected in the dialogs by any of these methods: v Select the item from the hierarchical menus v Click on an icon in the toolbar v Right click and select an item from the context-sensitive menu that is displayed In order to avoid unnecessary repetition in the instructions that follow, all options are described as being selected from the hierarchical menus. In addition, you should note that items can be selected either by clicking on them or by using the tab and arrow keys to navigate around the dialog. The steps are as follows: 1. Start the pristine tool and the Configuration Manager Pristine Tool main window is displayed. 2. Optionally select the required operating system and select Tools-> New Code Server. The New Code Server Object dialog is displayed. 3. Enter the name of the new code server object and click OK. The code server object setup dialog is displayed. 4. Under the General tab, enter the following identification information for the operating system image. Operating System If you did not select the operating system on the previous screen select it from this pull-down. Source path Select the source path from Table 20, enter the full pathname for the directory in which the operating system image is located, or click the ellipsis (...) button and browse for the source directory. Table 20. Source path location for operating system image Operating System OS/2 Warp Version 4.0 OS/2 Warp Version 4.5 Source Path <CD-ROM>\OS2IMAGE <CD-ROM>\OS2IMAGE Destination path Enter the full path on the code server where the code server object is to reside. New destination path This field is only used to change the location of an existing code server object, so it should be left blank when creating a new object. 5. Select the Information tab if you want to add additional information about the code server object (for example, creator, date, purpose of the object). 6. Select the Products tab. 7. Click on the check box of one of the additional required software items. The Install Directories dialog is displayed. 8. In the Source path field enter the path where the software image is located, either on the product CD-ROM or at a hard disk location where you have Appendix C. Pristine Installations 339

360 Pristine Installations on OS/2: Code Server Objects previously copied it. The tool will propose a Destination Path which you are strongly advised not to alter. Click OK to save the settings and return to the code server object dialog. 9. Repeat steps 7 and 8 for each of the additional required software items. 10. Click the Apply button to update the object. A syntax check is performed to ensure the paths you have entered are valid and that there is enough room for the operating system and software images in the destination folder. If the destination folder is not found after this check, it is created. The platform name and the object name is displayed in the Code Server created list. 11. Click Add if you want to create another code server object, and the New Code Server Object dialog is displayed (go back to step 3 on page 339); or click OK to return to the pristine tool main menu. Note: If you add another code server object, you must choose an OS/2 platform from the Operating System drop-down list in the code server window. Editing a Code Server Object You can change all but one of the code server object parameters by selecting the object, selecting Tools->Code Server, changing the value previously entered and selecting Apply. The exception is if you want to move the code server object to a new location: 1. Select a code server object in the Main dialog and then select Tools->Code Server. 2. Select the object you want to edit from the Code Server Created list and click Edit. 3. Enter a new path in the New Destination Path text box. 4. Click Apply. A check is performed to ensure the paths you have entered are valid and that there is enough room for the operating system image in the destination folder. If there is, the code server object will be moved to the location identified in New Destination Path. 5. Click OK to return to the pristine tool main menu. Deleting a Code Server Object To delete a code server object perform the following steps: 1. Select a code server object in the Main dialog and then select Tools->Code Server. 2. Select the object you want to delete from the Code Server created list and click Delete->Apply. A confirmation dialog box appears. Click Yes. The object is deleted. 3. Click OK to return to the main menu. Step 3: Adding System Files to Code Server Objects For each code server object you will need to add certain system files. In the examples below, the code server object folder (as entered in the Destination path field in step 4 on page 339) is shown as C:\CID. If you have used a different folder you should substitute your folder name. If you have more than one code server object you should apply the commands to each one (except THINSRV, which you run just once with a configuration file modified to refer to all code server objects). Before commencing, create a folder called log within each code server object folder. 340 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

361 Pristine Installations on OS/2: Adding System Files THINSRV THINSRV is an MPTS utility that extracts the necessary code server files, verifies supplied parameters, copies the necessary files to the target. In addition, it updates the config.sys and startup.cmd files on the code server workstation to automatically start the code server at system startup. To use the THINSRV program, perform the following steps: 1. Create the following directory: c:\cid\rsp\srvifs. 2. Before starting THINSRV, create the THINSRV configuration file, called default.ini, in the c:\cid\rsp\srvifs directory. An example of this file is shown below: Name = MHOLT1 GroupName = NO Adapter = 0 MaxClients = 50 MaxFiles = 100 ClientWorkers = 12 Path = c:\cid PermitWrite = NO PerClient = NO ; alias = ReadWrite,single,log,c:\cid\log Note: The folder in the Path statement is the folder where your code server object has been created. If you have more than one code server object you should add aliases for the other code server objects and their log folders to the bottom of this file. 3. Enter the following command in the command line: thinsrv /r:c:\cid\rsp\srvifs\default.ini /t:c:\srvifs /s:c:\cid\img\srvifs /tu:c:\ /l1:c:\cid\log\thinsrv.log This command copies the necessary code server files into the c:\srvifs directory. It also creates a valid default.ini file based on the response file named in the /r parameter. Note: The two characters after the slash at the beginning of the third line of the command as shown here are ell one. 4. If you are using OS/2 Version 4.5, you must add the following lines to c:\startup.cmd: cd srvifs service.exe /INI:default Configuring MPTS for Non-standard Network Adapters If a client system is using a network adapter that is unsupported by MPTS, for each created code server object you must update the MACS.ZIP file located in the C:\CID\IMG\MPTS\IBMCOM\MACS folder. To do this, perform the following steps: 1. Create a temporary directory in the root of the Code Server. In this example it is macstemp. 2. From within the macs folder, enter the following in the command line: pkunzip2 -d macs.zip c:\macstemp The contents of the MACS.ZIP archive are now unpacked to c:\macstemp. A number of subdirectories are now present under c:\macstemp. 3. Open c:\macstemp\ibmcom\macs and copy all the files required for your network adapter into this folder. Appendix C. Pristine Installations 341

362 Pristine Installations on OS/2: Adding System Files 4. Rebuild a new MACS.ZIP archive by entering the following: pkzip2 -rp macs.zip c:\macstemp\*.* 5. Copy the new MACS.ZIP archive back into C:\CID\IMG\MPTS\IBMCOM\MACS folder, overwriting the old archive. GETREXX REXX is required on the code server to run the LCU REXX command files used to install the requested products. Because the client workstation accesses the LCU command files from a redirected drive, it makes sense to access the required files for REXX from the code server. In this way, the required REXX modules do not have to be on the original boot diskettes. GETREXX enables the REXX modules to be copied from the OS/2 images to the code server executable directory and it is executed from the command line when you enter the following command: c:\cid\img\locinstu\getrexx c:\cid\img\os2image c:\cid\exe Step 4: Creating and Maintaining Code Server Object Configurations For every code server object created you must create at least one configuration, which tells the pristine installation process how to configure the new operating system. The following actions are possible: v Customizing the Operating System Response File v Customizing the Additional Required Software Response Files on page 343 v Adding Device Drivers on page 343 v Partitioning the Client Hard Disk on page 343 v Defining a Reference Model on page 344 v Adding Configuration-specific Information on page 344 Customizing the Operating System Response File The pristine tool provides you with an easy way to customize the response files that determine how the operating system will be installed. The default response files are located in the pristine tool s RSP subdirectory. These files can be edited using a text editor if you want to change the default values offered in the tool. 1. From the pristine tool main window, see the list of available code server objects by double-clicking the platform name. Select the object you want to configure. 2. Select File->New Configuration. The Pristine Configuration dialog is displayed. 3. Enter a name for the configuration and click OK. The Configuration dialog is displayed. This dialog lets you customize the operating system response file. The left panel lists all of the sections in the response file. Select a section and its installation keys and their default values are displayed in the right panel. Full details of the sections and keys and their meaning should be found in the documentation for the operating system. Note: To select a section you are recommended to double-click on the section name; a single click may be sufficient, but on certain platforms the Java code that controls the user interface does not always respond to a single click 4. To change the value of an installation key: v Select a section. v Double-click on the key for which the value is to be changed. The Installation Key dialog is displayed. 342 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

363 Pristine Installations on OS/2: Configurations v Edit the displayed value. v Click OK to return to the Configuration dialog. 5. To add, remove or rename installation keys, do the following: a. Select a section. b. Select an installation key (you do not have to do this if you are only adding a new key). c. Select Edit Key->Key->New, Delete or Rename d. The appropriate dialog will be displayed allowing you to add, delete or rename the key, as appropriate. e. Click OK to save the settings you have made and to return to the Configuration dialog. Note: While for many of the keys you can use their factory defaults, your attention is particularly drawn to the keys for the installation path, the gateway port and the endpoint port which must be completed for the operating system and for the additional required software. 6. To add, remove or rename installation section names, do the following: a. Select the section (you do not have to do this if you are only adding a new section). b. Select Edit Key-> Section-> New, Delete or Rename. 7. Click OK to save the settings you have made and to return to the Main dialog. Customizing the Additional Required Software Response Files From the Configuration dialog click on the No Product pull-down and select one of the additional required software items. The response file sections and keys for this product will be displayed and can be customized as described for the operating system response file, above. Repeat this action for each of the items in the pull-down. Adding Device Drivers For OS/2, device drivers are not added using the pristine tool. Instead you have already added them in Step 3: see Configuring MPTS for Non-standard Network Adapters on page 341. Partitioning the Client Hard Disk You must define the partitions on the hard disks of the pristine system. Up to two hard disks can be partitioned. The steps are as follows: 1. Select Configuration->Prepare hard disk. The Disk Partitioning dialog is displayed: There are tabs for each of two physical volumes. On the first volume there is a default definition of a primary partition, with the drive letter C, of 2000 megabytes. 2. To change the primary partition size click on Size and change the value. 3. To add a partition, click Add. A new partition is created, with a default size of 2000 megabytes, using the next available drive letter. The Partition type defaults to Logical, but can be changed by clicking on the Partition type of the partition in question. The total of all partitions created is shown in the box at bottom right. To change the partition size click on Size and change the value. 4. Click OK to save the partitioning details and return to the Configurations dialog. Remove a partition by selecting the partition and clicking Remove and then OK. Appendix C. Pristine Installations 343

364 Pristine Installations on OS/2: Configurations Defining a Reference Model In order to use Change Manager on the pristine system you are given the option of defining a reference model. The steps are as follows: 1. Select Configuration->Reference Model. The Reference Model dialog is displayed: 2. Enter the reference model name and/or version. 3. Click OK to save the reference model definition and return to the Configurations dialog. Remove a reference model definition by clicking Remove and then OK. Adding Configuration-specific Information Configuration-specific information can be added to the configuration. The steps are as follows: 1. Select Configuration->Information. The Information dialog is displayed. 2. Enter the required information. 3. Click OK to save the information and return to the Configurations dialog. Step 5: Preparing the System Diskettes To prepare the system diskettes you need to use the OS/2 system utilities SEDISK, THINLAPS, THINIFS and CASINSTL. In the examples below, the code server object folder (as entered in the Destination path field in step 4 on page 339) is shown as c:\cid. If you have used a different folder you should substitute your folder name. SEDISK SEDISK is an OS/2 utility that creates the system diskettes for starting the pristine system. By default, the diskettes have no LAN transport drivers or redirector code; these are added at a later stage. The SEDISK tool requires three formatted diskettes. To use SEDISK, perform the following steps: 1. In the directory where the SEDISK utility is located, launch SEDISK by entering the following: SEDISK /S:<source path> /T:<target drive> /S: Fully qualified source path to the OS/2 disk images, which can be on a local hard drive or a redirected drive. /T: Target drive (usually the A: drive). 2. Here is an example of how you use SEDISK to create a start disk: sedisk /s:c:\cid\img\os2image /t:a: This command launches SEDISK and creates three start diskettes using the OS/2 disk image in c:\cid\img\os2image. Adding the LAN Transport Driver with THINLAPS: You must add the appropriate network driver files to the start diskette. For this procedure, use THINLAPS: 1. From the three floppy disks you have created, insert the third diskette into the drive and enter the following command: thinlaps c:\cid\img\mpts A: <drivername>.nif 344 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

365 Pristine Installations on OS/2: System Diskettes Where <drivername>.nif is the filename that corresponds to the network adapter driver file that is stored on the target. 2. When asked for another disk, insert the second diskette (from the set of three) into the floppy drive. THINIFS and SRVIFS: THINIFS is an OS/2 utility that places all the necessary SRVIFS redirection files on the LAN transport diskette. SRVIFS is a small NetBIOS-based file server and requestor, which is shipped with MPTS. SRVIFS provides redirected I/O support to enable client access to a Code Server. This is a subset of the function provided by the LAN Server. Run THINIFS by doing the following: 1. From the set of three disks, insert the third disk you created into the drive and enter the following command from the command prompt: thinfs /s:c:\cid\img\srvifs /t:a:\ /srv:<code server name> /req:<pristine system name> /D:X /tu:a:\ When requested insert the second diskette. This provides the pristine system with the necessary information to connect to default directory on the code server. If you have a different directory you should modify the command accordingly. 2. Ensure that the LOG directory is read/write enabled, insert the third system diskette and enter the following to create an association between c:\cid\log and the client write drive: thinfs /s:c:\cid\img\srvifs /t:a:\ /srv:\\<code server name>\log /req:<pristine system name> /D:Y /tu:a:\ Adding the LAN CID Utility The LAN Configuration Installation and Distribution Utility (LCU), which is integrated with MPTS, enables you to chain together a series of CID installs. For example, an end user may require OS/2, MPTS, and LAN Server V5.0 to be installed. Once configured, this utility automatically installs all of these programs in one step. CASINSTL: This utility installs the LAN CID Utility on the system diskettes and is available from c:\cid\img\locinstu. To execute the CASINSTL program, insert the third system diskette and enter the following statement in the command line: casinstl /tu:a:\ /cmd:x:\clients\<configuration name> /D /l2:y:\srvifs_req.log /pa:x:\img\locinstu /pl:x:\exe;x:\img\locinstu; /0 /req:<pristine system name> Step 6: Creating Pristine Boot Diskettes When you have created at least one configuration for a code server object (see Step 4: Creating and Maintaining Code Server Object Configurations on page 342) and have prepared a set of system diskettes (see Step 5: Preparing the System Diskettes on page 344), you can use the pristine tool to transform the prepared system diskettes into a set of pristine boot diskettes. Note: This procedure, while being an essential step in the preparation for a pristine installation, may not need to update the system diskettes to create boot diskettes; thus, although you should have the system diskettes available you may not be asked to insert them. Appendix C. Pristine Installations 345

366 Pristine Installations on OS/2: Boot Diskettes 1. Ensure you are logged on to the LAN by issuing the following commands to start the LAN requester service: v For OS/2, Version 4.0 type: net share v For OS/2, Version 4.5 type: logon root /P:passwd /V:LOCAL 2. From the toolbar, click Tools->Create Boot Diskettes. The Create Boot Diskettes dialog is displayed. 3. If requested, place one of the diskettes you created in Step 5: Preparing the System Diskettes on page 344, into the diskette drive. 4. Complete the following fields: Server name Client boot drive Client source drive Client log drive Hostname of the code server Drive letter of the drive from which the pristine system will normally boot up Drive letter of the drive to which the shared code server folder will be mapped Drive letter of the drive to which the code server log will be mapped These value should correspond to those supplied in the above utilities. 5. Click OK. The pristine tool completes the preparation of the code server object configuration, and, if necessary, writes data also to the system diskette. Step 7: Running a Pristine Installation When you have completed the preparation of the set of pristine boot diskettes for a system or group of systems (see Step 6: Creating Pristine Boot Diskettes on page 345), you can commence a pristine installation. The installation procedure carries out the following operations: v It uses the boot diskettes to start up the pristine system and load a minimum system configuration into memory v It installs the necessary protocols to connect itself into the network and to locate the code server v Using the configuration information it partitions the hard disks and commences to download and install the operating system software, using the response file to drive the installation v Each system, or group of systems is assigned to a dedicated Tivoli gateway v If the Code Server Object configuration contains a Reference Model, and on the gateway a specific Login-Policy has been activated, a Change Manager operation will be started When these activities are completed, the new endpoint must be migrated from the dedicated pristine gateway to a normal gateway. Pristine Installation Procedure At least one person must be present where the pristine systems are located. The tasks executed locally are: v Starting the system v Removing the diskettes when necessary v Restarting the system if required 346 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

367 Pristine Installations on OS/2: Running Installation Once the diskettes are ready and delivered to the person performing the local installation, the installation process can begin. When the first Tivoli management agent login is connected, an automatic notification of the presence of a new machine in the Tivoli management region takes place. If you have defined a reference model you should ensure that the Change Manager component is installed, in order to compare the new system to the appropriate reference model and to start the specific action. This action completes the pristine installation process. Note: If you want to use a reference model to install Software Distribution, you should remember to install any prerequisite software. The final step is for the pristine system administrator, who must, after all installation processes are completed, migrate the new endpoint from the dedicated pristine gateway to a normal gateway. Appendix C. Pristine Installations 347

368 348 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

369 Appendix D. Authorization Roles This appendix contains tables that describe the roles you need to perform Software Distribution operations. To perform system administration operations from within the Tivoli environment, you must be a Tivoli administrator. Depending on the operations you are required to perform, you can have one or more of the following roles: v Super v Senior v Admin v User v Install-product Setting Up Software Distribution Profiles The following table lists the roles required to set up software package profiles: Table 21. Required roles for setting up software package profiles Operation Context Required Role Install Software Distribution Desktop view for root super or install-product Create a software package profile Clone a software package profile View a software package profile Subscribe resources to a profile manager Profile manager Profile manager Software package Profile manager policy region AND Subscriber policy region senior or super senior or super user, admin, senior, or super admin, senior, or super Defining and Deleting Profiles The following table lists the roles required to define a software package by setting its properties and to view configuration information: Table 22. Required roles for setting software package properties and viewing configuration information Operation Context Required Role Export a software package definition file Set or edit software package profile properties Import a software package definition file Delete a software package profile Software package Software package Software package Software package user, admin, senior, or super admin, senior, or super admin, senior, or super senior or super Copyright IBM Corp. 2002,

370 Defining and Deleting Profiles Table 22. Required roles for setting software package properties and viewing configuration information (continued) Operation Context Required Role View a software package profile (using the Software Package Editor) Modify a software package profile (using the Software Package Editor) Software package Software package admin, senior, or super senior, or super Performing Operations The following table lists the role required to distribute a software package: Table 23. Required roles to distribute software packages Operation Context Required Role Distribute a software package profile Schedule a software package profile distribution Calculate the size of a software package profile Remove a software package profile from a subscriber Profile manager policy region Profile manager policy region Profile manager policy region Software package admin, senior, or super admin, senior, or super user, admin, senior, or super admin, senior, or super 350 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

371 Notices This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user s responsibility to evaluate and verify the operation of any non-ibm product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents.you can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY U.S.A. For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to: IBM World Trade Asia Corporation Licensing 2-31 Roppongi 3-chome, Minato-ku Tokyo 106, Japan The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement might not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-ibm Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. Copyright IBM Corp. 2002,

372 IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact: IBM Corporation 2Z4A/ Burnet Road Austin, TX U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases payment of a fee. The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us. Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurement may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment. Information concerning non-ibm products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-ibm products. Questions on the capabilities of non-ibm products should be addressed to the suppliers of those products. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. If you are viewing this information in softcopy form, the photographs and color illustrations might not display. Trademarks IBM, the IBM logo, Tivoli, the Tivoli logo, Tivoli Enterprise, Tivoli Enterprise Console, NetView, Wake on LAN, AIX, AS/400, DB2, OS/2, and OS/400 are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both. Information concerning non-ibm products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of 352 IBM Tivoli Configuration Manager: User s Guide for Software Distribution

373 performance, compatibility or any other claims related to non-ibm products. Questions on the capabilities of non-ibm products should be addressed to the suppliers of those products. Microsoft, Windows, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. Other company, product, and service names may be trademarks or service marks of others. Notices 353